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