1git-branch(1) 2============= 3 4NAME 5---- 6git-branch - List, create, or delete branches 7 8SYNOPSIS 9-------- 10[verse] 11'git-branch' [--color | --no-color] [-r | -a] [--merged | --no-merged] 12 [-v [--abbrev=<length> | --no-abbrev]] 13 [--contains <commit>] 14'git-branch' [--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----------- 20With no arguments given a list of existing branches 21will be shown, the current branch will be highlighted with an asterisk. 22Option `-r` causes the remote-tracking branches to be listed, 23and option `-a` shows both. 24With `--contains <commit>`, shows only the branches that 25contains the named commit (in other words, the branches whose 26tip commits are descendant of the named commit). 27With `--merged`, only branches merged into HEAD will be listed, and 28with `--no-merged` only branches not merged into HEAD will be listed. 29 30In its second form, a new branch named <branchname> will be created. 31It will start out with a head equal to the one given as <start-point>. 32If no <start-point> is given, the branch will be created with a head 33equal to that of the currently checked out branch. 34 35Note that this will create the new branch, but it will not switch the 36working tree to it; use "git checkout <newbranch>" to switch to the 37new branch. 38 39When a local branch is started off a remote branch, git sets up the 40branch so that linkgit:git-pull[1] will appropriately merge from 41the remote branch. This behavior may be changed via the global 42`branch.autosetupmerge` configuration flag. That setting can be 43overridden by using the `--track` and `--no-track` options. 44 45With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. 46If <oldbranch> had a corresponding reflog, it is renamed to match 47<newbranch>, and a reflog entry is created to remember the branch 48renaming. If <newbranch> exists, -M must be used to force the rename 49to happen. 50 51With a `-d` or `-D` option, `<branchname>` will be deleted. You may 52specify more than one branch for deletion. If the branch currently 53has a reflog then the reflog will also be deleted. 54 55Use -r together with -d to delete remote-tracking branches. Note, that it 56only makes sense to delete remote-tracking branches if they no longer exist 57in remote repository or if linkgit:git-fetch[1] was configured not to fetch 58them again. See also 'prune' subcommand of linkgit:git-remote[1] for way to 59clean up all obsolete remote-tracking branches. 60 61 62OPTIONS 63------- 64-d:: 65 Delete a branch. The branch must be fully merged in HEAD. 66 67-D:: 68 Delete a branch irrespective of its merged status. 69 70-l:: 71 Create the branch's reflog. This activates recording of 72 all changes made to the branch ref, enabling use of date 73 based sha1 expressions such as "<branchname>@\{yesterday}". 74 75-f:: 76 Force the creation of a new branch even if it means deleting 77 a branch that already exists with the same name. 78 79-m:: 80 Move/rename a branch and the corresponding reflog. 81 82-M:: 83 Move/rename a branch even if the new branchname already exists. 84 85--color:: 86 Color branches to highlight current, local, and remote branches. 87 88--no-color:: 89 Turn off branch colors, even when the configuration file gives the 90 default to color output. 91 92-r:: 93 List or delete (if used with -d) the remote-tracking branches. 94 95-a:: 96 List both remote-tracking branches and local branches. 97 98-v:: 99--verbose:: 100 Show sha1 and commit subject line for each head. 101 102--abbrev=<length>:: 103 Alter minimum display length for sha1 in output listing, 104 default value is 7. 105 106--no-abbrev:: 107 Display the full sha1s in output listing rather than abbreviating them. 108 109--track:: 110 When creating a new branch, set up configuration so that git-pull 111 will automatically retrieve data from the start point, which must be 112 a branch. Use this if you always pull from the same upstream branch 113 into the new branch, and if you don't want to use "git pull 114 <repository> <refspec>" explicitly. This behavior is the default 115 when the start point is a remote branch. Set the 116 branch.autosetupmerge configuration variable to `false` if you want 117 git-checkout and git-branch to always behave as if '--no-track' were 118 given. Set it to `always` if you want this behavior when the 119 start-point is either a local or remote branch. 120 121--no-track:: 122 Ignore the branch.autosetupmerge configuration variable. 123 124--contains <commit>:: 125 Only list branches which contain the specified commit. 126 127--merged:: 128 Only list branches which are fully contained by HEAD. 129 130--no-merged:: 131 Do not list branches which are fully contained by HEAD. 132 133<branchname>:: 134 The name of the branch to create or delete. 135 The new branch name must pass all checks defined by 136 linkgit:git-check-ref-format[1]. Some of these checks 137 may restrict the characters allowed in a branch name. 138 139<start-point>:: 140 The new branch will be created with a HEAD equal to this. It may 141 be given as a branch name, a commit-id, or a tag. If this option 142 is omitted, the current branch is assumed. 143 144<oldbranch>:: 145 The name of an existing branch to rename. 146 147<newbranch>:: 148 The new name for an existing branch. The same restrictions as for 149 <branchname> applies. 150 151 152Examples 153-------- 154 155Start development off of a known tag:: 156+ 157------------ 158$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 159$ cd my2.6 160$ git branch my2.6.14 v2.6.14 <1> 161$ git checkout my2.6.14 162------------ 163+ 164<1> This step and the next one could be combined into a single step with 165"checkout -b my2.6.14 v2.6.14". 166 167Delete unneeded branch:: 168+ 169------------ 170$ git clone git://git.kernel.org/.../git.git my.git 171$ cd my.git 172$ git branch -d -r origin/todo origin/html origin/man <1> 173$ git branch -D test <2> 174------------ 175+ 176<1> Delete remote-tracking branches "todo", "html", "man". Next 'fetch' or 177'pull' will create them again unless you configure them not to. See 178linkgit:git-fetch[1]. 179<2> Delete "test" branch even if the "master" branch (or whichever branch is 180currently checked out) does not have all commits from test branch. 181 182 183Notes 184----- 185 186If you are creating a branch that you want to immediately checkout, it's 187easier to use the git checkout command with its `-b` option to create 188a branch and check it out with a single command. 189 190The options `--contains`, `--merged` and `--no-merged` serves three related 191but different purposes: 192 193- `--contains <commit>` is used to find all branches which will need 194 special attention if <commit> were to be rebased or amended, since those 195 branches contain the specified <commit>. 196 197- `--merged` is used to find all branches which can be safely deleted, 198 since those branches are fully contained by HEAD. 199 200- `--no-merged` is used to find branches which are candidates for merging 201 into HEAD, since those branches are not fully contained by HEAD. 202 203Author 204------ 205Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net> 206 207Documentation 208-------------- 209Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 210 211GIT 212--- 213Part of the linkgit:git[1] suite