help: reuse print_columns() for help -a
[git/git.git] / Documentation / git-branch.txt
CommitLineData
215a7ad1
JH
1git-branch(1)
2=============
7fc9d69f
JH
3
4NAME
5----
c3f0baac 6git-branch - List, create, or delete branches
7fc9d69f
JH
7
8SYNOPSIS
9--------
dd181119 10[verse]
73e9da01 11'git branch' [--color[=<when>] | --no-color] [-r | -a]
cddd127b 12 [--list] [-v [--abbrev=<length> | --no-abbrev]]
d8d33736 13 [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...]
4fc50066 14'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
b1889c36
JN
15'git branch' (-m | -M) [<oldbranch>] <newbranch>
16'git branch' (-d | -D) [-r] <branchname>...
b7200e83 17'git branch' --edit-description [<branchname>]
7fc9d69f
JH
18
19DESCRIPTION
20-----------
049716b3 21
e5ac1217 22With no arguments, existing branches are listed and the current branch will
049716b3 23be highlighted with an asterisk. Option `-r` causes the remote-tracking
cddd127b 24branches to be listed, and option `-a` shows both. This list mode is also
7b787599 25activated by the `--list` option (see below).
d8d33736
MG
26<pattern> restricts the output to matching branches, the pattern is a shell
27wildcard (i.e., matched using fnmatch(3))
28Multiple patterns may be given; if any of them matches, the tag is shown.
049716b3 29
e5ac1217
DM
30With `--contains`, shows only the branches that contain the named commit
31(in other words, the branches whose tip commits are descendants of the
049716b3
JH
32named commit). With `--merged`, only branches merged into the named
33commit (i.e. the branches whose tip commits are reachable from the named
34commit) will be listed. With `--no-merged` only branches not merged into
e5ac1217
DM
35the named commit will be listed. If the <commit> argument is missing it
36defaults to 'HEAD' (i.e. the tip of the current branch).
7fc9d69f 37
bb35f35e
JN
38The command's second form creates a new branch head named <branchname>
39which points to the current 'HEAD', or <start-point> if given.
2eaf273d 40
46749204
FMQ
41Note that this will create the new branch, but it will not switch the
42working tree to it; use "git checkout <newbranch>" to switch to the
43new branch.
44
29b9a66f 45When a local branch is started off a remote-tracking branch, git sets up the
0b444cdb 46branch so that 'git pull' will appropriately merge from
29b9a66f 47the remote-tracking branch. This behavior may be changed via the global
572fc81d 48`branch.autosetupmerge` configuration flag. That setting can be
4eec6f98
MM
49overridden by using the `--track` and `--no-track` options, and
50changed later using `git branch --set-upstream`.
0746d19a 51
c976d415
LH
52With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
53If <oldbranch> had a corresponding reflog, it is renamed to match
54<newbranch>, and a reflog entry is created to remember the branch
55renaming. If <newbranch> exists, -M must be used to force the rename
56to happen.
57
2eaf273d 58With a `-d` or `-D` option, `<branchname>` will be deleted. You may
3a4b3f26 59specify more than one branch for deletion. If the branch currently
1e72a40d
JH
60has a reflog then the reflog will also be deleted.
61
62Use -r together with -d to delete remote-tracking branches. Note, that it
63only makes sense to delete remote-tracking branches if they no longer exist
0b444cdb 64in the remote repository or if 'git fetch' was configured not to fetch
e5ac1217
DM
65them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a
66way to clean up all obsolete remote-tracking branches.
dd181119
JL
67
68
7fc9d69f
JH
69OPTIONS
70-------
d4072c97 71-d::
171edcbb 72--delete::
fff0d0ab
JN
73 Delete a branch. The branch must be fully merged in its
74 upstream branch, or in `HEAD` if no upstream was set with
75 `--track` or `--set-upstream`.
d4072c97
AE
76
77-D::
1e72a40d 78 Delete a branch irrespective of its merged status.
d4072c97 79
3a4b3f26 80-l::
171edcbb 81--create-reflog::
792d2370
JK
82 Create the branch's reflog. This activates recording of
83 all changes made to the branch ref, enabling use of date
967506bb 84 based sha1 expressions such as "<branchname>@\{yesterday}".
4c35f0db
JK
85 Note that in non-bare repositories, reflogs are usually
86 enabled by default by the `core.logallrefupdates` config option.
3a4b3f26 87
075dd8ee 88-f::
f7aec129 89--force::
fcfdf797 90 Reset <branchname> to <startpoint> if <branchname> exists
0b444cdb 91 already. Without `-f` 'git branch' refuses to change an existing branch.
2eaf273d 92
c976d415 93-m::
171edcbb 94--move::
c976d415
LH
95 Move/rename a branch and the corresponding reflog.
96
97-M::
e5ac1217 98 Move/rename a branch even if the new branch name already exists.
c976d415 99
73e9da01 100--color[=<when>]::
29b9a66f
MM
101 Color branches to highlight current, local, and
102 remote-tracking branches.
73e9da01 103 The value must be always (the default), never, or auto.
f3673988
BG
104
105--no-color::
106 Turn off branch colors, even when the configuration file gives the
107 default to color output.
73e9da01 108 Same as `--color=never`.
f3673988 109
2eaf273d 110-r::
171edcbb 111--remotes::
7dda22e3 112 List or delete (if used with -d) the remote-tracking branches.
bfcc9214
AP
113
114-a::
171edcbb 115--all::
bfcc9214 116 List both remote-tracking branches and local branches.
075dd8ee 117
cddd127b 118--list::
d8d33736
MG
119 Activate the list mode. `git branch <pattern>` would try to create a branch,
120 use `git branch --list <pattern>` to list matching branches.
cddd127b 121
3240240f
SB
122-v::
123--verbose::
7b787599
MG
124 When in list mode,
125 show sha1 and commit subject line for each head, along with
2d8a7f0b
JK
126 relationship to upstream branch (if any). If given twice, print
127 the name of the upstream branch, as well.
75e6e213
LH
128
129--abbrev=<length>::
e5ac1217 130 Alter the sha1's minimum display length in the output listing.
b792c067
NK
131 The default value is 7 and can be overridden by the `core.abbrev`
132 config option.
75e6e213 133
5e00f6fa 134--no-abbrev::
e5ac1217 135 Display the full sha1s in the output listing rather than abbreviating them.
5e00f6fa 136
be427d75 137-t::
84d176ce 138--track::
167d7445
JK
139 When creating a new branch, set up configuration to mark the
140 start-point branch as "upstream" from the new branch. This
141 configuration will tell git to show the relationship between the
142 two branches in `git status` and `git branch -v`. Furthermore,
143 it directs `git pull` without arguments to pull from the
144 upstream when the new branch is checked out.
145+
29b9a66f 146This behavior is the default when the start point is a remote-tracking branch.
167d7445
JK
147Set the branch.autosetupmerge configuration variable to `false` if you
148want `git checkout` and `git branch` to always behave as if '--no-track'
149were given. Set it to `always` if you want this behavior when the
29b9a66f 150start-point is either a local or remote-tracking branch.
84d176ce
FMQ
151
152--no-track::
167d7445 153 Do not set up "upstream" configuration, even if the
70e96647 154 branch.autosetupmerge configuration variable is true.
84d176ce 155
4fc50066
IL
156--set-upstream::
157 If specified branch does not exist yet or if '--force' has been
158 given, acts exactly like '--track'. Otherwise sets up configuration
159 like '--track' would when creating the branch, except that where
160 branch points to is not changed.
161
b7200e83
JH
162--edit-description::
163 Open an editor and edit the text to explain what the branch is
164 for, to be used by various other commands (e.g. `request-pull`).
165
9a7ea2b1
LH
166--contains <commit>::
167 Only list branches which contain the specified commit.
168
58d2c961
JN
169--merged [<commit>]::
170 Only list branches whose tips are reachable from the
171 specified commit (HEAD if not specified).
9a7ea2b1 172
58d2c961
JN
173--no-merged [<commit>]::
174 Only list branches whose tips are not reachable from the
175 specified commit (HEAD if not specified).
9a7ea2b1 176
52a22d1e 177<branchname>::
d4072c97 178 The name of the branch to create or delete.
2b1f4247 179 The new branch name must pass all checks defined by
5162e697 180 linkgit:git-check-ref-format[1]. Some of these checks
2b1f4247 181 may restrict the characters allowed in a branch name.
7fc9d69f 182
075dd8ee 183<start-point>::
bb35f35e
JN
184 The new branch head will point to this commit. It may be
185 given as a branch name, a commit-id, or a tag. If this
186 option is omitted, the current HEAD will be used instead.
2eaf273d 187
c976d415
LH
188<oldbranch>::
189 The name of an existing branch to rename.
190
191<newbranch>::
192 The new name for an existing branch. The same restrictions as for
e5ac1217 193 <branchname> apply.
7fc9d69f 194
1e2ccd3a
JH
195
196Examples
2eaf273d 197--------
1e2ccd3a 198
e5ac1217 199Start development from a known tag::
1e2ccd3a
JH
200+
201------------
202$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
203$ cd my2.6
2eaf273d 204$ git branch my2.6.14 v2.6.14 <1>
1e2ccd3a 205$ git checkout my2.6.14
1e2ccd3a 206------------
2eaf273d
SE
207+
208<1> This step and the next one could be combined into a single step with
209"checkout -b my2.6.14 v2.6.14".
1e2ccd3a 210
e5ac1217 211Delete an unneeded branch::
1e2ccd3a
JH
212+
213------------
214$ git clone git://git.kernel.org/.../git.git my.git
215$ cd my.git
33b1f3d5
FM
216$ git branch -d -r origin/todo origin/html origin/man <1>
217$ git branch -D test <2>
2eaf273d
SE
218------------
219+
e5ac1217
DM
220<1> Delete the remote-tracking branches "todo", "html" and "man". The next
221'fetch' or 'pull' will create them again unless you configure them not to.
222See linkgit:git-fetch[1].
223<2> Delete the "test" branch even if the "master" branch (or whichever branch
224is currently checked out) does not have all commits from the test branch.
2eaf273d
SE
225
226
227Notes
228-----
229
e5ac1217 230If you are creating a branch that you want to checkout immediately, it is
2eaf273d
SE
231easier to use the git checkout command with its `-b` option to create
232a branch and check it out with a single command.
233
e5ac1217 234The options `--contains`, `--merged` and `--no-merged` serve three related
9a7ea2b1
LH
235but different purposes:
236
237- `--contains <commit>` is used to find all branches which will need
238 special attention if <commit> were to be rebased or amended, since those
239 branches contain the specified <commit>.
240
241- `--merged` is used to find all branches which can be safely deleted,
242 since those branches are fully contained by HEAD.
243
244- `--no-merged` is used to find branches which are candidates for merging
245 into HEAD, since those branches are not fully contained by HEAD.
1e2ccd3a 246
b85e6c5f
NS
247SEE ALSO
248--------
249linkgit:git-check-ref-format[1],
250linkgit:git-fetch[1],
bb35f35e
JN
251linkgit:git-remote[1],
252link:user-manual.html#what-is-a-branch[``Understanding history: What is
253a branch?''] in the Git User's Manual.
b85e6c5f 254
7fc9d69f
JH
255GIT
256---
9e1f0a85 257Part of the linkgit:git[1] suite