| '\" t |
| .\" Title: git-branch |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 02/06/2019 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.21.0.rc0 |
| .\" Language: English |
| .\" |
| .TH "GIT\-BRANCH" "1" "02/06/2019" "Git 2\&.21\&.0\&.rc0" "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] [\-r | \-a] |
| [\-\-list] [\-v [\-\-abbrev=<length> | \-\-no\-abbrev]] |
| [\-\-column[=<options>] | \-\-no\-column] [\-\-sort=<key>] |
| [(\-\-merged | \-\-no\-merged) [<commit>]] |
| [\-\-contains [<commit]] [\-\-no\-contains [<commit>]] |
| [\-\-points\-at <object>] [\-\-format=<format>] [<pattern>\&...] |
| \fIgit branch\fR [\-\-track | \-\-no\-track] [\-f] <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 with an asterisk\&. Option \fB\-r\fR causes the remote\-tracking branches to be listed, and option \fB\-a\fR shows both local and remote branches\&. 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\&. Note that when providing a \fB<pattern>\fR, you must use \fB\-\-list\fR; otherwise the command is 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\&. |
| .sp |
| Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <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 along with its config and reflog will be copied to a new name\&. |
| .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\&. 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 and the corresponding reflog\&. |
| .RE |
| .PP |
| \-M |
| .RS 4 |
| Shortcut for |
| \fB\-\-move \-\-force\fR\&. |
| .RE |
| .PP |
| \-c, \-\-copy |
| .RS 4 |
| Copy a branch and the corresponding 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 column\&.branch 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\&. |
| .RE |
| .PP |
| \-a, \-\-all |
| .RS 4 |
| List both remote\-tracking branches and local branches\&. |
| .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 |
| \-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 name of the upstream branch, as well (see also |
| \fBgit remote show <remote>\fR)\&. |
| .RE |
| .PP |
| \-q, \-\-quiet |
| .RS 4 |
| Be more quiet when creating or deleting a branch, suppressing non\-error messages\&. |
| .RE |
| .PP |
| \-\-abbrev=<length> |
| .RS 4 |
| Alter the sha1\(cqs minimum display length in the output listing\&. 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 |
| .RS 4 |
| When creating a new branch, set up |
| \fBbranch\&.<name>\&.remote\fR |
| and |
| \fBbranch\&.<name>\&.merge\fR |
| configuration entries to mark the start\-point branch as "upstream" from 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 |
| This behavior 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 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\&. |
| .RE |
| .PP |
| \-\-no\-track |
| .RS 4 |
| Do not set up "upstream" configuration, even if the branch\&.autoSetupMerge configuration variable is true\&. |
| .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, incompatible with |
| \fB\-\-no\-merged\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, incompatible with |
| \fB\-\-merged\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 checkout 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 |
| .SH "NOTES" |
| .sp |
| If you are creating a branch that you want to checkout immediately, it is easier to use the git checkout command with its \fB\-b\fR option to create a branch and check it out 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 |
| .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 |