man1/git-branch.1

'\" t
.\"     Title: git-branch
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/07/2022
.\"    Manual: Git Manual
.\"    Source: Git 2.35.1.415.gc2162907e9
.\"  Language: English
.\"
.TH "GIT\-BRANCH" "1" "03/07/2022" "Git 2\&.35\&.1\&.415\&.gc21629" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-branch \- List, create, or delete branches
.SH "SYNOPSIS"
.sp
.nf
\fIgit branch\fR [\-\-color[=<when>] | \-\-no\-color] [\-\-show\-current]
        [\-v [\-\-abbrev=<n> | \-\-no\-abbrev]]
        [\-\-column[=<options>] | \-\-no\-column] [\-\-sort=<key>]
        [\-\-merged [<commit>]] [\-\-no\-merged [<commit>]]
        [\-\-contains [<commit>]] [\-\-no\-contains [<commit>]]
        [\-\-points\-at <object>] [\-\-format=<format>]
        [(\-r | \-\-remotes) | (\-a | \-\-all)]
        [\-\-list] [<pattern>\&...]
\fIgit branch\fR [\-\-track[=(direct|inherit)] | \-\-no\-track] [\-f]
        [\-\-recurse\-submodules] <branchname> [<start\-point>]
\fIgit branch\fR (\-\-set\-upstream\-to=<upstream> | \-u <upstream>) [<branchname>]
\fIgit branch\fR \-\-unset\-upstream [<branchname>]
\fIgit branch\fR (\-m | \-M) [<oldbranch>] <newbranch>
\fIgit branch\fR (\-c | \-C) [<oldbranch>] <newbranch>
\fIgit branch\fR (\-d | \-D) [\-r] <branchname>\&...
\fIgit branch\fR \-\-edit\-description [<branchname>]
.fi
.sp
.SH "DESCRIPTION"
.sp
If \fB\-\-list\fR is given, or if there are no non\-option arguments, existing branches are listed; the current branch will be highlighted in green and marked with an asterisk\&. Any branches checked out in linked worktrees will be highlighted in cyan and marked with a plus sign\&. Option \fB\-r\fR causes the remote\-tracking branches to be listed, and option \fB\-a\fR shows both local and remote branches\&.
.sp
If a \fB<pattern>\fR is given, it is used as a shell wildcard to restrict the output to matching branches\&. If multiple patterns are given, a branch is shown if it matches any of the patterns\&.
.sp
Note that when providing a \fB<pattern>\fR, you must use \fB\-\-list\fR; otherwise the command may be interpreted as branch creation\&.
.sp
With \fB\-\-contains\fR, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the named commit), \fB\-\-no\-contains\fR inverts it\&. With \fB\-\-merged\fR, only branches merged into the named commit (i\&.e\&. the branches whose tip commits are reachable from the named commit) will be listed\&. With \fB\-\-no\-merged\fR only branches not merged into the named commit will be listed\&. If the <commit> argument is missing it defaults to \fBHEAD\fR (i\&.e\&. the tip of the current branch)\&.
.sp
The command\(cqs second form creates a new branch head named <branchname> which points to the current \fBHEAD\fR, or <start\-point> if given\&. As a special case, for <start\-point>, you may use \fB"A\&.\&.\&.B"\fR as a shortcut for the merge base of \fBA\fR and \fBB\fR if there is exactly one merge base\&. You can leave out at most one of \fBA\fR and \fBB\fR, in which case it defaults to \fBHEAD\fR\&.
.sp
Note that this will create the new branch, but it will not switch the working tree to it; use "git switch <newbranch>" to switch to the new branch\&.
.sp
When a local branch is started off a remote\-tracking branch, Git sets up the branch (specifically the \fBbranch\&.<name>\&.remote\fR and \fBbranch\&.<name>\&.merge\fR configuration entries) so that \fIgit pull\fR will appropriately merge from the remote\-tracking branch\&. This behavior may be changed via the global \fBbranch\&.autoSetupMerge\fR configuration flag\&. That setting can be overridden by using the \fB\-\-track\fR and \fB\-\-no\-track\fR options, and changed later using \fBgit branch \-\-set\-upstream\-to\fR\&.
.sp
With a \fB\-m\fR or \fB\-M\fR option, <oldbranch> will be renamed to <newbranch>\&. If <oldbranch> had a corresponding reflog, it is renamed to match <newbranch>, and a reflog entry is created to remember the branch renaming\&. If <newbranch> exists, \-M must be used to force the rename to happen\&.
.sp
The \fB\-c\fR and \fB\-C\fR options have the exact same semantics as \fB\-m\fR and \fB\-M\fR, except instead of the branch being renamed, it will be copied to a new name, along with its config and reflog\&.
.sp
With a \fB\-d\fR or \fB\-D\fR option, \fB<branchname>\fR will be deleted\&. You may specify more than one branch for deletion\&. If the branch currently has a reflog then the reflog will also be deleted\&.
.sp
Use \fB\-r\fR together with \fB\-d\fR to delete remote\-tracking branches\&. Note, that it only makes sense to delete remote\-tracking branches if they no longer exist in the remote repository or if \fIgit fetch\fR was configured not to fetch them again\&. See also the \fIprune\fR subcommand of \fBgit-remote\fR(1) for a way to clean up all obsolete remote\-tracking branches\&.
.SH "OPTIONS"
.PP
\-d, \-\-delete
.RS 4
Delete a branch\&. The branch must be fully merged in its upstream branch, or in
\fBHEAD\fR
if no upstream was set with
\fB\-\-track\fR
or
\fB\-\-set\-upstream\-to\fR\&.
.RE
.PP
\-D
.RS 4
Shortcut for
\fB\-\-delete \-\-force\fR\&.
.RE
.PP
\-\-create\-reflog
.RS 4
Create the branch\(cqs reflog\&. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@{yesterday}"\&. Note that in non\-bare repositories, reflogs are usually enabled by default by the
\fBcore\&.logAllRefUpdates\fR
config option\&. The negated form
\fB\-\-no\-create\-reflog\fR
only overrides an earlier
\fB\-\-create\-reflog\fR, but currently does not negate the setting of
\fBcore\&.logAllRefUpdates\fR\&.
.RE
.PP
\-f, \-\-force
.RS 4
Reset <branchname> to <startpoint>, even if <branchname> exists already\&. Without
\fB\-f\fR,
\fIgit branch\fR
refuses to change an existing branch\&. In combination with
\fB\-d\fR
(or
\fB\-\-delete\fR), allow deleting the branch irrespective of its merged status, or whether it even points to a valid commit\&. In combination with
\fB\-m\fR
(or
\fB\-\-move\fR), allow renaming the branch even if the new branch name already exists, the same applies for
\fB\-c\fR
(or
\fB\-\-copy\fR)\&.
.RE
.PP
\-m, \-\-move
.RS 4
Move/rename a branch, together with its config and reflog\&.
.RE
.PP
\-M
.RS 4
Shortcut for
\fB\-\-move \-\-force\fR\&.
.RE
.PP
\-c, \-\-copy
.RS 4
Copy a branch, together with its config and reflog\&.
.RE
.PP
\-C
.RS 4
Shortcut for
\fB\-\-copy \-\-force\fR\&.
.RE
.PP
\-\-color[=<when>]
.RS 4
Color branches to highlight current, local, and remote\-tracking branches\&. The value must be always (the default), never, or auto\&.
.RE
.PP
\-\-no\-color
.RS 4
Turn off branch colors, even when the configuration file gives the default to color output\&. Same as
\fB\-\-color=never\fR\&.
.RE
.PP
\-i, \-\-ignore\-case
.RS 4
Sorting and filtering branches are case insensitive\&.
.RE
.PP
\-\-column[=<options>], \-\-no\-column
.RS 4
Display branch listing in columns\&. See configuration variable
\fBcolumn\&.branch\fR
for option syntax\&.
\fB\-\-column\fR
and
\fB\-\-no\-column\fR
without options are equivalent to
\fIalways\fR
and
\fInever\fR
respectively\&.
.sp
This option is only applicable in non\-verbose mode\&.
.RE
.PP
\-r, \-\-remotes
.RS 4
List or delete (if used with \-d) the remote\-tracking branches\&. Combine with
\fB\-\-list\fR
to match the optional pattern(s)\&.
.RE
.PP
\-a, \-\-all
.RS 4
List both remote\-tracking branches and local branches\&. Combine with
\fB\-\-list\fR
to match optional pattern(s)\&.
.RE
.PP
\-l, \-\-list
.RS 4
List branches\&. With optional
\fB<pattern>\&.\&.\&.\fR, e\&.g\&.
\fBgit branch \-\-list \(aqmaint\-*\(aq\fR, list only the branches that match the pattern(s)\&.
.RE
.PP
\-\-show\-current
.RS 4
Print the name of the current branch\&. In detached HEAD state, nothing is printed\&.
.RE
.PP
\-v, \-vv, \-\-verbose
.RS 4
When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any)\&. If given twice, print the path of the linked worktree (if any) and the name of the upstream branch, as well (see also
\fBgit remote show <remote>\fR)\&. Note that the current worktree\(cqs HEAD will not have its path printed (it will always be your current directory)\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
Be more quiet when creating or deleting a branch, suppressing non\-error messages\&.
.RE
.PP
\-\-abbrev=<n>
.RS 4
In the verbose listing that show the commit object name, show the shortest prefix that is at least
\fI<n>\fR
hexdigits long that uniquely refers the object\&. The default value is 7 and can be overridden by the
\fBcore\&.abbrev\fR
config option\&.
.RE
.PP
\-\-no\-abbrev
.RS 4
Display the full sha1s in the output listing rather than abbreviating them\&.
.RE
.PP
\-t, \-\-track[=(direct|inherit)]
.RS 4
When creating a new branch, set up
\fBbranch\&.<name>\&.remote\fR
and
\fBbranch\&.<name>\&.merge\fR
configuration entries to set "upstream" tracking configuration for the new branch\&. This configuration will tell git to show the relationship between the two branches in
\fBgit status\fR
and
\fBgit branch \-v\fR\&. Furthermore, it directs
\fBgit pull\fR
without arguments to pull from the upstream when the new branch is checked out\&.
.sp
The exact upstream branch is chosen depending on the optional argument:
\fB\-t\fR,
\fB\-\-track\fR, or
\fB\-\-track=direct\fR
means to use the start\-point branch itself as the upstream;
\fB\-\-track=inherit\fR
means to copy the upstream configuration of the start\-point branch\&.
.sp
\fB\-\-track=direct\fR
is the default when the start point is a remote\-tracking branch\&. Set the branch\&.autoSetupMerge configuration variable to
\fBfalse\fR
if you want
\fBgit switch\fR,
\fBgit checkout\fR
and
\fBgit branch\fR
to always behave as if
\fB\-\-no\-track\fR
were given\&. Set it to
\fBalways\fR
if you want this behavior when the start\-point is either a local or remote\-tracking branch\&. Set it to
\fBinherit\fR
if you want to copy the tracking configuration from the branch point\&.
.sp
See
\fBgit-pull\fR(1)
and
\fBgit-config\fR(1)
for additional discussion on how the
\fBbranch\&.<name>\&.remote\fR
and
\fBbranch\&.<name>\&.merge\fR
options are used\&.
.RE
.PP
\-\-no\-track
.RS 4
Do not set up "upstream" configuration, even if the branch\&.autoSetupMerge configuration variable is set\&.
.RE
.PP
\-\-recurse\-submodules
.RS 4
THIS OPTION IS EXPERIMENTAL! Causes the current command to recurse into submodules if
\fBsubmodule\&.propagateBranches\fR
is enabled\&. See
\fBsubmodule\&.propagateBranches\fR
in
\fBgit-config\fR(1)\&. Currently, only branch creation is supported\&.
.sp
When used in branch creation, a new branch <branchname> will be created in the superproject and all of the submodules in the superproject\(cqs <start\-point>\&. In submodules, the branch will point to the submodule commit in the superproject\(cqs <start\-point> but the branch\(cqs tracking information will be set up based on the submodule\(cqs branches and remotes e\&.g\&.
\fBgit branch \-\-recurse\-submodules topic origin/main\fR
will create the submodule branch "topic" that points to the submodule commit in the superproject\(cqs "origin/main", but tracks the submodule\(cqs "origin/main"\&.
.RE
.PP
\-\-set\-upstream
.RS 4
As this option had confusing syntax, it is no longer supported\&. Please use
\fB\-\-track\fR
or
\fB\-\-set\-upstream\-to\fR
instead\&.
.RE
.PP
\-u <upstream>, \-\-set\-upstream\-to=<upstream>
.RS 4
Set up <branchname>\(aqs tracking information so <upstream> is considered <branchname>\(aqs upstream branch\&. If no <branchname> is specified, then it defaults to the current branch\&.
.RE
.PP
\-\-unset\-upstream
.RS 4
Remove the upstream information for <branchname>\&. If no branch is specified it defaults to the current branch\&.
.RE
.PP
\-\-edit\-description
.RS 4
Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e\&.g\&.
\fBformat\-patch\fR,
\fBrequest\-pull\fR, and
\fBmerge\fR
(if enabled))\&. Multi\-line explanations may be used\&.
.RE
.PP
\-\-contains [<commit>]
.RS 4
Only list branches which contain the specified commit (HEAD if not specified)\&. Implies
\fB\-\-list\fR\&.
.RE
.PP
\-\-no\-contains [<commit>]
.RS 4
Only list branches which don\(cqt contain the specified commit (HEAD if not specified)\&. Implies
\fB\-\-list\fR\&.
.RE
.PP
\-\-merged [<commit>]
.RS 4
Only list branches whose tips are reachable from the specified commit (HEAD if not specified)\&. Implies
\fB\-\-list\fR\&.
.RE
.PP
\-\-no\-merged [<commit>]
.RS 4
Only list branches whose tips are not reachable from the specified commit (HEAD if not specified)\&. Implies
\fB\-\-list\fR\&.
.RE
.PP
<branchname>
.RS 4
The name of the branch to create or delete\&. The new branch name must pass all checks defined by
\fBgit-check-ref-format\fR(1)\&. Some of these checks may restrict the characters allowed in a branch name\&.
.RE
.PP
<start\-point>
.RS 4
The new branch head will point to this commit\&. It may be given as a branch name, a commit\-id, or a tag\&. If this option is omitted, the current HEAD will be used instead\&.
.RE
.PP
<oldbranch>
.RS 4
The name of an existing branch to rename\&.
.RE
.PP
<newbranch>
.RS 4
The new name for an existing branch\&. The same restrictions as for <branchname> apply\&.
.RE
.PP
\-\-sort=<key>
.RS 4
Sort based on the key given\&. Prefix
\fB\-\fR
to sort in descending order of the value\&. You may use the \-\-sort=<key> option multiple times, in which case the last key becomes the primary key\&. The keys supported are the same as those in
\fBgit for\-each\-ref\fR\&. Sort order defaults to the value configured for the
\fBbranch\&.sort\fR
variable if exists, or to sorting based on the full refname (including
\fBrefs/\&.\&.\&.\fR
prefix)\&. This lists detached HEAD (if present) first, then local branches and finally remote\-tracking branches\&. See
\fBgit-config\fR(1)\&.
.RE
.PP
\-\-points\-at <object>
.RS 4
Only list branches of the given object\&.
.RE
.PP
\-\-format <format>
.RS 4
A string that interpolates
\fB%(fieldname)\fR
from a branch ref being shown and the object it points at\&. The format is the same as that of
\fBgit-for-each-ref\fR(1)\&.
.RE
.SH "CONFIGURATION"
.sp
\fBpager\&.branch\fR is only respected when listing branches, i\&.e\&., when \fB\-\-list\fR is used or implied\&. The default is to use a pager\&. See \fBgit-config\fR(1)\&.
.SH "EXAMPLES"
.PP
Start development from a known tag
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
$ git clone git://git\&.kernel\&.org/pub/scm/\&.\&.\&./linux\-2\&.6 my2\&.6
$ cd my2\&.6
$ git branch my2\&.6\&.14 v2\&.6\&.14   \fB(1)\fR
$ git switch my2\&.6\&.14
.fi
.if n \{\
.RE
.\}
.sp
\fB1. \fRThis step and the next one could be combined into a single step with "checkout \-b my2\&.6\&.14 v2\&.6\&.14"\&.
.br
.RE
.PP
Delete an unneeded branch
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
$ git clone git://git\&.kernel\&.org/\&.\&.\&./git\&.git my\&.git
$ cd my\&.git
$ git branch \-d \-r origin/todo origin/html origin/man   \fB(1)\fR
$ git branch \-D test                                    \fB(2)\fR
.fi
.if n \{\
.RE
.\}
.sp
\fB1. \fRDelete the remote\-tracking branches "todo", "html" and "man"\&. The next
\fIfetch\fR
or
\fIpull\fR
will create them again unless you configure them not to\&. See
\fBgit-fetch\fR(1)\&.
.br
\fB2. \fRDelete the "test" branch even if the "master" branch (or whichever branch is currently checked out) does not have all commits from the test branch\&.
.br
.RE
.PP
Listing branches from a specific remote
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
$ git branch \-r \-l \(aq<remote>/<pattern>\(aq                 \fB(1)\fR
$ git for\-each\-ref \(aqrefs/remotes/<remote>/<pattern>\(aq    \fB(2)\fR
.fi
.if n \{\
.RE
.\}
.sp
\fB1. \fRUsing
\fB\-a\fR
would conflate <remote> with any local branches you happen to have been prefixed with the same <remote> pattern\&.
.br
\fB2. \fR\fBfor\-each\-ref\fR
can take a wide range of options\&. See
\fBgit-for-each-ref\fR(1)
.br
.RE
.sp
Patterns will normally need quoting\&.
.SH "NOTES"
.sp
If you are creating a branch that you want to switch to immediately, it is easier to use the "git switch" command with its \fB\-c\fR option to do the same thing with a single command\&.
.sp
The options \fB\-\-contains\fR, \fB\-\-no\-contains\fR, \fB\-\-merged\fR and \fB\-\-no\-merged\fR serve four related but different purposes:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-contains <commit>\fR
is used to find all branches which will need special attention if <commit> were to be rebased or amended, since those branches contain the specified <commit>\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-no\-contains <commit>\fR
is the inverse of that, i\&.e\&. branches that don\(cqt contain the specified <commit>\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-merged\fR
is used to find all branches which can be safely deleted, since those branches are fully contained by HEAD\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-no\-merged\fR
is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD\&.
.RE
.sp
When combining multiple \fB\-\-contains\fR and \fB\-\-no\-contains\fR filters, only references that contain at least one of the \fB\-\-contains\fR commits and contain none of the \fB\-\-no\-contains\fR commits are shown\&.
.sp
When combining multiple \fB\-\-merged\fR and \fB\-\-no\-merged\fR filters, only references that are reachable from at least one of the \fB\-\-merged\fR commits and from none of the \fB\-\-no\-merged\fR commits are shown\&.
.SH "SEE ALSO"
.sp
\fBgit-check-ref-format\fR(1), \fBgit-fetch\fR(1), \fBgit-remote\fR(1), \m[blue]\fB\(lqUnderstanding history: What is a branch?\(rq\fR\m[]\&\s-2\u[1]\d\s+2 in the Git User\(cqs Manual\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite
.SH "NOTES"
.IP " 1." 4
\(lqUnderstanding history: What is a branch?\(rq
.RS 4
\%git-htmldocs/user-manual.html#what-is-a-branch
.RE