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