1GIT-BRANCH(1) Git Manual GIT-BRANCH(1)
2
6 git-branch - List, create, or delete branches
7
9 git branch [--color[=<when>] | --no-color] [--show-current]
10 [-v [--abbrev=<n> | --no-abbrev]]
11 [--column[=<options>] | --no-column] [--sort=<key>]
12 [--merged [<commit>]] [--no-merged [<commit>]]
13 [--contains [<commit>]] [--no-contains [<commit>]]
14 [--points-at <object>] [--format=<format>]
15 [(-r | --remotes) | (-a | --all)]
16 [--list] [<pattern>...]
17 git branch [--track[=(direct|inherit)] | --no-track] [-f]
18 [--recurse-submodules] <branchname> [<start-point>]
19 git branch (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
20 git branch --unset-upstream [<branchname>]
21 git branch (-m | -M) [<oldbranch>] <newbranch>
22 git branch (-c | -C) [<oldbranch>] <newbranch>
23 git branch (-d | -D) [-r] <branchname>...
24 git branch --edit-description [<branchname>]
25
27 If --list is given, or if there are no non-option arguments, existing
28 branches are listed; the current branch will be highlighted in green
29 and marked with an asterisk. Any branches checked out in linked
30 worktrees will be highlighted in cyan and marked with a plus sign.
31 Option -r causes the remote-tracking branches to be listed, and option
32 -a shows both local and remote branches.
33 If a <pattern> is given, it is used as a shell wildcard to restrict the
35 output to matching branches. If multiple patterns are given, a branch
36 is shown if it matches any of the patterns.
37 Note that when providing a <pattern>, you must use --list; otherwise
39 the command may be interpreted as branch creation.
40 With --contains, shows only the branches that contain the named commit
42 (in other words, the branches whose tip commits are descendants of the
43 named commit), --no-contains inverts it. With --merged, only branches
44 merged into the named commit (i.e. the branches whose tip commits are
45 reachable from the named commit) will be listed. With --no-merged only
46 branches not merged into the named commit will be listed. If the
47 <commit> argument is missing it defaults to HEAD (i.e. the tip of the
48 current branch).
49 The command’s second form creates a new branch head named <branchname>
51 which points to the current HEAD, or <start-point> if given. As a
52 special case, for <start-point>, you may use "A...B" as a shortcut for
53 the merge base of A and B if there is exactly one merge base. You can
54 leave out at most one of A and B, in which case it defaults to HEAD.
55 Note that this will create the new branch, but it will not switch the
57 working tree to it; use "git switch <newbranch>" to switch to the new
58 branch.
59 When a local branch is started off a remote-tracking branch, Git sets
61 up the branch (specifically the branch.<name>.remote and
62 branch.<name>.merge configuration entries) so that git pull will
63 appropriately merge from the remote-tracking branch. This behavior may
64 be changed via the global branch.autoSetupMerge configuration flag.
65 That setting can be overridden by using the --track and --no-track
66 options, and changed later using git branch --set-upstream-to.
67 With a -m or -M option, <oldbranch> will be renamed to <newbranch>. If
69 <oldbranch> had a corresponding reflog, it is renamed to match
70 <newbranch>, and a reflog entry is created to remember the branch
71 renaming. If <newbranch> exists, -M must be used to force the rename to
72 happen.
73 The -c and -C options have the exact same semantics as -m and -M,
75 except instead of the branch being renamed, it will be copied to a new
76 name, along with its config and reflog.
77 With a -d or -D option, <branchname> will be deleted. You may specify
79 more than one branch for deletion. If the branch currently has a reflog
80 then the reflog will also be deleted.
81 Use -r together with -d to delete remote-tracking branches. Note, that
83 it only makes sense to delete remote-tracking branches if they no
84 longer exist in the remote repository or if git fetch was configured
85 not to fetch them again. See also the prune subcommand of git-remote(1)
86 for a way to clean up all obsolete remote-tracking branches.
87
89 -d, --delete
90 Delete a branch. The branch must be fully merged in its upstream
91 branch, or in HEAD if no upstream was set with --track or
92 --set-upstream-to.
93 -D
95 Shortcut for --delete --force.
96 --create-reflog
98 Create the branch’s reflog. This activates recording of all changes
99 made to the branch ref, enabling use of date based sha1 expressions
100 such as "<branchname>@{yesterday}". Note that in non-bare
101 repositories, reflogs are usually enabled by default by the
102 core.logAllRefUpdates config option. The negated form
103 --no-create-reflog only overrides an earlier --create-reflog, but
104 currently does not negate the setting of core.logAllRefUpdates.
105 -f, --force
107 Reset <branchname> to <start-point>, even if <branchname> exists
108 already. Without -f, git branch refuses to change an existing
109 branch. In combination with -d (or --delete), allow deleting the
110 branch irrespective of its merged status, or whether it even points
111 to a valid commit. In combination with -m (or --move), allow
112 renaming the branch even if the new branch name already exists, the
113 same applies for -c (or --copy).
114 Note that git branch -f <branchname> [<start-point>], even with -f,
116 refuses to change an existing branch <branchname> that is checked
117 out in another worktree linked to the same repository.
118 -m, --move
120 Move/rename a branch, together with its config and reflog.
121 -M
123 Shortcut for --move --force.
124 -c, --copy
126 Copy a branch, together with its config and reflog.
127 -C
129 Shortcut for --copy --force.
130 --color[=<when>]
132 Color branches to highlight current, local, and remote-tracking
133 branches. The value must be always (the default), never, or auto.
134 --no-color
136 Turn off branch colors, even when the configuration file gives the
137 default to color output. Same as --color=never.
138 -i, --ignore-case
140 Sorting and filtering branches are case insensitive.
141 --omit-empty
143 Do not print a newline after formatted refs where the format
144 expands to the empty string.
145 --column[=<options>], --no-column
147 Display branch listing in columns. See configuration variable
148 column.branch for option syntax. --column and --no-column without
149 options are equivalent to always and never respectively.
150 This option is only applicable in non-verbose mode.
152 -r, --remotes
154 List or delete (if used with -d) the remote-tracking branches.
155 Combine with --list to match the optional pattern(s).
156 -a, --all
158 List both remote-tracking branches and local branches. Combine with
159 --list to match optional pattern(s).
160 -l, --list
162 List branches. With optional <pattern>..., e.g. git branch --list
163 'maint-*', list only the branches that match the pattern(s).
164 --show-current
166 Print the name of the current branch. In detached HEAD state,
167 nothing is printed.
168 -v, -vv, --verbose
170 When in list mode, show sha1 and commit subject line for each head,
171 along with relationship to upstream branch (if any). If given
172 twice, print the path of the linked worktree (if any) and the name
173 of the upstream branch, as well (see also git remote show
174 <remote>). Note that the current worktree’s HEAD will not have its
175 path printed (it will always be your current directory).
176 -q, --quiet
178 Be more quiet when creating or deleting a branch, suppressing
179 non-error messages.
180 --abbrev=<n>
182 In the verbose listing that show the commit object name, show the
183 shortest prefix that is at least <n> hexdigits long that uniquely
184 refers the object. The default value is 7 and can be overridden by
185 the core.abbrev config option.
186 --no-abbrev
188 Display the full sha1s in the output listing rather than
189 abbreviating them.
190 -t, --track[=(direct|inherit)]
192 When creating a new branch, set up branch.<name>.remote and
193 branch.<name>.merge configuration entries to set "upstream"
194 tracking configuration for the new branch. This configuration will
195 tell git to show the relationship between the two branches in git
196 status and git branch -v. Furthermore, it directs git pull without
197 arguments to pull from the upstream when the new branch is checked
198 out.
199 The exact upstream branch is chosen depending on the optional
201 argument: -t, --track, or --track=direct means to use the
202 start-point branch itself as the upstream; --track=inherit means to
203 copy the upstream configuration of the start-point branch.
204 The branch.autoSetupMerge configuration variable specifies how git
206 switch, git checkout and git branch should behave when neither
207 --track nor --no-track are specified:
208 The default option, true, behaves as though --track=direct were
210 given whenever the start-point is a remote-tracking branch. false
211 behaves as if --no-track were given. always behaves as though
212 --track=direct were given. inherit behaves as though
213 --track=inherit were given. simple behaves as though
214 --track=direct were given only when the start-point is a
215 remote-tracking branch and the new branch has the same name as the
216 remote branch.
217 See git-pull(1) and git-config(1) for additional discussion on how
219 the branch.<name>.remote and branch.<name>.merge options are used.
220 --no-track
222 Do not set up "upstream" configuration, even if the
223 branch.autoSetupMerge configuration variable is set.
224 --recurse-submodules
226 THIS OPTION IS EXPERIMENTAL! Causes the current command to recurse
227 into submodules if submodule.propagateBranches is enabled. See
228 submodule.propagateBranches in git-config(1). Currently, only
229 branch creation is supported.
230 When used in branch creation, a new branch <branchname> will be
232 created in the superproject and all of the submodules in the
233 superproject’s <start-point>. In submodules, the branch will point
234 to the submodule commit in the superproject’s <start-point> but the
235 branch’s tracking information will be set up based on the
236 submodule’s branches and remotes e.g. git branch
237 --recurse-submodules topic origin/main will create the submodule
238 branch "topic" that points to the submodule commit in the
239 superproject’s "origin/main", but tracks the submodule’s
240 "origin/main".
241 --set-upstream
243 As this option had confusing syntax, it is no longer supported.
244 Please use --track or --set-upstream-to instead.
245 -u <upstream>, --set-upstream-to=<upstream>
247 Set up <branchname>'s tracking information so <upstream> is
248 considered <branchname>'s upstream branch. If no <branchname> is
249 specified, then it defaults to the current branch.
250 --unset-upstream
252 Remove the upstream information for <branchname>. If no branch is
253 specified it defaults to the current branch.
254 --edit-description
256 Open an editor and edit the text to explain what the branch is for,
257 to be used by various other commands (e.g. format-patch,
258 request-pull, and merge (if enabled)). Multi-line explanations may
259 be used.
260 --contains [<commit>]
262 Only list branches which contain the specified commit (HEAD if not
263 specified). Implies --list.
264 --no-contains [<commit>]
266 Only list branches which don’t contain the specified commit (HEAD
267 if not specified). Implies --list.
268 --merged [<commit>]
270 Only list branches whose tips are reachable from the specified
271 commit (HEAD if not specified). Implies --list.
272 --no-merged [<commit>]
274 Only list branches whose tips are not reachable from the specified
275 commit (HEAD if not specified). Implies --list.
276 <branchname>
278 The name of the branch to create or delete. The new branch name
279 must pass all checks defined by git-check-ref-format(1). Some of
280 these checks may restrict the characters allowed in a branch name.
281 <start-point>
283 The new branch head will point to this commit. It may be given as a
284 branch name, a commit-id, or a tag. If this option is omitted, the
285 current HEAD will be used instead.
286 <oldbranch>
288 The name of an existing branch to rename.
289 <newbranch>
291 The new name for an existing branch. The same restrictions as for
292 <branchname> apply.
293 --sort=<key>
295 Sort based on the key given. Prefix - to sort in descending order
296 of the value. You may use the --sort=<key> option multiple times,
297 in which case the last key becomes the primary key. The keys
298 supported are the same as those in git for-each-ref. Sort order
299 defaults to the value configured for the branch.sort variable if it
300 exists, or to sorting based on the full refname (including refs/...
301 prefix). This lists detached HEAD (if present) first, then local
302 branches and finally remote-tracking branches. See git-config(1).
303 --points-at <object>
305 Only list branches of the given object.
306 --format <format>
308 A string that interpolates %(fieldname) from a branch ref being
309 shown and the object it points at. The format is the same as that
310 of git-for-each-ref(1).
311
313 pager.branch is only respected when listing branches, i.e., when --list
314 is used or implied. The default is to use a pager. See git-config(1).
315 Everything above this line in this section isn’t included from the git-
317 config(1) documentation. The content that follows is the same as what’s
318 found there:
319 branch.autoSetupMerge
321 Tells git branch, git switch and git checkout to set up new
322 branches so that git-pull(1) will appropriately merge from the
323 starting point branch. Note that even if this option is not set,
324 this behavior can be chosen per-branch using the --track and
325 --no-track options. The valid settings are: false — no automatic
326 setup is done; true — automatic setup is done when the starting
327 point is a remote-tracking branch; always — automatic setup is done
328 when the starting point is either a local branch or remote-tracking
329 branch; inherit — if the starting point has a tracking
330 configuration, it is copied to the new branch; simple — automatic
331 setup is done only when the starting point is a remote-tracking
332 branch and the new branch has the same name as the remote branch.
333 This option defaults to true.
334 branch.autoSetupRebase
336 When a new branch is created with git branch, git switch or git
337 checkout that tracks another branch, this variable tells Git to set
338 up pull to rebase instead of merge (see "branch.<name>.rebase").
339 When never, rebase is never automatically set to true. When local,
340 rebase is set to true for tracked branches of other local branches.
341 When remote, rebase is set to true for tracked branches of
342 remote-tracking branches. When always, rebase will be set to true
343 for all tracking branches. See "branch.autoSetupMerge" for details
344 on how to set up a branch to track another branch. This option
345 defaults to never.
346 branch.sort
348 This variable controls the sort ordering of branches when displayed
349 by git-branch(1). Without the "--sort=<value>" option provided, the
350 value of this variable will be used as the default. See git-for-
351 each-ref(1) field names for valid values.
352 branch.<name>.remote
354 When on branch <name>, it tells git fetch and git push which remote
355 to fetch from or push to. The remote to push to may be overridden
356 with remote.pushDefault (for all branches). The remote to push to,
357 for the current branch, may be further overridden by
358 branch.<name>.pushRemote. If no remote is configured, or if you are
359 not on any branch and there is more than one remote defined in the
360 repository, it defaults to origin for fetching and
361 remote.pushDefault for pushing. Additionally, . (a period) is the
362 current local repository (a dot-repository), see
363 branch.<name>.merge's final note below.
364 branch.<name>.pushRemote
366 When on branch <name>, it overrides branch.<name>.remote for
367 pushing. It also overrides remote.pushDefault for pushing from
368 branch <name>. When you pull from one place (e.g. your upstream)
369 and push to another place (e.g. your own publishing repository),
370 you would want to set remote.pushDefault to specify the remote to
371 push to for all branches, and use this option to override it for a
372 specific branch.
373 branch.<name>.merge
375 Defines, together with branch.<name>.remote, the upstream branch
376 for the given branch. It tells git fetch/git pull/git rebase which
377 branch to merge and can also affect git push (see push.default).
378 When in branch <name>, it tells git fetch the default refspec to be
379 marked for merging in FETCH_HEAD. The value is handled like the
380 remote part of a refspec, and must match a ref which is fetched
381 from the remote given by "branch.<name>.remote". The merge
382 information is used by git pull (which first calls git fetch) to
383 lookup the default branch for merging. Without this option, git
384 pull defaults to merge the first refspec fetched. Specify multiple
385 values to get an octopus merge. If you wish to setup git pull so
386 that it merges into <name> from another branch in the local
387 repository, you can point branch.<name>.merge to the desired
388 branch, and use the relative path setting . (a period) for
389 branch.<name>.remote.
390 branch.<name>.mergeOptions
392 Sets default options for merging into branch <name>. The syntax and
393 supported options are the same as those of git-merge(1), but option
394 values containing whitespace characters are currently not
395 supported.
396 branch.<name>.rebase
398 When true, rebase the branch <name> on top of the fetched branch,
399 instead of merging the default branch from the default remote when
400 "git pull" is run. See "pull.rebase" for doing this in a non
401 branch-specific manner.
402 When merges (or just m), pass the --rebase-merges option to git
404 rebase so that the local merge commits are included in the rebase
405 (see git-rebase(1) for details).
406 When the value is interactive (or just i), the rebase is run in
408 interactive mode.
409 NOTE: this is a possibly dangerous operation; do not use it unless
411 you understand the implications (see git-rebase(1) for details).
412 branch.<name>.description
414 Branch description, can be edited with git branch
415 --edit-description. Branch description is automatically added to
416 the format-patch cover letter or request-pull summary.
417
419 Start development from a known tag
420 $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
422 $ cd my2.6
423 $ git branch my2.6.14 v2.6.14 [1m(1)
424 $ git switch my2.6.14
425 1. This step and the next one could be combined into a single
427 step with "checkout -b my2.6.14 v2.6.14".
428 Delete an unneeded branch
430 $ git clone git://git.kernel.org/.../git.git my.git
432 $ cd my.git
433 $ git branch -d -r origin/todo origin/html origin/man [1m(1)
434 $ git branch -D test [1m(2)
435 1. Delete the remote-tracking branches "todo", "html" and
437 "man". The next fetch or pull will create them again
438 unless you configure them not to. See git-fetch(1).
439 2. Delete the "test" branch even if the "master" branch (or
440 whichever branch is currently checked out) does not have
441 all commits from the test branch.
442 Listing branches from a specific remote
444 $ git branch -r -l '<remote>/<pattern>' [1m(1)
446 $ git for-each-ref 'refs/remotes/<remote>/<pattern>' [1m(2)
447 1. Using -a would conflate <remote> with any local branches
449 you happen to have been prefixed with the same <remote>
450 pattern.
451 2. for-each-ref can take a wide range of options. See git-
452 for-each-ref(1)
453 Patterns will normally need quoting.
455
457 If you are creating a branch that you want to switch to immediately, it
458 is easier to use the "git switch" command with its -c option to do the
459 same thing with a single command.
460 The options --contains, --no-contains, --merged and --no-merged serve
462 four related but different purposes:
463 • --contains <commit> is used to find all branches which will need
465 special attention if <commit> were to be rebased or amended, since
466 those branches contain the specified <commit>.
467 • --no-contains <commit> is the inverse of that, i.e. branches that
469 don’t contain the specified <commit>.
470 • --merged is used to find all branches which can be safely deleted,
472 since those branches are fully contained by HEAD.
473 • --no-merged is used to find branches which are candidates for
475 merging into HEAD, since those branches are not fully contained by
476 HEAD.
477 When combining multiple --contains and --no-contains filters, only
479 references that contain at least one of the --contains commits and
480 contain none of the --no-contains commits are shown.
481 When combining multiple --merged and --no-merged filters, only
483 references that are reachable from at least one of the --merged commits
484 and from none of the --no-merged commits are shown.
485
487 git-check-ref-format(1), git-fetch(1), git-remote(1), “Understanding
488 history: What is a branch?”[1] in the Git User’s Manual.
489
491 Part of the git(1) suite
492
494 1. “Understanding history: What is a branch?”
495 file:///usr/share/doc/git/user-manual.html#what-is-a-branch
496Git 2.43.0 11/20/2023 GIT-BRANCH(1)