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