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] [-v [--abbrev=<length> | --no-abbrev]] 13 [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] 14'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 15'git branch' (-m | -M) [<oldbranch>] <newbranch> 16'git branch' (-d | -D) [-r] <branchname>... 17 18DESCRIPTION 19----------- 20 21With no arguments, existing branches are listed and the current branch will 22be highlighted with an asterisk. Option `-r` causes the remote-tracking 23branches to be listed, and option `-a` shows both. This list mode is also 24activated by the `--list` option (see below). 25<pattern> restricts the output to matching branches, the pattern is a shell 26wildcard (i.e., matched using fnmatch(3)) 27Multiple patterns may be given; if any of them matches, the tag is shown. 28 29With `--contains`, shows only the branches that contain the named commit 30(in other words, the branches whose tip commits are descendants of the 31named commit). With `--merged`, only branches merged into the named 32commit (i.e. the branches whose tip commits are reachable from the named 33commit) will be listed. With `--no-merged` only branches not merged into 34the named commit will be listed. If the <commit> argument is missing it 35defaults to 'HEAD' (i.e. the tip of the current branch). 36 37The command's second form creates a new branch head named <branchname> 38which points to the current 'HEAD', or <start-point> if given. 39 40Note that this will create the new branch, but it will not switch the 41working tree to it; use "git checkout <newbranch>" to switch to the 42new branch. 43 44When a local branch is started off a remote-tracking branch, git sets up the 45branch so that 'git pull' will appropriately merge from 46the remote-tracking branch. This behavior may be changed via the global 47`branch.autosetupmerge` configuration flag. That setting can be 48overridden by using the `--track` and `--no-track` options, and 49changed later using `git branch --set-upstream`. 50 51With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. 52If <oldbranch> had a corresponding reflog, it is renamed to match 53<newbranch>, and a reflog entry is created to remember the branch 54renaming. If <newbranch> exists, -M must be used to force the rename 55to happen. 56 57With a `-d` or `-D` option, `<branchname>` will be deleted. You may 58specify more than one branch for deletion. If the branch currently 59has a reflog then the reflog will also be deleted. 60 61Use -r together with -d to delete remote-tracking branches. Note, that it 62only makes sense to delete remote-tracking branches if they no longer exist 63in the remote repository or if 'git fetch' was configured not to fetch 64them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a 65way to clean up all obsolete remote-tracking branches. 66 67 68OPTIONS 69------- 70-d:: 71--delete:: 72 Delete a branch. The branch must be fully merged in its 73 upstream branch, or in `HEAD` if no upstream was set with 74 `--track` or `--set-upstream`. 75 76-D:: 77 Delete a branch irrespective of its merged status. 78 79-l:: 80--create-reflog:: 81 Create the branch's reflog. This activates recording of 82 all changes made to the branch ref, enabling use of date 83 based sha1 expressions such as "<branchname>@\{yesterday}". 84 Note that in non-bare repositories, reflogs are usually 85 enabled by default by the `core.logallrefupdates` config option. 86 87-f:: 88--force:: 89 Reset <branchname> to <startpoint> if <branchname> exists 90 already. Without `-f` 'git branch' refuses to change an existing branch. 91 92-m:: 93--move:: 94 Move/rename a branch and the corresponding reflog. 95 96-M:: 97 Move/rename a branch even if the new branch name already exists. 98 99--color[=<when>]:: 100 Color branches to highlight current, local, and 101 remote-tracking branches. 102 The value must be always (the default), never, or auto. 103 104--no-color:: 105 Turn off branch colors, even when the configuration file gives the 106 default to color output. 107 Same as `--color=never`. 108 109-r:: 110--remotes:: 111 List or delete (if used with -d) the remote-tracking branches. 112 113-a:: 114--all:: 115 List both remote-tracking branches and local branches. 116 117--list:: 118 Activate the list mode. `git branch <pattern>` would try to create a branch, 119 use `git branch --list <pattern>` to list matching branches. 120 121-v:: 122--verbose:: 123 When in list mode, 124 show sha1 and commit subject line for each head, along with 125 relationship to upstream branch (if any). If given twice, print 126 the name of the upstream branch, as well. 127 128--abbrev=<length>:: 129 Alter the sha1's minimum display length in the output listing. 130 The default value is 7 and can be overridden by the `core.abbrev` 131 config option. 132 133--no-abbrev:: 134 Display the full sha1s in the output listing rather than abbreviating them. 135 136-t:: 137--track:: 138 When creating a new branch, set up configuration to mark the 139 start-point branch as "upstream" from the new branch. This 140 configuration will tell git to show the relationship between the 141 two branches in `git status` and `git branch -v`. Furthermore, 142 it directs `git pull` without arguments to pull from the 143 upstream when the new branch is checked out. 144+ 145This behavior is the default when the start point is a remote-tracking branch. 146Set the branch.autosetupmerge configuration variable to `false` if you 147want `git checkout` and `git branch` to always behave as if '--no-track' 148were given. Set it to `always` if you want this behavior when the 149start-point is either a local or remote-tracking branch. 150 151--no-track:: 152 Do not set up "upstream" configuration, even if the 153 branch.autosetupmerge configuration variable is true. 154 155--set-upstream:: 156 If specified branch does not exist yet or if '--force' has been 157 given, acts exactly like '--track'. Otherwise sets up configuration 158 like '--track' would when creating the branch, except that where 159 branch points to is not changed. 160 161--contains <commit>:: 162 Only list branches which contain the specified commit. 163 164--merged [<commit>]:: 165 Only list branches whose tips are reachable from the 166 specified commit (HEAD if not specified). 167 168--no-merged [<commit>]:: 169 Only list branches whose tips are not reachable from the 170 specified commit (HEAD if not specified). 171 172<branchname>:: 173 The name of the branch to create or delete. 174 The new branch name must pass all checks defined by 175 linkgit:git-check-ref-format[1]. Some of these checks 176 may restrict the characters allowed in a branch name. 177 178<start-point>:: 179 The new branch head will point to this commit. It may be 180 given as a branch name, a commit-id, or a tag. If this 181 option is omitted, the current HEAD will be used instead. 182 183<oldbranch>:: 184 The name of an existing branch to rename. 185 186<newbranch>:: 187 The new name for an existing branch. The same restrictions as for 188 <branchname> apply. 189 190 191Examples 192-------- 193 194Start development from a known tag:: 195+ 196------------ 197$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 198$ cd my2.6 199$ git branch my2.6.14 v2.6.14 <1> 200$ git checkout my2.6.14 201------------ 202+ 203<1> This step and the next one could be combined into a single step with 204"checkout -b my2.6.14 v2.6.14". 205 206Delete an unneeded branch:: 207+ 208------------ 209$ git clone git://git.kernel.org/.../git.git my.git 210$ cd my.git 211$ git branch -d -r origin/todo origin/html origin/man <1> 212$ git branch -D test <2> 213------------ 214+ 215<1> Delete the remote-tracking branches "todo", "html" and "man". The next 216'fetch' or 'pull' will create them again unless you configure them not to. 217See linkgit:git-fetch[1]. 218<2> Delete the "test" branch even if the "master" branch (or whichever branch 219is currently checked out) does not have all commits from the test branch. 220 221 222Notes 223----- 224 225If you are creating a branch that you want to checkout immediately, it is 226easier to use the git checkout command with its `-b` option to create 227a branch and check it out with a single command. 228 229The options `--contains`, `--merged` and `--no-merged` serve three related 230but different purposes: 231 232- `--contains <commit>` is used to find all branches which will need 233 special attention if <commit> were to be rebased or amended, since those 234 branches contain the specified <commit>. 235 236- `--merged` is used to find all branches which can be safely deleted, 237 since those branches are fully contained by HEAD. 238 239- `--no-merged` is used to find branches which are candidates for merging 240 into HEAD, since those branches are not fully contained by HEAD. 241 242SEE ALSO 243-------- 244linkgit:git-check-ref-format[1], 245linkgit:git-fetch[1], 246linkgit:git-remote[1], 247link:user-manual.html#what-is-a-branch[``Understanding history: What is 248a branch?''] in the Git User's Manual. 249 250GIT 251--- 252Part of the linkgit:git[1] suite