Documentation/git-branch.txt

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