edd8f6463ebab38f950db634e28fe5f06cf3915a
[git/git.git] / Documentation / git-show-branch.txt
1 git-show-branch(1)
2 ==================
3
4 NAME
5 ----
6 git-show-branch - Show branches and their commits
7
8 SYNOPSIS
9 --------
10 [verse]
11 'git show-branch' [--all] [--remotes] [--topo-order] [--current]
12 [--more=<n> | --list | --independent | --merge-base]
13 [--color | --no-color]
14 [--no-name | --sha1-name] [--topics] [<rev> | <glob>]...
15 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
16
17 DESCRIPTION
18 -----------
19
20 Shows the commit ancestry graph starting from the commits named
21 with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads
22 and/or $GIT_DIR/refs/tags) semi-visually.
23
24 It cannot show more than 29 branches and commits at a time.
25
26 It uses `showbranch.default` multi-valued configuration items if
27 no <rev> nor <glob> is given on the command line.
28
29
30 OPTIONS
31 -------
32 <rev>::
33 Arbitrary extended SHA1 expression (see linkgit:git-rev-parse[1])
34 that typically names a branch head or a tag.
35
36 <glob>::
37 A glob pattern that matches branch or tag names under
38 $GIT_DIR/refs. For example, if you have many topic
39 branches under $GIT_DIR/refs/heads/topic, giving
40 `topic/*` would show all of them.
41
42 -r::
43 --remotes::
44 Show the remote-tracking branches.
45
46 -a::
47 --all::
48 Show both remote-tracking branches and local branches.
49
50 --current::
51 With this option, the command includes the current
52 branch to the list of revs to be shown when it is not
53 given on the command line.
54
55 --topo-order::
56 By default, the branches and their commits are shown in
57 reverse chronological order. This option makes them
58 appear in topological order (i.e., descendant commits
59 are shown before their parents).
60
61 --sparse::
62 By default, the output omits merges that are reachable
63 from only one tip being shown. This option makes them
64 visible.
65
66 --more=<n>::
67 Usually the command stops output upon showing the commit
68 that is the common ancestor of all the branches. This
69 flag tells the command to go <n> more common commits
70 beyond that. When <n> is negative, display only the
71 <reference>s given, without showing the commit ancestry
72 tree.
73
74 --list::
75 Synonym to `--more=-1`
76
77 --merge-base::
78 Instead of showing the commit list, just act like the
79 'git-merge-base -a' command, except that it can accept
80 more than two heads.
81
82 --independent::
83 Among the <reference>s given, display only the ones that
84 cannot be reached from any other <reference>.
85
86 --no-name::
87 Do not show naming strings for each commit.
88
89 --sha1-name::
90 Instead of naming the commits using the path to reach
91 them from heads (e.g. "master~2" to mean the grandparent
92 of "master"), name them with the unique prefix of their
93 object names.
94
95 --topics::
96 Shows only commits that are NOT on the first branch given.
97 This helps track topic branches by hiding any commit that
98 is already in the main line of development. When given
99 "git show-branch --topics master topic1 topic2", this
100 will show the revisions given by "git rev-list {caret}master
101 topic1 topic2"
102
103 -g::
104 --reflog[=<n>[,<base>]] [<ref>]::
105 Shows <n> most recent ref-log entries for the given
106 ref. If <base> is given, <n> entries going back from
107 that entry. <base> can be specified as count or date.
108 When no explicit <ref> parameter is given, it defaults to the
109 current branch (or `HEAD` if it is detached).
110
111 --color::
112 Color the status sign (one of these: `*` `!` `+` `-`) of each commit
113 corresponding to the branch it's in.
114
115 --no-color::
116 Turn off colored output, even when the configuration file gives the
117 default to color output.
118
119 Note that --more, --list, --independent and --merge-base options
120 are mutually exclusive.
121
122
123 OUTPUT
124 ------
125 Given N <references>, the first N lines are the one-line
126 description from their commit message. The branch head that is
127 pointed at by $GIT_DIR/HEAD is prefixed with an asterisk `*`
128 character while other heads are prefixed with a `!` character.
129
130 Following these N lines, one-line log for each commit is
131 displayed, indented N places. If a commit is on the I-th
132 branch, the I-th indentation character shows a `+` sign;
133 otherwise it shows a space. Merge commits are denoted by
134 a `-` sign. Each commit shows a short name that
135 can be used as an extended SHA1 to name that commit.
136
137 The following example shows three branches, "master", "fixes"
138 and "mhf":
139
140 ------------------------------------------------
141 $ git show-branch master fixes mhf
142 * [master] Add 'git show-branch'.
143 ! [fixes] Introduce "reset type" flag to "git reset"
144 ! [mhf] Allow "+remote:local" refspec to cause --force when fetching.
145 ---
146 + [mhf] Allow "+remote:local" refspec to cause --force when fetching.
147 + [mhf~1] Use git-octopus when pulling more than one heads.
148 + [fixes] Introduce "reset type" flag to "git reset"
149 + [mhf~2] "git fetch --force".
150 + [mhf~3] Use .git/remote/origin, not .git/branches/origin.
151 + [mhf~4] Make "git pull" and "git fetch" default to origin
152 + [mhf~5] Infamous 'octopus merge'
153 + [mhf~6] Retire git-parse-remote.
154 + [mhf~7] Multi-head fetch.
155 + [mhf~8] Start adding the $GIT_DIR/remotes/ support.
156 *++ [master] Add 'git show-branch'.
157 ------------------------------------------------
158
159 These three branches all forked from a common commit, [master],
160 whose commit message is "Add \'git show-branch\'". The "fixes"
161 branch adds one commit "Introduce "reset type" flag to "git reset"".
162 The "mhf" branch adds many other commits. The current branch
163 is "master".
164
165
166 EXAMPLE
167 -------
168
169 If you keep your primary branches immediately under
170 `$GIT_DIR/refs/heads`, and topic branches in subdirectories of
171 it, having the following in the configuration file may help:
172
173 ------------
174 [showbranch]
175 default = --topo-order
176 default = heads/*
177
178 ------------
179
180 With this, `git show-branch` without extra parameters would show
181 only the primary branches. In addition, if you happen to be on
182 your topic branch, it is shown as well.
183
184 ------------
185 $ git show-branch --reflog="10,1 hour ago" --list master
186 ------------
187
188 shows 10 reflog entries going back from the tip as of 1 hour ago.
189 Without `--list`, the output also shows how these tips are
190 topologically related with each other.
191
192
193 Author
194 ------
195 Written by Junio C Hamano <gitster@pobox.com>
196
197
198 Documentation
199 --------------
200 Documentation by Junio C Hamano.
201
202
203 GIT
204 ---
205 Part of the linkgit:git[1] suite