6 git-branch - List, create, or delete branches
11 'git branch' [--color[=<when>] | --no-color] [--show-current]
12 [-v [--abbrev=<n> | --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[=(direct|inherit)] | --no-track] [-f]
20 [--recurse-submodules] <branchname> [<start-point>]
21 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
22 'git branch' --unset-upstream [<branchname>]
23 'git branch' (-m | -M) [<oldbranch>] <newbranch>
24 'git branch' (-c | -C) [<oldbranch>] <newbranch>
25 'git branch' (-d | -D) [-r] <branchname>...
26 'git branch' --edit-description [<branchname>]
31 If `--list` is given, or if there are no non-option arguments, existing
32 branches are listed; the current branch will be highlighted in green and
33 marked with an asterisk. Any branches checked out in linked worktrees will
34 be highlighted in cyan and marked with a plus sign. Option `-r` causes the
35 remote-tracking branches to be listed,
36 and option `-a` shows both local and remote branches.
39 is given, it is used as a shell wildcard to restrict the output to
40 matching branches. If multiple patterns are given, a branch is shown if
41 it matches any of the patterns.
43 Note that when providing a
44 `<pattern>`, you must use `--list`; otherwise the command may be interpreted
47 With `--contains`, shows only the branches that contain the named commit
48 (in other words, the branches whose tip commits are descendants of the
49 named commit), `--no-contains` inverts it. With `--merged`, only branches
50 merged into the named commit (i.e. the branches whose tip commits are
51 reachable from the named commit) will be listed. With `--no-merged` only
52 branches not merged into the named commit will be listed. If the <commit>
53 argument is missing it defaults to `HEAD` (i.e. the tip of the current
56 The command's second form creates a new branch head named <branchname>
57 which points to the current `HEAD`, or <start-point> if given. As a
58 special case, for <start-point>, you may use `"A...B"` as a shortcut for
59 the merge base of `A` and `B` if there is exactly one merge base. You
60 can leave out at most one of `A` and `B`, in which case it defaults to
63 Note that this will create the new branch, but it will not switch the
64 working tree to it; use "git switch <newbranch>" to switch to the
67 When a local branch is started off a remote-tracking branch, Git sets up the
68 branch (specifically the `branch.<name>.remote` and `branch.<name>.merge`
69 configuration entries) so that 'git pull' will appropriately merge from
70 the remote-tracking branch. This behavior may be changed via the global
71 `branch.autoSetupMerge` configuration flag. That setting can be
72 overridden by using the `--track` and `--no-track` options, and
73 changed later using `git branch --set-upstream-to`.
75 With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>.
76 If <oldbranch> had a corresponding reflog, it is renamed to match
77 <newbranch>, and a reflog entry is created to remember the branch
78 renaming. If <newbranch> exists, -M must be used to force the rename
81 The `-c` and `-C` options have the exact same semantics as `-m` and
82 `-M`, except instead of the branch being renamed, it will be copied to a
83 new name, along with its config and reflog.
85 With a `-d` or `-D` option, `<branchname>` will be deleted. You may
86 specify more than one branch for deletion. If the branch currently
87 has a reflog then the reflog will also be deleted.
89 Use `-r` together with `-d` to delete remote-tracking branches. Note, that it
90 only makes sense to delete remote-tracking branches if they no longer exist
91 in the remote repository or if 'git fetch' was configured not to fetch
92 them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a
93 way to clean up all obsolete remote-tracking branches.
100 Delete a branch. The branch must be fully merged in its
101 upstream branch, or in `HEAD` if no upstream was set with
102 `--track` or `--set-upstream-to`.
105 Shortcut for `--delete --force`.
108 Create the branch's reflog. This activates recording of
109 all changes made to the branch ref, enabling use of date
110 based sha1 expressions such as "<branchname>@\{yesterday}".
111 Note that in non-bare repositories, reflogs are usually
112 enabled by default by the `core.logAllRefUpdates` config option.
113 The negated form `--no-create-reflog` only overrides an earlier
114 `--create-reflog`, but currently does not negate the setting of
115 `core.logAllRefUpdates`.
119 Reset <branchname> to <startpoint>, even if <branchname> exists
120 already. Without `-f`, 'git branch' refuses to change an existing branch.
121 In combination with `-d` (or `--delete`), allow deleting the
122 branch irrespective of its merged status, or whether it even
123 points to a valid commit. In combination with
124 `-m` (or `--move`), allow renaming the branch even if the new
125 branch name already exists, the same applies for `-c` (or `--copy`).
129 Move/rename a branch, together with its config and reflog.
132 Shortcut for `--move --force`.
136 Copy a branch, together with its config and reflog.
139 Shortcut for `--copy --force`.
142 Color branches to highlight current, local, and
143 remote-tracking branches.
144 The value must be always (the default), never, or auto.
147 Turn off branch colors, even when the configuration file gives the
148 default to color output.
149 Same as `--color=never`.
153 Sorting and filtering branches are case insensitive.
155 --column[=<options>]::
157 Display branch listing in columns. See configuration variable
158 `column.branch` for option syntax. `--column` and `--no-column`
159 without options are equivalent to 'always' and 'never' respectively.
161 This option is only applicable in non-verbose mode.
165 List or delete (if used with -d) the remote-tracking branches.
166 Combine with `--list` to match the optional pattern(s).
170 List both remote-tracking branches and local branches.
171 Combine with `--list` to match optional pattern(s).
175 List branches. With optional `<pattern>...`, e.g. `git
176 branch --list 'maint-*'`, list only the branches that match
180 Print the name of the current branch. In detached HEAD state,
187 show sha1 and commit subject line for each head, along with
188 relationship to upstream branch (if any). If given twice, print
189 the path of the linked worktree (if any) and the name of the upstream
190 branch, as well (see also `git remote show <remote>`). Note that the
191 current worktree's HEAD will not have its path printed (it will always
192 be your current directory).
196 Be more quiet when creating or deleting a branch, suppressing
200 In the verbose listing that show the commit object name,
201 show the shortest prefix that is at least '<n>' hexdigits
202 long that uniquely refers the object.
203 The default value is 7 and can be overridden by the `core.abbrev`
207 Display the full sha1s in the output listing rather than abbreviating them.
210 --track[=(direct|inherit)]::
211 When creating a new branch, set up `branch.<name>.remote` and
212 `branch.<name>.merge` configuration entries to set "upstream" tracking
213 configuration for the new branch. This
214 configuration will tell git to show the relationship between the
215 two branches in `git status` and `git branch -v`. Furthermore,
216 it directs `git pull` without arguments to pull from the
217 upstream when the new branch is checked out.
219 The exact upstream branch is chosen depending on the optional argument:
220 `-t`, `--track`, or `--track=direct` means to use the start-point branch
221 itself as the upstream; `--track=inherit` means to copy the upstream
222 configuration of the start-point branch.
224 The branch.autoSetupMerge configuration variable specifies how `git switch`,
225 `git checkout` and `git branch` should behave when neither `--track` nor
226 `--no-track` are specified:
228 The default option, `true`, behaves as though `--track=direct`
229 were given whenever the start-point is a remote-tracking branch.
230 `false` behaves as if `--no-track` were given. `always` behaves as though
231 `--track=direct` were given. `inherit` behaves as though `--track=inherit`
232 were given. `simple` behaves as though `--track=direct` were given only when
233 the start-point is a remote-tracking branch and the new branch has the same
234 name as the remote branch.
236 See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
237 how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
240 Do not set up "upstream" configuration, even if the
241 branch.autoSetupMerge configuration variable is set.
243 --recurse-submodules::
244 THIS OPTION IS EXPERIMENTAL! Causes the current command to
245 recurse into submodules if `submodule.propagateBranches` is
246 enabled. See `submodule.propagateBranches` in
247 linkgit:git-config[1]. Currently, only branch creation is
250 When used in branch creation, a new branch <branchname> will be created
251 in the superproject and all of the submodules in the superproject's
252 <start-point>. In submodules, the branch will point to the submodule
253 commit in the superproject's <start-point> but the branch's tracking
254 information will be set up based on the submodule's branches and remotes
255 e.g. `git branch --recurse-submodules topic origin/main` will create the
256 submodule branch "topic" that points to the submodule commit in the
257 superproject's "origin/main", but tracks the submodule's "origin/main".
260 As this option had confusing syntax, it is no longer supported.
261 Please use `--track` or `--set-upstream-to` instead.
264 --set-upstream-to=<upstream>::
265 Set up <branchname>'s tracking information so <upstream> is
266 considered <branchname>'s upstream branch. If no <branchname>
267 is specified, then it defaults to the current branch.
270 Remove the upstream information for <branchname>. If no branch
271 is specified it defaults to the current branch.
274 Open an editor and edit the text to explain what the branch is
275 for, to be used by various other commands (e.g. `format-patch`,
276 `request-pull`, and `merge` (if enabled)). Multi-line explanations
279 --contains [<commit>]::
280 Only list branches which contain the specified commit (HEAD
281 if not specified). Implies `--list`.
283 --no-contains [<commit>]::
284 Only list branches which don't contain the specified commit
285 (HEAD if not specified). Implies `--list`.
287 --merged [<commit>]::
288 Only list branches whose tips are reachable from the
289 specified commit (HEAD if not specified). Implies `--list`.
291 --no-merged [<commit>]::
292 Only list branches whose tips are not reachable from the
293 specified commit (HEAD if not specified). Implies `--list`.
296 The name of the branch to create or delete.
297 The new branch name must pass all checks defined by
298 linkgit:git-check-ref-format[1]. Some of these checks
299 may restrict the characters allowed in a branch name.
302 The new branch head will point to this commit. It may be
303 given as a branch name, a commit-id, or a tag. If this
304 option is omitted, the current HEAD will be used instead.
307 The name of an existing branch to rename.
310 The new name for an existing branch. The same restrictions as for
314 Sort based on the key given. Prefix `-` to sort in descending
315 order of the value. You may use the --sort=<key> option
316 multiple times, in which case the last key becomes the primary
317 key. The keys supported are the same as those in `git
318 for-each-ref`. Sort order defaults to the value configured for the
319 `branch.sort` variable if exists, or to sorting based on the
320 full refname (including `refs/...` prefix). This lists
321 detached HEAD (if present) first, then local branches and
322 finally remote-tracking branches. See linkgit:git-config[1].
325 --points-at <object>::
326 Only list branches of the given object.
329 A string that interpolates `%(fieldname)` from a branch ref being shown
330 and the object it points at. The format is the same as
331 that of linkgit:git-for-each-ref[1].
335 `pager.branch` is only respected when listing branches, i.e., when
336 `--list` is used or implied. The default is to use a pager.
337 See linkgit:git-config[1].
342 Start development from a known tag::
345 $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
347 $ git branch my2.6.14 v2.6.14 <1>
348 $ git switch my2.6.14
351 <1> This step and the next one could be combined into a single step with
352 "checkout -b my2.6.14 v2.6.14".
354 Delete an unneeded branch::
357 $ git clone git://git.kernel.org/.../git.git my.git
359 $ git branch -d -r origin/todo origin/html origin/man <1>
360 $ git branch -D test <2>
363 <1> Delete the remote-tracking branches "todo", "html" and "man". The next
364 'fetch' or 'pull' will create them again unless you configure them not to.
365 See linkgit:git-fetch[1].
366 <2> Delete the "test" branch even if the "master" branch (or whichever branch
367 is currently checked out) does not have all commits from the test branch.
369 Listing branches from a specific remote::
372 $ git branch -r -l '<remote>/<pattern>' <1>
373 $ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2>
376 <1> Using `-a` would conflate <remote> with any local branches you happen to
377 have been prefixed with the same <remote> pattern.
378 <2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1]
380 Patterns will normally need quoting.
385 If you are creating a branch that you want to switch to immediately,
386 it is easier to use the "git switch" command with its `-c` option to
387 do the same thing with a single command.
389 The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
390 serve four related but different purposes:
392 - `--contains <commit>` is used to find all branches which will need
393 special attention if <commit> were to be rebased or amended, since those
394 branches contain the specified <commit>.
396 - `--no-contains <commit>` is the inverse of that, i.e. branches that don't
397 contain the specified <commit>.
399 - `--merged` is used to find all branches which can be safely deleted,
400 since those branches are fully contained by HEAD.
402 - `--no-merged` is used to find branches which are candidates for merging
403 into HEAD, since those branches are not fully contained by HEAD.
405 include::ref-reachability-filters.txt[]
409 linkgit:git-check-ref-format[1],
410 linkgit:git-fetch[1],
411 linkgit:git-remote[1],
412 link:user-manual.html#what-is-a-branch[``Understanding history: What is
413 a branch?''] in the Git User's Manual.
417 Part of the linkgit:git[1] suite