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