documentation: convert "diffcore" and "repository-layout" to man pages
[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]
e8b404c2 11'git-branch' [--color | --no-color] [-r | -a] [--merged | --no-merged]
5e00f6fa 12 [-v [--abbrev=<length> | --no-abbrev]]
3f7dfe77 13 [--contains <commit>]
0746d19a 14'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
c976d415 15'git-branch' (-m | -M) [<oldbranch>] <newbranch>
7dda22e3 16'git-branch' (-d | -D) [-r] <branchname>...
7fc9d69f
JH
17
18DESCRIPTION
19-----------
bfcc9214 20With no arguments given a list of existing branches
2eaf273d 21will be shown, the current branch will be highlighted with an asterisk.
bfcc9214
AP
22Option `-r` causes the remote-tracking branches to be listed,
23and option `-a` shows both.
3f7dfe77
JH
24With `--contains <commit>`, shows only the branches that
25contains the named commit (in other words, the branches whose
26tip commits are descendant of the named commit).
e8b404c2
LH
27With `--merged`, only branches merged into HEAD will be listed, and
28with `--no-merged` only branches not merged into HEAD will be listed.
7fc9d69f 29
2eaf273d
SE
30In its second form, a new branch named <branchname> will be created.
31It will start out with a head equal to the one given as <start-point>.
32If no <start-point> is given, the branch will be created with a head
33equal to that of the currently checked out branch.
34
46749204
FMQ
35Note that this will create the new branch, but it will not switch the
36working tree to it; use "git checkout <newbranch>" to switch to the
37new branch.
38
572fc81d
JS
39When a local branch is started off a remote branch, git sets up the
40branch so that linkgit:git-pull[1] will appropriately merge from
41the remote branch. This behavior may be changed via the global
42`branch.autosetupmerge` configuration flag. That setting can be
43overridden by using the `--track` and `--no-track` options.
0746d19a 44
c976d415
LH
45With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
46If <oldbranch> had a corresponding reflog, it is renamed to match
47<newbranch>, and a reflog entry is created to remember the branch
48renaming. If <newbranch> exists, -M must be used to force the rename
49to happen.
50
2eaf273d 51With a `-d` or `-D` option, `<branchname>` will be deleted. You may
3a4b3f26 52specify more than one branch for deletion. If the branch currently
1e72a40d
JH
53has a reflog then the reflog will also be deleted.
54
55Use -r together with -d to delete remote-tracking branches. Note, that it
56only makes sense to delete remote-tracking branches if they no longer exist
5162e697
DM
57in remote repository or if linkgit:git-fetch[1] was configured not to fetch
58them again. See also 'prune' subcommand of linkgit:git-remote[1] for way to
1e72a40d 59clean up all obsolete remote-tracking branches.
dd181119
JL
60
61
7fc9d69f
JH
62OPTIONS
63-------
d4072c97 64-d::
1e72a40d 65 Delete a branch. The branch must be fully merged in HEAD.
d4072c97
AE
66
67-D::
1e72a40d 68 Delete a branch irrespective of its merged status.
d4072c97 69
3a4b3f26 70-l::
792d2370
JK
71 Create the branch's reflog. This activates recording of
72 all changes made to the branch ref, enabling use of date
967506bb 73 based sha1 expressions such as "<branchname>@\{yesterday}".
3a4b3f26 74
075dd8ee 75-f::
2eaf273d
SE
76 Force the creation of a new branch even if it means deleting
77 a branch that already exists with the same name.
78
c976d415
LH
79-m::
80 Move/rename a branch and the corresponding reflog.
81
82-M::
83 Move/rename a branch even if the new branchname already exists.
84
f3673988
BG
85--color::
86 Color branches to highlight current, local, and remote branches.
87
88--no-color::
89 Turn off branch colors, even when the configuration file gives the
90 default to color output.
91
2eaf273d 92-r::
7dda22e3 93 List or delete (if used with -d) the remote-tracking branches.
bfcc9214
AP
94
95-a::
96 List both remote-tracking branches and local branches.
075dd8ee 97
e0e6c096 98-v, --verbose::
23bfbb81 99 Show sha1 and commit subject line for each head.
75e6e213
LH
100
101--abbrev=<length>::
102 Alter minimum display length for sha1 in output listing,
103 default value is 7.
104
5e00f6fa
JP
105--no-abbrev::
106 Display the full sha1s in output listing rather than abbreviating them.
107
84d176ce 108--track::
572fc81d
JS
109 When creating a new branch, set up configuration so that git-pull
110 will automatically retrieve data from the start point, which must be
111 a branch. Use this if you always pull from the same upstream branch
112 into the new branch, and if you don't want to use "git pull
113 <repository> <refspec>" explicitly. This behavior is the default
114 when the start point is a remote branch. Set the
115 branch.autosetupmerge configuration variable to `false` if you want
116 git-checkout and git-branch to always behave as if '--no-track' were
117 given. Set it to `always` if you want this behavior when the
118 start-point is either a local or remote branch.
84d176ce
FMQ
119
120--no-track::
572fc81d 121 Ignore the branch.autosetupmerge configuration variable.
84d176ce 122
9a7ea2b1
LH
123--contains <commit>::
124 Only list branches which contain the specified commit.
125
126--merged::
127 Only list branches which are fully contained by HEAD.
128
129--no-merged::
130 Do not list branches which are fully contained by HEAD.
131
52a22d1e 132<branchname>::
d4072c97 133 The name of the branch to create or delete.
2b1f4247 134 The new branch name must pass all checks defined by
5162e697 135 linkgit:git-check-ref-format[1]. Some of these checks
2b1f4247 136 may restrict the characters allowed in a branch name.
7fc9d69f 137
075dd8ee 138<start-point>::
2eaf273d
SE
139 The new branch will be created with a HEAD equal to this. It may
140 be given as a branch name, a commit-id, or a tag. If this option
141 is omitted, the current branch is assumed.
142
c976d415
LH
143<oldbranch>::
144 The name of an existing branch to rename.
145
146<newbranch>::
147 The new name for an existing branch. The same restrictions as for
148 <branchname> applies.
7fc9d69f 149
1e2ccd3a
JH
150
151Examples
2eaf273d 152--------
1e2ccd3a 153
dd181119 154Start development off of a known tag::
1e2ccd3a
JH
155+
156------------
157$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
158$ cd my2.6
2eaf273d 159$ git branch my2.6.14 v2.6.14 <1>
1e2ccd3a 160$ git checkout my2.6.14
1e2ccd3a 161------------
2eaf273d
SE
162+
163<1> This step and the next one could be combined into a single step with
164"checkout -b my2.6.14 v2.6.14".
1e2ccd3a
JH
165
166Delete unneeded branch::
167+
168------------
169$ git clone git://git.kernel.org/.../git.git my.git
170$ cd my.git
33b1f3d5
FM
171$ git branch -d -r origin/todo origin/html origin/man <1>
172$ git branch -D test <2>
2eaf273d
SE
173------------
174+
1e72a40d
JH
175<1> Delete remote-tracking branches "todo", "html", "man". Next 'fetch' or
176'pull' will create them again unless you configure them not to. See
5162e697 177linkgit:git-fetch[1].
1e72a40d
JH
178<2> Delete "test" branch even if the "master" branch (or whichever branch is
179currently checked out) does not have all commits from test branch.
2eaf273d
SE
180
181
182Notes
183-----
184
185If you are creating a branch that you want to immediately checkout, it's
186easier to use the git checkout command with its `-b` option to create
187a branch and check it out with a single command.
188
9a7ea2b1
LH
189The options `--contains`, `--merged` and `--no-merged` serves three related
190but different purposes:
191
192- `--contains <commit>` is used to find all branches which will need
193 special attention if <commit> were to be rebased or amended, since those
194 branches contain the specified <commit>.
195
196- `--merged` is used to find all branches which can be safely deleted,
197 since those branches are fully contained by HEAD.
198
199- `--no-merged` is used to find branches which are candidates for merging
200 into HEAD, since those branches are not fully contained by HEAD.
1e2ccd3a 201
7fc9d69f
JH
202Author
203------
204Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>
205
206Documentation
207--------------
208Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
209
210GIT
211---
5162e697 212Part of the linkgit:git[7] suite