Merge branch 'jk/fast-import-marks-cleanup'
[git] / Documentation / git-branch.txt
1 git-branch(1)
2 =============
3
4 NAME
5 ----
6 git-branch - List, create, or delete branches
7
8 SYNOPSIS
9 --------
10 [verse]
11 'git branch' [--color[=<when>] | --no-color] [--show-current]
12         [-v [--abbrev=<length> | --no-abbrev]]
13         [--column[=<options>] | --no-column] [--sort=<key>]
14         [--merged [<commit>]] [--no-merged [<commit>]]
15         [--contains [<commit>]] [--no-contains [<commit>]]
16         [--points-at <object>] [--format=<format>]
17         [(-r | --remotes) | (-a | --all)]
18         [--list] [<pattern>...]
19 'git branch' [--track | --no-track] [-f] <branchname> [<start-point>]
20 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
21 'git branch' --unset-upstream [<branchname>]
22 'git branch' (-m | -M) [<oldbranch>] <newbranch>
23 'git branch' (-c | -C) [<oldbranch>] <newbranch>
24 'git branch' (-d | -D) [-r] <branchname>...
25 'git branch' --edit-description [<branchname>]
26
27 DESCRIPTION
28 -----------
29
30 If `--list` is given, or if there are no non-option arguments, existing
31 branches are listed; the current branch will be highlighted in green and
32 marked with an asterisk.  Any branches checked out in linked worktrees will
33 be highlighted in cyan and marked with a plus sign. Option `-r` causes the
34 remote-tracking branches to be listed,
35 and option `-a` shows both local and remote branches.
36
37 If a `<pattern>`
38 is given, it is used as a shell wildcard to restrict the output to
39 matching branches. If multiple patterns are given, a branch is shown if
40 it matches any of the patterns.
41
42 Note that when providing a
43 `<pattern>`, you must use `--list`; otherwise the command may be interpreted
44 as branch creation.
45
46 With `--contains`, shows only the branches that contain the named commit
47 (in other words, the branches whose tip commits are descendants of the
48 named commit), `--no-contains` inverts it. With `--merged`, only branches
49 merged into the named commit (i.e. the branches whose tip commits are
50 reachable from the named commit) will be listed.  With `--no-merged` only
51 branches not merged into the named commit will be listed.  If the <commit>
52 argument is missing it defaults to `HEAD` (i.e. the tip of the current
53 branch).
54
55 The command's second form creates a new branch head named <branchname>
56 which points to the current `HEAD`, or <start-point> if given. As a
57 special case, for <start-point>, you may use `"A...B"` as a shortcut for
58 the merge base of `A` and `B` if there is exactly one merge base. You
59 can leave out at most one of `A` and `B`, in which case it defaults to
60 `HEAD`.
61
62 Note that this will create the new branch, but it will not switch the
63 working tree to it; use "git switch <newbranch>" to switch to the
64 new branch.
65
66 When a local branch is started off a remote-tracking branch, Git sets up the
67 branch (specifically the `branch.<name>.remote` and `branch.<name>.merge`
68 configuration entries) so that 'git pull' will appropriately merge from
69 the remote-tracking branch. This behavior may be changed via the global
70 `branch.autoSetupMerge` configuration flag. That setting can be
71 overridden by using the `--track` and `--no-track` options, and
72 changed later using `git branch --set-upstream-to`.
73
74 With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>.
75 If <oldbranch> had a corresponding reflog, it is renamed to match
76 <newbranch>, and a reflog entry is created to remember the branch
77 renaming. If <newbranch> exists, -M must be used to force the rename
78 to happen.
79
80 The `-c` and `-C` options have the exact same semantics as `-m` and
81 `-M`, except instead of the branch being renamed it along with its
82 config and reflog will be copied to a new name.
83
84 With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
85 specify more than one branch for deletion.  If the branch currently
86 has a reflog then the reflog will also be deleted.
87
88 Use `-r` together with `-d` to delete remote-tracking branches. Note, that it
89 only makes sense to delete remote-tracking branches if they no longer exist
90 in the remote repository or if 'git fetch' was configured not to fetch
91 them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a
92 way to clean up all obsolete remote-tracking branches.
93
94
95 OPTIONS
96 -------
97 -d::
98 --delete::
99         Delete a branch. The branch must be fully merged in its
100         upstream branch, or in `HEAD` if no upstream was set with
101         `--track` or `--set-upstream-to`.
102
103 -D::
104         Shortcut for `--delete --force`.
105
106 --create-reflog::
107         Create the branch's reflog.  This activates recording of
108         all changes made to the branch ref, enabling use of date
109         based sha1 expressions such as "<branchname>@\{yesterday}".
110         Note that in non-bare repositories, reflogs are usually
111         enabled by default by the `core.logAllRefUpdates` config option.
112         The negated form `--no-create-reflog` only overrides an earlier
113         `--create-reflog`, but currently does not negate the setting of
114         `core.logAllRefUpdates`.
115
116 -f::
117 --force::
118         Reset <branchname> to <startpoint>, even if <branchname> exists
119         already. Without `-f`, 'git branch' refuses to change an existing branch.
120         In combination with `-d` (or `--delete`), allow deleting the
121         branch irrespective of its merged status. In combination with
122         `-m` (or `--move`), allow renaming the branch even if the new
123         branch name already exists, the same applies for `-c` (or `--copy`).
124
125 -m::
126 --move::
127         Move/rename a branch and the corresponding reflog.
128
129 -M::
130         Shortcut for `--move --force`.
131
132 -c::
133 --copy::
134         Copy a branch and the corresponding reflog.
135
136 -C::
137         Shortcut for `--copy --force`.
138
139 --color[=<when>]::
140         Color branches to highlight current, local, and
141         remote-tracking branches.
142         The value must be always (the default), never, or auto.
143
144 --no-color::
145         Turn off branch colors, even when the configuration file gives the
146         default to color output.
147         Same as `--color=never`.
148
149 -i::
150 --ignore-case::
151         Sorting and filtering branches are case insensitive.
152
153 --column[=<options>]::
154 --no-column::
155         Display branch listing in columns. See configuration variable
156         column.branch for option syntax.`--column` and `--no-column`
157         without options are equivalent to 'always' and 'never' respectively.
158 +
159 This option is only applicable in non-verbose mode.
160
161 -r::
162 --remotes::
163         List or delete (if used with -d) the remote-tracking branches.
164         Combine with `--list` to match the optional pattern(s).
165
166 -a::
167 --all::
168         List both remote-tracking branches and local branches.
169         Combine with `--list` to match optional pattern(s).
170
171 -l::
172 --list::
173         List branches.  With optional `<pattern>...`, e.g. `git
174         branch --list 'maint-*'`, list only the branches that match
175         the pattern(s).
176
177 --show-current::
178         Print the name of the current branch. In detached HEAD state,
179         nothing is printed.
180
181 -v::
182 -vv::
183 --verbose::
184         When in list mode,
185         show sha1 and commit subject line for each head, along with
186         relationship to upstream branch (if any). If given twice, print
187         the path of the linked worktree (if any) and the name of the upstream
188         branch, as well (see also `git remote show <remote>`).  Note that the
189         current worktree's HEAD will not have its path printed (it will always
190         be your current directory).
191
192 -q::
193 --quiet::
194         Be more quiet when creating or deleting a branch, suppressing
195         non-error messages.
196
197 --abbrev=<length>::
198         Alter the sha1's minimum display length in the output listing.
199         The default value is 7 and can be overridden by the `core.abbrev`
200         config option.
201
202 --no-abbrev::
203         Display the full sha1s in the output listing rather than abbreviating them.
204
205 -t::
206 --track::
207         When creating a new branch, set up `branch.<name>.remote` and
208         `branch.<name>.merge` configuration entries to mark the
209         start-point branch as "upstream" from the new branch. This
210         configuration will tell git to show the relationship between the
211         two branches in `git status` and `git branch -v`. Furthermore,
212         it directs `git pull` without arguments to pull from the
213         upstream when the new branch is checked out.
214 +
215 This behavior is the default when the start point is a remote-tracking branch.
216 Set the branch.autoSetupMerge configuration variable to `false` if you
217 want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track`
218 were given. Set it to `always` if you want this behavior when the
219 start-point is either a local or remote-tracking branch.
220
221 --no-track::
222         Do not set up "upstream" configuration, even if the
223         branch.autoSetupMerge configuration variable is true.
224
225 --set-upstream::
226         As this option had confusing syntax, it is no longer supported.
227         Please use `--track` or `--set-upstream-to` instead.
228
229 -u <upstream>::
230 --set-upstream-to=<upstream>::
231         Set up <branchname>'s tracking information so <upstream> is
232         considered <branchname>'s upstream branch. If no <branchname>
233         is specified, then it defaults to the current branch.
234
235 --unset-upstream::
236         Remove the upstream information for <branchname>. If no branch
237         is specified it defaults to the current branch.
238
239 --edit-description::
240         Open an editor and edit the text to explain what the branch is
241         for, to be used by various other commands (e.g. `format-patch`,
242         `request-pull`, and `merge` (if enabled)). Multi-line explanations
243         may be used.
244
245 --contains [<commit>]::
246         Only list branches which contain the specified commit (HEAD
247         if not specified). Implies `--list`.
248
249 --no-contains [<commit>]::
250         Only list branches which don't contain the specified commit
251         (HEAD if not specified). Implies `--list`.
252
253 --merged [<commit>]::
254         Only list branches whose tips are reachable from the
255         specified commit (HEAD if not specified). Implies `--list`.
256
257 --no-merged [<commit>]::
258         Only list branches whose tips are not reachable from the
259         specified commit (HEAD if not specified). Implies `--list`.
260
261 <branchname>::
262         The name of the branch to create or delete.
263         The new branch name must pass all checks defined by
264         linkgit:git-check-ref-format[1].  Some of these checks
265         may restrict the characters allowed in a branch name.
266
267 <start-point>::
268         The new branch head will point to this commit.  It may be
269         given as a branch name, a commit-id, or a tag.  If this
270         option is omitted, the current HEAD will be used instead.
271
272 <oldbranch>::
273         The name of an existing branch to rename.
274
275 <newbranch>::
276         The new name for an existing branch. The same restrictions as for
277         <branchname> apply.
278
279 --sort=<key>::
280         Sort based on the key given. Prefix `-` to sort in descending
281         order of the value. You may use the --sort=<key> option
282         multiple times, in which case the last key becomes the primary
283         key. The keys supported are the same as those in `git
284         for-each-ref`. Sort order defaults to the value configured for the
285         `branch.sort` variable if exists, or to sorting based on the
286         full refname (including `refs/...` prefix). This lists
287         detached HEAD (if present) first, then local branches and
288         finally remote-tracking branches. See linkgit:git-config[1].
289
290
291 --points-at <object>::
292         Only list branches of the given object.
293
294 --format <format>::
295         A string that interpolates `%(fieldname)` from a branch ref being shown
296         and the object it points at.  The format is the same as
297         that of linkgit:git-for-each-ref[1].
298
299 CONFIGURATION
300 -------------
301 `pager.branch` is only respected when listing branches, i.e., when
302 `--list` is used or implied. The default is to use a pager.
303 See linkgit:git-config[1].
304
305 EXAMPLES
306 --------
307
308 Start development from a known tag::
309 +
310 ------------
311 $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
312 $ cd my2.6
313 $ git branch my2.6.14 v2.6.14   <1>
314 $ git switch my2.6.14
315 ------------
316 +
317 <1> This step and the next one could be combined into a single step with
318     "checkout -b my2.6.14 v2.6.14".
319
320 Delete an unneeded branch::
321 +
322 ------------
323 $ git clone git://git.kernel.org/.../git.git my.git
324 $ cd my.git
325 $ git branch -d -r origin/todo origin/html origin/man   <1>
326 $ git branch -D test                                    <2>
327 ------------
328 +
329 <1> Delete the remote-tracking branches "todo", "html" and "man". The next
330     'fetch' or 'pull' will create them again unless you configure them not to.
331     See linkgit:git-fetch[1].
332 <2> Delete the "test" branch even if the "master" branch (or whichever branch
333     is currently checked out) does not have all commits from the test branch.
334
335 Listing branches from a specific remote::
336 +
337 ------------
338 $ git branch -r -l '<remote>/<pattern>'                 <1>
339 $ git for-each-ref 'refs/remotes/<remote>/<pattern>'    <2>
340 ------------
341 +
342 <1> Using `-a` would conflate <remote> with any local branches you happen to
343     have been prefixed with the same <remote> pattern.
344 <2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1]
345
346 Patterns will normally need quoting.
347
348 NOTES
349 -----
350
351 If you are creating a branch that you want to switch to immediately,
352 it is easier to use the "git switch" command with its `-c` option to
353 do the same thing with a single command.
354
355 The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
356 serve four related but different purposes:
357
358 - `--contains <commit>` is used to find all branches which will need
359   special attention if <commit> were to be rebased or amended, since those
360   branches contain the specified <commit>.
361
362 - `--no-contains <commit>` is the inverse of that, i.e. branches that don't
363   contain the specified <commit>.
364
365 - `--merged` is used to find all branches which can be safely deleted,
366   since those branches are fully contained by HEAD.
367
368 - `--no-merged` is used to find branches which are candidates for merging
369   into HEAD, since those branches are not fully contained by HEAD.
370
371 include::ref-reachability-filters.txt[]
372
373 SEE ALSO
374 --------
375 linkgit:git-check-ref-format[1],
376 linkgit:git-fetch[1],
377 linkgit:git-remote[1],
378 link:user-manual.html#what-is-a-branch[``Understanding history: What is
379 a branch?''] in the Git User's Manual.
380
381 GIT
382 ---
383 Part of the linkgit:git[1] suite