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