man1/git-show-branch.1

   1 '\" t
   2 .\"     Title: git-show-branch
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2024-02-27
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.44.0.53.g0f9d4d28b7
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-SHOW\-BRANCH" "1" "2024\-02\-27" "Git 2\&.44\&.0\&.53\&.g0f9d4d2" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-show-branch \- Show branches and their commits
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit show\-branch\fR [\-a | \-\-all] [\-r | \-\-remotes] [\-\-topo\-order | \-\-date\-order]
  36                 [\-\-current] [\-\-color[=<when>] | \-\-no\-color] [\-\-sparse]
  37                 [\-\-more=<n> | \-\-list | \-\-independent | \-\-merge\-base]
  38                 [\-\-no\-name | \-\-sha1\-name] [\-\-topics]
  39                 [(<rev> | <glob>)\&...]
  40 \fIgit show\-branch\fR (\-g | \-\-reflog)[=<n>[,<base>]] [\-\-list] [<ref>]
  41 .fi
  42 .sp
  43 .SH "DESCRIPTION"
  44 .sp
  45 Shows the commit ancestry graph starting from the commits named with <rev>s or <glob>s (or all refs under refs/heads and/or refs/tags) semi\-visually\&.
  46 .sp
  47 It cannot show more than 29 branches and commits at a time\&.
  48 .sp
  49 It uses \fBshowbranch\&.default\fR multi\-valued configuration items if no <rev> or <glob> is given on the command line\&.
  50 .SH "OPTIONS"
  51 .PP
  52 <rev>
  53 .RS 4
  54 Arbitrary extended SHA\-1 expression (see
  55 \fBgitrevisions\fR(7)) that typically names a branch head or a tag\&.
  56 .RE
  57 .PP
  58 <glob>
  59 .RS 4
  60 A glob pattern that matches branch or tag names under refs/\&. For example, if you have many topic branches under refs/heads/topic, giving
  61 \fBtopic/*\fR
  62 would show all of them\&.
  63 .RE
  64 .PP
  65 \-r, \-\-remotes
  66 .RS 4
  67 Show the remote\-tracking branches\&.
  68 .RE
  69 .PP
  70 \-a, \-\-all
  71 .RS 4
  72 Show both remote\-tracking branches and local branches\&.
  73 .RE
  74 .PP
  75 \-\-current
  76 .RS 4
  77 With this option, the command includes the current branch in the list of revs to be shown when it is not given on the command line\&.
  78 .RE
  79 .PP
  80 \-\-topo\-order
  81 .RS 4
  82 By default, the branches and their commits are shown in reverse chronological order\&. This option makes them appear in topological order (i\&.e\&., descendant commits are shown before their parents)\&.
  83 .RE
  84 .PP
  85 \-\-date\-order
  86 .RS 4
  87 This option is similar to
  88 \fB\-\-topo\-order\fR
  89 in the sense that no parent comes before all of its children, but otherwise commits are ordered according to their commit date\&.
  90 .RE
  91 .PP
  92 \-\-sparse
  93 .RS 4
  94 By default, the output omits merges that are reachable from only one tip being shown\&. This option makes them visible\&.
  95 .RE
  96 .PP
  97 \-\-more=<n>
  98 .RS 4
  99 Usually the command stops output upon showing the commit that is the common ancestor of all the branches\&. This flag tells the command to go <n> more common commits beyond that\&. When <n> is negative, display only the <ref>s given, without showing the commit ancestry tree\&.
 100 .RE
 101 .PP
 102 \-\-list
 103 .RS 4
 104 Synonym to
 105 \fB\-\-more=\-1\fR
 106 .RE
 107 .PP
 108 \-\-merge\-base
 109 .RS 4
 110 Instead of showing the commit list, determine possible merge bases for the specified commits\&. All merge bases will be contained in all specified commits\&. This is different from how
 111 \fBgit-merge-base\fR(1)
 112 handles the case of three or more commits\&.
 113 .RE
 114 .PP
 115 \-\-independent
 116 .RS 4
 117 Among the <ref>s given, display only the ones that cannot be reached from any other <ref>\&.
 118 .RE
 119 .PP
 120 \-\-no\-name
 121 .RS 4
 122 Do not show naming strings for each commit\&.
 123 .RE
 124 .PP
 125 \-\-sha1\-name
 126 .RS 4
 127 Instead of naming the commits using the path to reach them from heads (e\&.g\&. "master~2" to mean the grandparent of "master"), name them with the unique prefix of their object names\&.
 128 .RE
 129 .PP
 130 \-\-topics
 131 .RS 4
 132 Shows only commits that are NOT on the first branch given\&. This helps track topic branches by hiding any commit that is already in the main line of development\&. When given "git show\-branch \-\-topics master topic1 topic2", this will show the revisions given by "git rev\-list ^master topic1 topic2"
 133 .RE
 134 .PP
 135 \-g, \-\-reflog[=<n>[,<base>]] [<ref>]
 136 .RS 4
 137 Shows <n> most recent ref\-log entries for the given ref\&. If <base> is given, <n> entries going back from that entry\&. <base> can be specified as count or date\&. When no explicit <ref> parameter is given, it defaults to the current branch (or
 138 \fBHEAD\fR
 139 if it is detached)\&.
 140 .RE
 141 .PP
 142 \-\-color[=<when>]
 143 .RS 4
 144 Color the status sign (one of these:
 145 \fB*\fR
 146 \fB!\fR
 147 \fB+\fR
 148 \fB\-\fR) of each commit corresponding to the branch it\(cqs in\&. The value must be always (the default), never, or auto\&.
 149 .RE
 150 .PP
 151 \-\-no\-color
 152 .RS 4
 153 Turn off colored output, even when the configuration file gives the default to color output\&. Same as
 154 \fB\-\-color=never\fR\&.
 155 .RE
 156 .sp
 157 Note that \-\-more, \-\-list, \-\-independent, and \-\-merge\-base options are mutually exclusive\&.
 158 .SH "OUTPUT"
 159 .sp
 160 Given N <ref>s, the first N lines are the one\-line description from their commit message\&. The branch head that is pointed at by $GIT_DIR/HEAD is prefixed with an asterisk \fB*\fR character while other heads are prefixed with a \fB!\fR character\&.
 161 .sp
 162 Following these N lines, a one\-line log for each commit is displayed, indented N places\&. If a commit is on the I\-th branch, the I\-th indentation character shows a \fB+\fR sign; otherwise it shows a space\&. Merge commits are denoted by a \fB\-\fR sign\&. Each commit shows a short name that can be used as an extended SHA\-1 to name that commit\&.
 163 .sp
 164 The following example shows three branches, "master", "fixes", and "mhf":
 165 .sp
 166 .if n \{\
 167 .RS 4
 168 .\}
 169 .nf
 170 $ git show\-branch master fixes mhf
 171 * [master] Add \*(Aqgit show\-branch\*(Aq\&.
 172  ! [fixes] Introduce "reset type" flag to "git reset"
 173   ! [mhf] Allow "+remote:local" refspec to cause \-\-force when fetching\&.
 174 \-\-\-
 175   + [mhf] Allow "+remote:local" refspec to cause \-\-force when fetching\&.
 176   + [mhf~1] Use git\-octopus when pulling more than one head\&.
 177  +  [fixes] Introduce "reset type" flag to "git reset"
 178   + [mhf~2] "git fetch \-\-force"\&.
 179   + [mhf~3] Use \&.git/remote/origin, not \&.git/branches/origin\&.
 180   + [mhf~4] Make "git pull" and "git fetch" default to origin
 181   + [mhf~5] Infamous \*(Aqoctopus merge\*(Aq
 182   + [mhf~6] Retire git\-parse\-remote\&.
 183   + [mhf~7] Multi\-head fetch\&.
 184   + [mhf~8] Start adding the $GIT_DIR/remotes/ support\&.
 185 *++ [master] Add \*(Aqgit show\-branch\*(Aq\&.
 186 .fi
 187 .if n \{\
 188 .RE
 189 .\}
 190 .sp
 191 .sp
 192 These three branches all forked from a common commit, [master], whose commit message is "Add \*(Aqgit show\-branch\*(Aq"\&. The "fixes" branch adds one commit "Introduce "reset type" flag to "git reset""\&. The "mhf" branch adds many other commits\&. The current branch is "master"\&.
 193 .SH "EXAMPLES"
 194 .sp
 195 If you keep your primary branches immediately under \fBrefs/heads\fR, and topic branches in subdirectories of it, having the following in the configuration file may help:
 196 .sp
 197 .if n \{\
 198 .RS 4
 199 .\}
 200 .nf
 201 [showbranch]
 202         default = \-\-topo\-order
 203         default = heads/*
 204 .fi
 205 .if n \{\
 206 .RE
 207 .\}
 208 .sp
 209 .sp
 210 With this, \fBgit show\-branch\fR without extra parameters would show only the primary branches\&. In addition, if you happen to be on your topic branch, it is shown as well\&.
 211 .sp
 212 .if n \{\
 213 .RS 4
 214 .\}
 215 .nf
 216 $ git show\-branch \-\-reflog="10,1 hour ago" \-\-list master
 217 .fi
 218 .if n \{\
 219 .RE
 220 .\}
 221 .sp
 222 .sp
 223 shows 10 reflog entries going back from the tip as of 1 hour ago\&. Without \fB\-\-list\fR, the output also shows how these tips are topologically related to each other\&.
 224 .SH "CONFIGURATION"
 225 .sp
 226 Everything below this line in this section is selectively included from the \fBgit-config\fR(1) documentation\&. The content is the same as what\(cqs found there:
 227 .PP
 228 showBranch\&.default
 229 .RS 4
 230 The default set of branches for
 231 \fBgit-show-branch\fR(1)\&. See
 232 \fBgit-show-branch\fR(1)\&.
 233 .RE
 234 .SH "GIT"
 235 .sp
 236 Part of the \fBgit\fR(1) suite