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 v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-10
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.0.551.gc5ee8f2d1c
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-SHOW\-BRANCH" "1" "2024-09-10" "Git 2\&.46\&.0\&.551\&.gc5ee8f" "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 .SH "DESCRIPTION"
  43 .sp
  44 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\&.
  45 .sp
  46 It cannot show more than 26 branches and commits at a time\&.
  47 .sp
  48 It uses \fBshowbranch\&.default\fR multi\-valued configuration items if no <rev> or <glob> is given on the command line\&.
  49 .SH "OPTIONS"
  50 .PP
  51 <rev>
  52 .RS 4
  53 Arbitrary extended SHA\-1 expression (see
  54 \fBgitrevisions\fR(7)) that typically names a branch head or a tag\&.
  55 .RE
  56 .PP
  57 <glob>
  58 .RS 4
  59 A glob pattern that matches branch or tag names under refs/\&. For example, if you have many topic branches under refs/heads/topic, giving
  60 \fBtopic/*\fR
  61 would show all of them\&.
  62 .RE
  63 .PP
  64 \-r, \-\-remotes
  65 .RS 4
  66 Show the remote\-tracking branches\&.
  67 .RE
  68 .PP
  69 \-a, \-\-all
  70 .RS 4
  71 Show both remote\-tracking branches and local branches\&.
  72 .RE
  73 .PP
  74 \-\-current
  75 .RS 4
  76 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\&.
  77 .RE
  78 .PP
  79 \-\-topo\-order
  80 .RS 4
  81 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)\&.
  82 .RE
  83 .PP
  84 \-\-date\-order
  85 .RS 4
  86 This option is similar to
  87 \fB\-\-topo\-order\fR
  88 in the sense that no parent comes before all of its children, but otherwise commits are ordered according to their commit date\&.
  89 .RE
  90 .PP
  91 \-\-sparse
  92 .RS 4
  93 By default, the output omits merges that are reachable from only one tip being shown\&. This option makes them visible\&.
  94 .RE
  95 .PP
  96 \-\-more=<n>
  97 .RS 4
  98 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\&.
  99 .RE
 100 .PP
 101 \-\-list
 102 .RS 4
 103 Synonym to
 104 \fB\-\-more=\-1\fR
 105 .RE
 106 .PP
 107 \-\-merge\-base
 108 .RS 4
 109 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
 110 \fBgit-merge-base\fR(1)
 111 handles the case of three or more commits\&.
 112 .RE
 113 .PP
 114 \-\-independent
 115 .RS 4
 116 Among the <ref>s given, display only the ones that cannot be reached from any other <ref>\&.
 117 .RE
 118 .PP
 119 \-\-no\-name
 120 .RS 4
 121 Do not show naming strings for each commit\&.
 122 .RE
 123 .PP
 124 \-\-sha1\-name
 125 .RS 4
 126 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\&.
 127 .RE
 128 .PP
 129 \-\-topics
 130 .RS 4
 131 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"
 132 .RE
 133 .PP
 134 \-g, \-\-reflog[=<n>[,<base>]] [<ref>]
 135 .RS 4
 136 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
 137 \fBHEAD\fR
 138 if it is detached)\&.
 139 .RE
 140 .PP
 141 \-\-color[=<when>]
 142 .RS 4
 143 Color the status sign (one of these:
 144 \fB*\fR
 145 \fB!\fR
 146 \fB+\fR
 147 \fB\-\fR) of each commit corresponding to the branch it\(cqs in\&. The value must be always (the default), never, or auto\&.
 148 .RE
 149 .PP
 150 \-\-no\-color
 151 .RS 4
 152 Turn off colored output, even when the configuration file gives the default to color output\&. Same as
 153 \fB\-\-color=never\fR\&.
 154 .RE
 155 .sp
 156 Note that \-\-more, \-\-list, \-\-independent, and \-\-merge\-base options are mutually exclusive\&.
 157 .SH "OUTPUT"
 158 .sp
 159 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\&.
 160 .sp
 161 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\&.
 162 .sp
 163 The following example shows three branches, "master", "fixes", and "mhf":
 164 .sp
 165 .if n \{\
 166 .RS 4
 167 .\}
 168 .nf
 169 $ git show\-branch master fixes mhf
 170 * [master] Add \*(Aqgit show\-branch\*(Aq\&.
 171  ! [fixes] Introduce "reset type" flag to "git reset"
 172   ! [mhf] Allow "+remote:local" refspec to cause \-\-force when fetching\&.
 173 \-\-\-
 174   + [mhf] Allow "+remote:local" refspec to cause \-\-force when fetching\&.
 175   + [mhf~1] Use git\-octopus when pulling more than one head\&.
 176  +  [fixes] Introduce "reset type" flag to "git reset"
 177   + [mhf~2] "git fetch \-\-force"\&.
 178   + [mhf~3] Use \&.git/remote/origin, not \&.git/branches/origin\&.
 179   + [mhf~4] Make "git pull" and "git fetch" default to origin
 180   + [mhf~5] Infamous \*(Aqoctopus merge\*(Aq
 181   + [mhf~6] Retire git\-parse\-remote\&.
 182   + [mhf~7] Multi\-head fetch\&.
 183   + [mhf~8] Start adding the $GIT_DIR/remotes/ support\&.
 184 *++ [master] Add \*(Aqgit show\-branch\*(Aq\&.
 185 .fi
 186 .if n \{\
 187 .RE
 188 .\}
 189 .sp
 190 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"\&.
 191 .SH "EXAMPLES"
 192 .sp
 193 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:
 194 .sp
 195 .if n \{\
 196 .RS 4
 197 .\}
 198 .nf
 199 [showbranch]
 200         default = \-\-topo\-order
 201         default = heads/*
 202 .fi
 203 .if n \{\
 204 .RE
 205 .\}
 206 .sp
 207 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\&.
 208 .sp
 209 .if n \{\
 210 .RS 4
 211 .\}
 212 .nf
 213 $ git show\-branch \-\-reflog="10,1 hour ago" \-\-list master
 214 .fi
 215 .if n \{\
 216 .RE
 217 .\}
 218 .sp
 219 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\&.
 220 .SH "CONFIGURATION"
 221 .sp
 222 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:
 223 .PP
 224 showBranch\&.default
 225 .RS 4
 226 The default set of branches for
 227 \fBgit-show-branch\fR(1)\&. See
 228 \fBgit-show-branch\fR(1)\&.
 229 .RE
 230 .SH "GIT"
 231 .sp
 232 Part of the \fBgit\fR(1) suite