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 <startpoint>, 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 -m, --move
116 Move/rename a branch, together with its config and reflog.
117 -M
119 Shortcut for --move --force.
120 -c, --copy
122 Copy a branch, together with its config and reflog.
123 -C
125 Shortcut for --copy --force.
126 --color[=<when>]
128 Color branches to highlight current, local, and remote-tracking
129 branches. The value must be always (the default), never, or auto.
130 --no-color
132 Turn off branch colors, even when the configuration file gives the
133 default to color output. Same as --color=never.
134 -i, --ignore-case
136 Sorting and filtering branches are case insensitive.
137 --column[=<options>], --no-column
139 Display branch listing in columns. See configuration variable
140 column.branch for option syntax. --column and --no-column without
141 options are equivalent to always and never respectively.
142 This option is only applicable in non-verbose mode.
144 -r, --remotes
146 List or delete (if used with -d) the remote-tracking branches.
147 Combine with --list to match the optional pattern(s).
148 -a, --all
150 List both remote-tracking branches and local branches. Combine with
151 --list to match optional pattern(s).
152 -l, --list
154 List branches. With optional <pattern>..., e.g. git branch --list
155 'maint-*', list only the branches that match the pattern(s).
156 --show-current
158 Print the name of the current branch. In detached HEAD state,
159 nothing is printed.
160 -v, -vv, --verbose
162 When in list mode, show sha1 and commit subject line for each head,
163 along with relationship to upstream branch (if any). If given
164 twice, print the path of the linked worktree (if any) and the name
165 of the upstream branch, as well (see also git remote show
166 <remote>). Note that the current worktree’s HEAD will not have its
167 path printed (it will always be your current directory).
168 -q, --quiet
170 Be more quiet when creating or deleting a branch, suppressing
171 non-error messages.
172 --abbrev=<n>
174 In the verbose listing that show the commit object name, show the
175 shortest prefix that is at least <n> hexdigits long that uniquely
176 refers the object. The default value is 7 and can be overridden by
177 the core.abbrev config option.
178 --no-abbrev
180 Display the full sha1s in the output listing rather than
181 abbreviating them.
182 -t, --track[=(direct|inherit)]
184 When creating a new branch, set up branch.<name>.remote and
185 branch.<name>.merge configuration entries to set "upstream"
186 tracking configuration for the new branch. This configuration will
187 tell git to show the relationship between the two branches in git
188 status and git branch -v. Furthermore, it directs git pull without
189 arguments to pull from the upstream when the new branch is checked
190 out.
191 The exact upstream branch is chosen depending on the optional
193 argument: -t, --track, or --track=direct means to use the
194 start-point branch itself as the upstream; --track=inherit means to
195 copy the upstream configuration of the start-point branch.
196 The branch.autoSetupMerge configuration variable specifies how git
198 switch, git checkout and git branch should behave when neither
199 --track nor --no-track are specified:
200 The default option, true, behaves as though --track=direct were
202 given whenever the start-point is a remote-tracking branch. false
203 behaves as if --no-track were given. always behaves as though
204 --track=direct were given. inherit behaves as though
205 --track=inherit were given. simple behaves as though
206 --track=direct were given only when the start-point is a
207 remote-tracking branch and the new branch has the same name as the
208 remote branch.
209 See git-pull(1) and git-config(1) for additional discussion on how
211 the branch.<name>.remote and branch.<name>.merge options are used.
212 --no-track
214 Do not set up "upstream" configuration, even if the
215 branch.autoSetupMerge configuration variable is set.
216 --recurse-submodules
218 THIS OPTION IS EXPERIMENTAL! Causes the current command to recurse
219 into submodules if submodule.propagateBranches is enabled. See
220 submodule.propagateBranches in git-config(1). Currently, only
221 branch creation is supported.
222 When used in branch creation, a new branch <branchname> will be
224 created in the superproject and all of the submodules in the
225 superproject’s <start-point>. In submodules, the branch will point
226 to the submodule commit in the superproject’s <start-point> but the
227 branch’s tracking information will be set up based on the
228 submodule’s branches and remotes e.g. git branch
229 --recurse-submodules topic origin/main will create the submodule
230 branch "topic" that points to the submodule commit in the
231 superproject’s "origin/main", but tracks the submodule’s
232 "origin/main".
233 --set-upstream
235 As this option had confusing syntax, it is no longer supported.
236 Please use --track or --set-upstream-to instead.
237 -u <upstream>, --set-upstream-to=<upstream>
239 Set up <branchname>'s tracking information so <upstream> is
240 considered <branchname>'s upstream branch. If no <branchname> is
241 specified, then it defaults to the current branch.
242 --unset-upstream
244 Remove the upstream information for <branchname>. If no branch is
245 specified it defaults to the current branch.
246 --edit-description
248 Open an editor and edit the text to explain what the branch is for,
249 to be used by various other commands (e.g. format-patch,
250 request-pull, and merge (if enabled)). Multi-line explanations may
251 be used.
252 --contains [<commit>]
254 Only list branches which contain the specified commit (HEAD if not
255 specified). Implies --list.
256 --no-contains [<commit>]
258 Only list branches which don’t contain the specified commit (HEAD
259 if not specified). Implies --list.
260 --merged [<commit>]
262 Only list branches whose tips are reachable from the specified
263 commit (HEAD if not specified). Implies --list.
264 --no-merged [<commit>]
266 Only list branches whose tips are not reachable from the specified
267 commit (HEAD if not specified). Implies --list.
268 <branchname>
270 The name of the branch to create or delete. The new branch name
271 must pass all checks defined by git-check-ref-format(1). Some of
272 these checks may restrict the characters allowed in a branch name.
273 <start-point>
275 The new branch head will point to this commit. It may be given as a
276 branch name, a commit-id, or a tag. If this option is omitted, the
277 current HEAD will be used instead.
278 <oldbranch>
280 The name of an existing branch to rename.
281 <newbranch>
283 The new name for an existing branch. The same restrictions as for
284 <branchname> apply.
285 --sort=<key>
287 Sort based on the key given. Prefix - to sort in descending order
288 of the value. You may use the --sort=<key> option multiple times,
289 in which case the last key becomes the primary key. The keys
290 supported are the same as those in git for-each-ref. Sort order
291 defaults to the value configured for the branch.sort variable if
292 exists, or to sorting based on the full refname (including refs/...
293 prefix). This lists detached HEAD (if present) first, then local
294 branches and finally remote-tracking branches. See git-config(1).
295 --points-at <object>
297 Only list branches of the given object.
298 --format <format>
300 A string that interpolates %(fieldname) from a branch ref being
301 shown and the object it points at. The format is the same as that
302 of git-for-each-ref(1).
303
305 pager.branch is only respected when listing branches, i.e., when --list
306 is used or implied. The default is to use a pager. See git-config(1).
307 Everything above this line in this section isn’t included from the git-
309 config(1) documentation. The content that follows is the same as what’s
310 found there:
311 branch.autoSetupMerge
313 Tells git branch, git switch and git checkout to set up new
314 branches so that git-pull(1) will appropriately merge from the
315 starting point branch. Note that even if this option is not set,
316 this behavior can be chosen per-branch using the --track and
317 --no-track options. The valid settings are: false — no automatic
318 setup is done; true — automatic setup is done when the starting
319 point is a remote-tracking branch; always — automatic setup is done
320 when the starting point is either a local branch or remote-tracking
321 branch; inherit — if the starting point has a tracking
322 configuration, it is copied to the new branch; simple — automatic
323 setup is done only when the starting point is a remote-tracking
324 branch and the new branch has the same name as the remote branch.
325 This option defaults to true.
326 branch.autoSetupRebase
328 When a new branch is created with git branch, git switch or git
329 checkout that tracks another branch, this variable tells Git to set
330 up pull to rebase instead of merge (see "branch.<name>.rebase").
331 When never, rebase is never automatically set to true. When local,
332 rebase is set to true for tracked branches of other local branches.
333 When remote, rebase is set to true for tracked branches of
334 remote-tracking branches. When always, rebase will be set to true
335 for all tracking branches. See "branch.autoSetupMerge" for details
336 on how to set up a branch to track another branch. This option
337 defaults to never.
338 branch.sort
340 This variable controls the sort ordering of branches when displayed
341 by git-branch(1). Without the "--sort=<value>" option provided, the
342 value of this variable will be used as the default. See git-for-
343 each-ref(1) field names for valid values.
344 branch.<name>.remote
346 When on branch <name>, it tells git fetch and git push which remote
347 to fetch from/push to. The remote to push to may be overridden with
348 remote.pushDefault (for all branches). The remote to push to, for
349 the current branch, may be further overridden by
350 branch.<name>.pushRemote. If no remote is configured, or if you are
351 not on any branch and there is more than one remote defined in the
352 repository, it defaults to origin for fetching and
353 remote.pushDefault for pushing. Additionally, . (a period) is the
354 current local repository (a dot-repository), see
355 branch.<name>.merge's final note below.
356 branch.<name>.pushRemote
358 When on branch <name>, it overrides branch.<name>.remote for
359 pushing. It also overrides remote.pushDefault for pushing from
360 branch <name>. When you pull from one place (e.g. your upstream)
361 and push to another place (e.g. your own publishing repository),
362 you would want to set remote.pushDefault to specify the remote to
363 push to for all branches, and use this option to override it for a
364 specific branch.
365 branch.<name>.merge
367 Defines, together with branch.<name>.remote, the upstream branch
368 for the given branch. It tells git fetch/git pull/git rebase which
369 branch to merge and can also affect git push (see push.default).
370 When in branch <name>, it tells git fetch the default refspec to be
371 marked for merging in FETCH_HEAD. The value is handled like the
372 remote part of a refspec, and must match a ref which is fetched
373 from the remote given by "branch.<name>.remote". The merge
374 information is used by git pull (which at first calls git fetch) to
375 lookup the default branch for merging. Without this option, git
376 pull defaults to merge the first refspec fetched. Specify multiple
377 values to get an octopus merge. If you wish to setup git pull so
378 that it merges into <name> from another branch in the local
379 repository, you can point branch.<name>.merge to the desired
380 branch, and use the relative path setting . (a period) for
381 branch.<name>.remote.
382 branch.<name>.mergeOptions
384 Sets default options for merging into branch <name>. The syntax and
385 supported options are the same as those of git-merge(1), but option
386 values containing whitespace characters are currently not
387 supported.
388 branch.<name>.rebase
390 When true, rebase the branch <name> on top of the fetched branch,
391 instead of merging the default branch from the default remote when
392 "git pull" is run. See "pull.rebase" for doing this in a non
393 branch-specific manner.
394 When merges (or just m), pass the --rebase-merges option to git
396 rebase so that the local merge commits are included in the rebase
397 (see git-rebase(1) for details).
398 When the value is interactive (or just i), the rebase is run in
400 interactive mode.
401 NOTE: this is a possibly dangerous operation; do not use it unless
403 you understand the implications (see git-rebase(1) for details).
404 branch.<name>.description
406 Branch description, can be edited with git branch
407 --edit-description. Branch description is automatically added in
408 the format-patch cover letter or request-pull summary.
409
411 Start development from a known tag
412 $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
414 $ cd my2.6
415 $ git branch my2.6.14 v2.6.14 [1m(1)
416 $ git switch my2.6.14
417 1. This step and the next one could be combined into a single
419 step with "checkout -b my2.6.14 v2.6.14".
420 Delete an unneeded branch
422 $ git clone git://git.kernel.org/.../git.git my.git
424 $ cd my.git
425 $ git branch -d -r origin/todo origin/html origin/man [1m(1)
426 $ git branch -D test [1m(2)
427 1. Delete the remote-tracking branches "todo", "html" and
429 "man". The next fetch or pull will create them again
430 unless you configure them not to. See git-fetch(1).
431 2. Delete the "test" branch even if the "master" branch (or
432 whichever branch is currently checked out) does not have
433 all commits from the test branch.
434 Listing branches from a specific remote
436 $ git branch -r -l '<remote>/<pattern>' [1m(1)
438 $ git for-each-ref 'refs/remotes/<remote>/<pattern>' [1m(2)
439 1. Using -a would conflate <remote> with any local branches
441 you happen to have been prefixed with the same <remote>
442 pattern.
443 2. for-each-ref can take a wide range of options. See git-
444 for-each-ref(1)
445 Patterns will normally need quoting.
447
449 If you are creating a branch that you want to switch to immediately, it
450 is easier to use the "git switch" command with its -c option to do the
451 same thing with a single command.
452 The options --contains, --no-contains, --merged and --no-merged serve
454 four related but different purposes:
455 • --contains <commit> is used to find all branches which will need
457 special attention if <commit> were to be rebased or amended, since
458 those branches contain the specified <commit>.
459 • --no-contains <commit> is the inverse of that, i.e. branches that
461 don’t contain the specified <commit>.
462 • --merged is used to find all branches which can be safely deleted,
464 since those branches are fully contained by HEAD.
465 • --no-merged is used to find branches which are candidates for
467 merging into HEAD, since those branches are not fully contained by
468 HEAD.
469 When combining multiple --contains and --no-contains filters, only
471 references that contain at least one of the --contains commits and
472 contain none of the --no-contains commits are shown.
473 When combining multiple --merged and --no-merged filters, only
475 references that are reachable from at least one of the --merged commits
476 and from none of the --no-merged commits are shown.
477
479 git-check-ref-format(1), git-fetch(1), git-remote(1), “Understanding
480 history: What is a branch?”[1] in the Git User’s Manual.
481
483 Part of the git(1) suite
484
486 1. “Understanding history: What is a branch?”
487 file:///usr/share/doc/git/user-manual.html#what-is-a-branch
488Git 2.39.1 2023-01-13 GIT-BRANCH(1)