show-branch: make the current branch and merge commits stand out.
[git/git.git] / Documentation / git-show-branch.txt
CommitLineData
f5e375c9
JH
1git-show-branch(1)
2==================
f5e375c9
JH
3
4NAME
5----
6git-show-branch - Show branches and their commits.
7
8SYNOPSIS
9--------
d4ce5f7e 10'git-show-branch [--all] [--heads] [--tags] [--topo-order] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [<rev> | <glob>]...'
f5e375c9
JH
11
12DESCRIPTION
13-----------
287f8600
JH
14
15Shows the commit ancestry graph starting from the commits named
16with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads
17and/or $GIT_DIR/refs/tags) semi-visually.
18
19It cannot show more than 29 branches and commits at a time.
20
54f9734e
JH
21It uses `showbranch.default` multi-valued configuration items if
22no <rev> nor <glob> is given on the command line.
23
f5e375c9
JH
24
25OPTIONS
26-------
287f8600
JH
27<rev>::
28 Arbitrary extended SHA1 expression (see `git-rev-parse`)
29 that typically names a branch HEAD or a tag.
30
31<glob>::
32 A glob pattern that matches branch or tag names under
33 $GIT_DIR/refs. For example, if you have many topic
34 branches under $GIT_DIR/refs/heads/topic, giving
35 `topic/*` would show all of them.
f5e375c9
JH
36
37--all --heads --tags::
38 Show all refs under $GIT_DIR/refs, $GIT_DIR/refs/heads,
39 and $GIT_DIR/refs/tags, respectively.
40
d4ce5f7e
NW
41--topo-order::
42 By default, the branches and their commits are shown in
43 reverse chronological order. This option makes them
44 appear in topological order (i.e., descendant commits
45 are shown before their parents).
46
f5e375c9
JH
47--more=<n>::
48 Usually the command stops output upon showing the commit
49 that is the common ancestor of all the branches. This
f85a4191 50 flag tells the command to go <n> more common commits
1f8af483
JH
51 beyond that. When <n> is negative, display only the
52 <reference>s given, without showing the commit ancestry
53 tree.
54
55--list::
54f9734e 56 Synonym to `--more=-1`
f5e375c9
JH
57
58--merge-base::
59 Instead of showing the commit list, just act like the
2f0f8b71
JH
60 'git-merge-base -a' command, except that it can accept
61 more than two heads.
f5e375c9 62
1f8af483
JH
63--independent::
64 Among the <reference>s given, display only the ones that
65 cannot be reached from any other <reference>.
66
013f276e
JH
67--no-name::
68 Do not show naming strings for each commit.
69
70--sha1-name::
71 Instead of naming the commits using the path to reach
72 them from heads (e.g. "master~2" to mean the grandparent
73 of "master"), name them with the unique prefix of their
74 object names.
75
1f8af483
JH
76Note that --more, --list, --independent and --merge-base options
77are mutually exclusive.
78
f5e375c9
JH
79
80OUTPUT
81------
82Given N <references>, the first N lines are the one-line
83description from their commit message. The branch head that is
ebedc319
JH
84pointed at by $GIT_DIR/HEAD is prefixed with an asterisk `*`
85character while other heads are prefixed with a `!` character.
f5e375c9
JH
86
87Following these N lines, one-line log for each commit is
88displayed, indented N places. If a commit is on the I-th
ebedc319
JH
89branch, the I-th indentation character shows a `+` sign;
90otherwise it shows a space. Merge commits are denoted by
91a `-` sign. Each commit shows a short name that
89438677 92can be used as an extended SHA1 to name that commit.
f5e375c9
JH
93
94The following example shows three branches, "master", "fixes"
95and "mhf":
96
97------------------------------------------------
98$ git show-branch master fixes mhf
ebedc319 99* [master] Add 'git show-branch'.
f5e375c9
JH
100 ! [fixes] Introduce "reset type" flag to "git reset"
101 ! [mhf] Allow "+remote:local" refspec to cause --force when fetching.
102---
103 + [mhf] Allow "+remote:local" refspec to cause --force when fetching.
104 + [mhf~1] Use git-octopus when pulling more than one heads.
105 + [fixes] Introduce "reset type" flag to "git reset"
106 + [mhf~2] "git fetch --force".
107 + [mhf~3] Use .git/remote/origin, not .git/branches/origin.
108 + [mhf~4] Make "git pull" and "git fetch" default to origin
109 + [mhf~5] Infamous 'octopus merge'
110 + [mhf~6] Retire git-parse-remote.
111 + [mhf~7] Multi-head fetch.
112 + [mhf~8] Start adding the $GIT_DIR/remotes/ support.
ebedc319 113*++ [master] Add 'git show-branch'.
f5e375c9
JH
114------------------------------------------------
115
116These three branches all forked from a common commit, [master],
117whose commit message is "Add 'git show-branch'. "fixes" branch
118adds one commit 'Introduce "reset type"'. "mhf" branch has many
ebedc319 119other commits. The current branch is "master".
f5e375c9 120
f5e375c9 121
54f9734e
JH
122EXAMPLE
123-------
124
125If you keep your primary branches immediately under
126`$GIT_DIR/refs/heads`, and topic branches in subdirectories of
127it, having the following in the configuration file may help:
128
129------------
130[showbranch]
131 default = --topo-order
132 default = heads/*
133
134------------
135
136With this,`git show-branch` without extra parameters would show
137only the primary branches.
138
139
140
f5e375c9
JH
141Author
142------
143Written by Junio C Hamano <junkio@cox.net>
144
145
146Documentation
147--------------
148Documentation by Junio C Hamano.
149
150
151GIT
152---
a7154e91 153Part of the gitlink:git[7] suite