Add documentation for --track and --no-track to the git-branch docs.
[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]
5e00f6fa
JP
11'git-branch' [--color | --no-color] [-r | -a]
12 [-v [--abbrev=<length> | --no-abbrev]]
0746d19a 13'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
c976d415 14'git-branch' (-m | -M) [<oldbranch>] <newbranch>
7dda22e3 15'git-branch' (-d | -D) [-r] <branchname>...
7fc9d69f
JH
16
17DESCRIPTION
18-----------
bfcc9214 19With no arguments given a list of existing branches
2eaf273d 20will be shown, the current branch will be highlighted with an asterisk.
bfcc9214
AP
21Option `-r` causes the remote-tracking branches to be listed,
22and option `-a` shows both.
7fc9d69f 23
2eaf273d
SE
24In its second form, a new branch named <branchname> will be created.
25It will start out with a head equal to the one given as <start-point>.
26If no <start-point> is given, the branch will be created with a head
27equal to that of the currently checked out branch.
28
0746d19a
PB
29When a local branch is started off a remote branch, git can setup the
30branch so that gitlink:git-pull[1] will appropriately merge from that
31remote branch. If this behavior is desired, it is possible to make it
32the default using the global `branch.autosetupmerge` configuration
33flag. Otherwise, it can be chosen per-branch using the `--track`
34and `--no-track` options.
35
c976d415
LH
36With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
37If <oldbranch> had a corresponding reflog, it is renamed to match
38<newbranch>, and a reflog entry is created to remember the branch
39renaming. If <newbranch> exists, -M must be used to force the rename
40to happen.
41
2eaf273d 42With a `-d` or `-D` option, `<branchname>` will be deleted. You may
3a4b3f26 43specify more than one branch for deletion. If the branch currently
792d2370 44has a reflog then the reflog will also be deleted. Use -r together with -d
7dda22e3 45to delete remote-tracking branches.
dd181119
JL
46
47
7fc9d69f
JH
48OPTIONS
49-------
d4072c97
AE
50-d::
51 Delete a branch. The branch must be fully merged.
52
53-D::
54 Delete a branch irrespective of its index status.
55
3a4b3f26 56-l::
792d2370
JK
57 Create the branch's reflog. This activates recording of
58 all changes made to the branch ref, enabling use of date
967506bb 59 based sha1 expressions such as "<branchname>@\{yesterday}".
3a4b3f26 60
075dd8ee 61-f::
2eaf273d
SE
62 Force the creation of a new branch even if it means deleting
63 a branch that already exists with the same name.
64
c976d415
LH
65-m::
66 Move/rename a branch and the corresponding reflog.
67
68-M::
69 Move/rename a branch even if the new branchname already exists.
70
f3673988
BG
71--color::
72 Color branches to highlight current, local, and remote branches.
73
74--no-color::
75 Turn off branch colors, even when the configuration file gives the
76 default to color output.
77
2eaf273d 78-r::
7dda22e3 79 List or delete (if used with -d) the remote-tracking branches.
bfcc9214
AP
80
81-a::
82 List both remote-tracking branches and local branches.
075dd8ee 83
75e6e213 84-v::
23bfbb81 85 Show sha1 and commit subject line for each head.
75e6e213
LH
86
87--abbrev=<length>::
88 Alter minimum display length for sha1 in output listing,
89 default value is 7.
90
5e00f6fa
JP
91--no-abbrev::
92 Display the full sha1s in output listing rather than abbreviating them.
93
84d176ce
FMQ
94--track::
95 Set up configuration so that git-pull will automatically
96 retrieve data from the remote branch. Use this if you always
97 pull from the same remote branch into the new branch, or if you
98 don't want to use "git pull <repository> <refspec>" explicitly. Set the
99 branch.autosetupmerge configuration variable to true if you
100 want git-checkout and git-branch to always behave as if
101 '--track' were given.
102
103--no-track::
104 When -b is given and a branch is created off a remote branch,
105 set up configuration so that git-pull will not retrieve data
106 from the remote branch, ignoring the branch.autosetupmerge
107 configuration variable.
108
52a22d1e 109<branchname>::
d4072c97 110 The name of the branch to create or delete.
2b1f4247
SP
111 The new branch name must pass all checks defined by
112 gitlink:git-check-ref-format[1]. Some of these checks
113 may restrict the characters allowed in a branch name.
7fc9d69f 114
075dd8ee 115<start-point>::
2eaf273d
SE
116 The new branch will be created with a HEAD equal to this. It may
117 be given as a branch name, a commit-id, or a tag. If this option
118 is omitted, the current branch is assumed.
119
c976d415
LH
120<oldbranch>::
121 The name of an existing branch to rename.
122
123<newbranch>::
124 The new name for an existing branch. The same restrictions as for
125 <branchname> applies.
7fc9d69f 126
1e2ccd3a
JH
127
128Examples
2eaf273d 129--------
1e2ccd3a 130
dd181119 131Start development off of a known tag::
1e2ccd3a
JH
132+
133------------
134$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
135$ cd my2.6
2eaf273d 136$ git branch my2.6.14 v2.6.14 <1>
1e2ccd3a 137$ git checkout my2.6.14
1e2ccd3a 138------------
2eaf273d
SE
139+
140<1> This step and the next one could be combined into a single step with
141"checkout -b my2.6.14 v2.6.14".
1e2ccd3a
JH
142
143Delete unneeded branch::
144+
145------------
146$ git clone git://git.kernel.org/.../git.git my.git
147$ cd my.git
33b1f3d5
FM
148$ git branch -d -r origin/todo origin/html origin/man <1>
149$ git branch -D test <2>
2eaf273d
SE
150------------
151+
434e6ef8
SH
152<1> Delete remote-tracking branches "todo", "html", "man"
153<2> Delete "test" branch even if the "master" branch does not have all
045fe3cc 154commits from test branch.
2eaf273d
SE
155
156
157Notes
158-----
159
160If you are creating a branch that you want to immediately checkout, it's
161easier to use the git checkout command with its `-b` option to create
162a branch and check it out with a single command.
163
1e2ccd3a 164
7fc9d69f
JH
165Author
166------
167Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>
168
169Documentation
170--------------
171Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
172
173GIT
174---
a7154e91 175Part of the gitlink:git[7] suite