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