1git-branch(1) 2============= 3 4NAME 5---- 6git-branch - List, create, or delete branches 7 8SYNOPSIS 9-------- 10[verse] 11'git branch' [--color[=<when>] | --no-color] [--show-current] 12 [-v [--abbrev=<length> | --no-abbrev]] 13 [--column[=<options>] | --no-column] [--sort=<key>] 14 [(--merged | --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 | --no-track] [-f] <branchname> [<start-point>] 20'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 21'git branch' --unset-upstream [<branchname>] 22'git branch' (-m | -M) [<oldbranch>] <newbranch> 23'git branch' (-c | -C) [<oldbranch>] <newbranch> 24'git branch' (-d | -D) [-r] <branchname>... 25'git branch' --edit-description [<branchname>] 26 27DESCRIPTION 28----------- 29 30If `--list` is given, or if there are no non-option arguments, existing 31branches are listed; the current branch will be highlighted in green and 32marked with an asterisk. Any branches checked out in linked worktrees will 33be highlighted in cyan and marked with a plus sign. Option `-r` causes the 34remote-tracking branches to be listed, 35and option `-a` shows both local and remote branches. 36 37If a `<pattern>` 38is given, it is used as a shell wildcard to restrict the output to 39matching branches. If multiple patterns are given, a branch is shown if 40it matches any of the patterns. 41 42Note that when providing a 43`<pattern>`, you must use `--list`; otherwise the command may be interpreted 44as branch creation. 45 46With `--contains`, shows only the branches that contain the named commit 47(in other words, the branches whose tip commits are descendants of the 48named commit), `--no-contains` inverts it. With `--merged`, only branches 49merged into the named commit (i.e. the branches whose tip commits are 50reachable from the named commit) will be listed. With `--no-merged` only 51branches not merged into the named commit will be listed. If the <commit> 52argument is missing it defaults to `HEAD` (i.e. the tip of the current 53branch). 54 55The command's second form creates a new branch head named <branchname> 56which points to the current `HEAD`, or <start-point> if given. As a 57special case, for <start-point>, you may use `"A...B"` as a shortcut for 58the merge base of `A` and `B` if there is exactly one merge base. You 59can leave out at most one of `A` and `B`, in which case it defaults to 60`HEAD`. 61 62Note that this will create the new branch, but it will not switch the 63working tree to it; use "git switch <newbranch>" to switch to the 64new branch. 65 66When a local branch is started off a remote-tracking branch, Git sets up the 67branch (specifically the `branch.<name>.remote` and `branch.<name>.merge` 68configuration entries) so that 'git pull' will appropriately merge from 69the remote-tracking branch. This behavior may be changed via the global 70`branch.autoSetupMerge` configuration flag. That setting can be 71overridden by using the `--track` and `--no-track` options, and 72changed later using `git branch --set-upstream-to`. 73 74With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>. 75If <oldbranch> had a corresponding reflog, it is renamed to match 76<newbranch>, and a reflog entry is created to remember the branch 77renaming. If <newbranch> exists, -M must be used to force the rename 78to happen. 79 80The `-c` and `-C` options have the exact same semantics as `-m` and 81`-M`, except instead of the branch being renamed it along with its 82config and reflog will be copied to a new name. 83 84With a `-d` or `-D` option, `<branchname>` will be deleted. You may 85specify more than one branch for deletion. If the branch currently 86has a reflog then the reflog will also be deleted. 87 88Use `-r` together with `-d` to delete remote-tracking branches. Note, that it 89only makes sense to delete remote-tracking branches if they no longer exist 90in the remote repository or if 'git fetch' was configured not to fetch 91them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a 92way to clean up all obsolete remote-tracking branches. 93 94 95OPTIONS 96------- 97-d:: 98--delete:: 99 Delete a branch. The branch must be fully merged in its 100 upstream branch, or in `HEAD` if no upstream was set with 101 `--track` or `--set-upstream-to`. 102 103-D:: 104 Shortcut for `--delete --force`. 105 106--create-reflog:: 107 Create the branch's reflog. This activates recording of 108 all changes made to the branch ref, enabling use of date 109 based sha1 expressions such as "<branchname>@\{yesterday}". 110 Note that in non-bare repositories, reflogs are usually 111 enabled by default by the `core.logAllRefUpdates` config option. 112 The negated form `--no-create-reflog` only overrides an earlier 113 `--create-reflog`, but currently does not negate the setting of 114 `core.logAllRefUpdates`. 115 116-f:: 117--force:: 118 Reset <branchname> to <startpoint>, even if <branchname> exists 119 already. Without `-f`, 'git branch' refuses to change an existing branch. 120 In combination with `-d` (or `--delete`), allow deleting the 121 branch irrespective of its merged status. In combination with 122 `-m` (or `--move`), allow renaming the branch even if the new 123 branch name already exists, the same applies for `-c` (or `--copy`). 124 125-m:: 126--move:: 127 Move/rename a branch and the corresponding reflog. 128 129-M:: 130 Shortcut for `--move --force`. 131 132-c:: 133--copy:: 134 Copy a branch and the corresponding reflog. 135 136-C:: 137 Shortcut for `--copy --force`. 138 139--color[=<when>]:: 140 Color branches to highlight current, local, and 141 remote-tracking branches. 142 The value must be always (the default), never, or auto. 143 144--no-color:: 145 Turn off branch colors, even when the configuration file gives the 146 default to color output. 147 Same as `--color=never`. 148 149-i:: 150--ignore-case:: 151 Sorting and filtering branches are case insensitive. 152 153--column[=<options>]:: 154--no-column:: 155 Display branch listing in columns. See configuration variable 156 column.branch for option syntax.`--column` and `--no-column` 157 without options are equivalent to 'always' and 'never' respectively. 158+ 159This option is only applicable in non-verbose mode. 160 161-r:: 162--remotes:: 163 List or delete (if used with -d) the remote-tracking branches. 164 Combine with `--list` to match the optional pattern(s). 165 166-a:: 167--all:: 168 List both remote-tracking branches and local branches. 169 Combine with `--list` to match optional pattern(s). 170 171-l:: 172--list:: 173 List branches. With optional `<pattern>...`, e.g. `git 174 branch --list 'maint-*'`, list only the branches that match 175 the pattern(s). 176 177--show-current:: 178 Print the name of the current branch. In detached HEAD state, 179 nothing is printed. 180 181-v:: 182-vv:: 183--verbose:: 184 When in list mode, 185 show sha1 and commit subject line for each head, along with 186 relationship to upstream branch (if any). If given twice, print 187 the path of the linked worktree (if any) and the name of the upstream 188 branch, as well (see also `git remote show <remote>`). Note that the 189 current worktree's HEAD will not have its path printed (it will always 190 be your current directory). 191 192-q:: 193--quiet:: 194 Be more quiet when creating or deleting a branch, suppressing 195 non-error messages. 196 197--abbrev=<length>:: 198 Alter the sha1's minimum display length in the output listing. 199 The default value is 7 and can be overridden by the `core.abbrev` 200 config option. 201 202--no-abbrev:: 203 Display the full sha1s in the output listing rather than abbreviating them. 204 205-t:: 206--track:: 207 When creating a new branch, set up `branch.<name>.remote` and 208 `branch.<name>.merge` configuration entries to mark the 209 start-point branch as "upstream" from the new branch. This 210 configuration will tell git to show the relationship between the 211 two branches in `git status` and `git branch -v`. Furthermore, 212 it directs `git pull` without arguments to pull from the 213 upstream when the new branch is checked out. 214+ 215This behavior is the default when the start point is a remote-tracking branch. 216Set the branch.autoSetupMerge configuration variable to `false` if you 217want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track` 218were given. Set it to `always` if you want this behavior when the 219start-point is either a local or remote-tracking branch. 220 221--no-track:: 222 Do not set up "upstream" configuration, even if the 223 branch.autoSetupMerge configuration variable is true. 224 225--set-upstream:: 226 As this option had confusing syntax, it is no longer supported. 227 Please use `--track` or `--set-upstream-to` instead. 228 229-u <upstream>:: 230--set-upstream-to=<upstream>:: 231 Set up <branchname>'s tracking information so <upstream> is 232 considered <branchname>'s upstream branch. If no <branchname> 233 is specified, then it defaults to the current branch. 234 235--unset-upstream:: 236 Remove the upstream information for <branchname>. If no branch 237 is specified it defaults to the current branch. 238 239--edit-description:: 240 Open an editor and edit the text to explain what the branch is 241 for, to be used by various other commands (e.g. `format-patch`, 242 `request-pull`, and `merge` (if enabled)). Multi-line explanations 243 may be used. 244 245--contains [<commit>]:: 246 Only list branches which contain the specified commit (HEAD 247 if not specified). Implies `--list`. 248 249--no-contains [<commit>]:: 250 Only list branches which don't contain the specified commit 251 (HEAD if not specified). Implies `--list`. 252 253--merged [<commit>]:: 254 Only list branches whose tips are reachable from the 255 specified commit (HEAD if not specified). Implies `--list`, 256 incompatible with `--no-merged`. 257 258--no-merged [<commit>]:: 259 Only list branches whose tips are not reachable from the 260 specified commit (HEAD if not specified). Implies `--list`, 261 incompatible with `--merged`. 262 263<branchname>:: 264 The name of the branch to create or delete. 265 The new branch name must pass all checks defined by 266 linkgit:git-check-ref-format[1]. Some of these checks 267 may restrict the characters allowed in a branch name. 268 269<start-point>:: 270 The new branch head will point to this commit. It may be 271 given as a branch name, a commit-id, or a tag. If this 272 option is omitted, the current HEAD will be used instead. 273 274<oldbranch>:: 275 The name of an existing branch to rename. 276 277<newbranch>:: 278 The new name for an existing branch. The same restrictions as for 279 <branchname> apply. 280 281--sort=<key>:: 282 Sort based on the key given. Prefix `-` to sort in descending 283 order of the value. You may use the --sort=<key> option 284 multiple times, in which case the last key becomes the primary 285 key. The keys supported are the same as those in `git 286 for-each-ref`. Sort order defaults to the value configured for the 287 `branch.sort` variable if exists, or to sorting based on the 288 full refname (including `refs/...` prefix). This lists 289 detached HEAD (if present) first, then local branches and 290 finally remote-tracking branches. See linkgit:git-config[1]. 291 292 293--points-at <object>:: 294 Only list branches of the given object. 295 296--format <format>:: 297 A string that interpolates `%(fieldname)` from a branch ref being shown 298 and the object it points at. The format is the same as 299 that of linkgit:git-for-each-ref[1]. 300 301CONFIGURATION 302------------- 303`pager.branch` is only respected when listing branches, i.e., when 304`--list` is used or implied. The default is to use a pager. 305See linkgit:git-config[1]. 306 307EXAMPLES 308-------- 309 310Start development from a known tag:: 311+ 312------------ 313$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 314$ cd my2.6 315$ git branch my2.6.14 v2.6.14 <1> 316$ git switch my2.6.14 317------------ 318+ 319<1> This step and the next one could be combined into a single step with 320 "checkout -b my2.6.14 v2.6.14". 321 322Delete an unneeded branch:: 323+ 324------------ 325$ git clone git://git.kernel.org/.../git.git my.git 326$ cd my.git 327$ git branch -d -r origin/todo origin/html origin/man <1> 328$ git branch -D test <2> 329------------ 330+ 331<1> Delete the remote-tracking branches "todo", "html" and "man". The next 332 'fetch' or 'pull' will create them again unless you configure them not to. 333 See linkgit:git-fetch[1]. 334<2> Delete the "test" branch even if the "master" branch (or whichever branch 335 is currently checked out) does not have all commits from the test branch. 336 337Listing branches from a specific remote:: 338+ 339------------ 340$ git branch -r -l '<remote>/<pattern>' <1> 341$ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2> 342------------ 343+ 344<1> Using `-a` would conflate <remote> with any local branches you happen to 345 have been prefixed with the same <remote> pattern. 346<2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1] 347 348Patterns will normally need quoting. 349 350NOTES 351----- 352 353If you are creating a branch that you want to switch to immediately, 354it is easier to use the "git switch" command with its `-c` option to 355do the same thing with a single command. 356 357The options `--contains`, `--no-contains`, `--merged` and `--no-merged` 358serve four related but different purposes: 359 360- `--contains <commit>` is used to find all branches which will need 361 special attention if <commit> were to be rebased or amended, since those 362 branches contain the specified <commit>. 363 364- `--no-contains <commit>` is the inverse of that, i.e. branches that don't 365 contain the specified <commit>. 366 367- `--merged` is used to find all branches which can be safely deleted, 368 since those branches are fully contained by HEAD. 369 370- `--no-merged` is used to find branches which are candidates for merging 371 into HEAD, since those branches are not fully contained by HEAD. 372 373SEE ALSO 374-------- 375linkgit:git-check-ref-format[1], 376linkgit:git-fetch[1], 377linkgit:git-remote[1], 378link:user-manual.html#what-is-a-branch[``Understanding history: What is 379a branch?''] in the Git User's Manual. 380 381GIT 382--- 383Part of the linkgit:git[1] suite