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