1git-checkout(1) 2=============== 3 4NAME 5---- 6git-checkout - Checkout a branch or paths to the working tree 7 8SYNOPSIS 9-------- 10[verse] 11'git checkout' [-q] [-f] [[--track | --no-track] -b <new_branch> [-l]] [-m] [<branch>] 12'git checkout' [-f|--ours|--theirs|-m] [<tree-ish>] [--] <paths>... 13 14DESCRIPTION 15----------- 16 17When <paths> are not given, this command switches branches by 18updating the index and working tree to reflect the specified 19branch, <branch>, and updating HEAD to be <branch> or, if 20specified, <new_branch>. Using -b will cause <new_branch> to 21be created; in this case you can use the --track or --no-track 22options, which will be passed to `git branch`. 23 24When <paths> are given, this command does *not* switch 25branches. It updates the named paths in the working tree from 26the index file, or from a named commit. In 27this case, the `-b` options is meaningless and giving 28either of them results in an error. <tree-ish> argument can be 29used to specify a specific tree-ish (i.e. commit, tag or tree) 30to update the index for the given paths before updating the 31working tree. 32 33The index may contain unmerged entries after a failed merge. By 34default, if you try to check out such an entry from the index, the 35checkout operation will fail and nothing will be checked out. 36Using -f will ignore these unmerged entries. The contents from a 37specific side of the merge can be checked out of the index by 38using --ours or --theirs. With -m, changes made to the working tree 39file can be discarded to recreate the original conflicted merge result. 40 41OPTIONS 42------- 43-q:: 44 Quiet, suppress feedback messages. 45 46-f:: 47 When switching branches, proceed even if the index or the 48 working tree differs from HEAD. This is used to throw away 49 local changes. 50+ 51When checking out paths from the index, do not fail upon unmerged 52entries; instead, unmerged entries are ignored. 53 54--ours:: 55--theirs:: 56 When checking out paths from the index, check out stage #2 57 ('ours') or #3 ('theirs') for unmerged paths. 58 59-b:: 60 Create a new branch named <new_branch> and start it at 61 <branch>. The new branch name must pass all checks defined 62 by linkgit:git-check-ref-format[1]. Some of these checks 63 may restrict the characters allowed in a branch name. 64 65-t:: 66--track:: 67 When creating a new branch, set up configuration so that 'git-pull' 68 will automatically retrieve data from the start point, which must be 69 a branch. Use this if you always pull from the same upstream branch 70 into the new branch, and if you don't want to use "git pull 71 <repository> <refspec>" explicitly. This behavior is the default 72 when the start point is a remote branch. Set the 73 branch.autosetupmerge configuration variable to `false` if you want 74 'git-checkout' and 'git-branch' to always behave as if '--no-track' were 75 given. Set it to `always` if you want this behavior when the 76 start-point is either a local or remote branch. 77 78--no-track:: 79 Ignore the branch.autosetupmerge configuration variable. 80 81-l:: 82 Create the new branch's reflog. This activates recording of 83 all changes made to the branch ref, enabling use of date 84 based sha1 expressions such as "<branchname>@\{yesterday}". 85 86-m:: 87 When switching branches, 88 if you have local modifications to one or more files that 89 are different between the current branch and the branch to 90 which you are switching, the command refuses to switch 91 branches in order to preserve your modifications in context. 92 However, with this option, a three-way merge between the current 93 branch, your working tree contents, and the new branch 94 is done, and you will be on the new branch. 95+ 96When a merge conflict happens, the index entries for conflicting 97paths are left unmerged, and you need to resolve the conflicts 98and mark the resolved paths with `git add` (or `git rm` if the merge 99should result in deletion of the path). 100+ 101When checking out paths from the index, this option lets you recreate 102the conflicted merge in the specified paths. 103 104<new_branch>:: 105 Name for the new branch. 106 107<branch>:: 108 Branch to checkout; may be any object ID that resolves to a 109 commit. Defaults to HEAD. 110+ 111When this parameter names a non-branch (but still a valid commit object), 112your HEAD becomes 'detached'. 113 114 115Detached HEAD 116------------- 117 118It is sometimes useful to be able to 'checkout' a commit that is 119not at the tip of one of your branches. The most obvious 120example is to check out the commit at a tagged official release 121point, like this: 122 123------------ 124$ git checkout v2.6.18 125------------ 126 127Earlier versions of git did not allow this and asked you to 128create a temporary branch using `-b` option, but starting from 129version 1.5.0, the above command 'detaches' your HEAD from the 130current branch and directly point at the commit named by the tag 131(`v2.6.18` in the above example). 132 133You can use usual git commands while in this state. You can use 134`git reset --hard $othercommit` to further move around, for 135example. You can make changes and create a new commit on top of 136a detached HEAD. You can even create a merge by using `git 137merge $othercommit`. 138 139The state you are in while your HEAD is detached is not recorded 140by any branch (which is natural --- you are not on any branch). 141What this means is that you can discard your temporary commits 142and merges by switching back to an existing branch (e.g. `git 143checkout master`), and a later `git prune` or `git gc` would 144garbage-collect them. If you did this by mistake, you can ask 145the reflog for HEAD where you were, e.g. 146 147------------ 148$ git log -g -2 HEAD 149------------ 150 151 152EXAMPLES 153-------- 154 155. The following sequence checks out the `master` branch, reverts 156the `Makefile` to two revisions back, deletes hello.c by 157mistake, and gets it back from the index. 158+ 159------------ 160$ git checkout master <1> 161$ git checkout master~2 Makefile <2> 162$ rm -f hello.c 163$ git checkout hello.c <3> 164------------ 165+ 166<1> switch branch 167<2> take out a file out of other commit 168<3> restore hello.c from HEAD of current branch 169+ 170If you have an unfortunate branch that is named `hello.c`, this 171step would be confused as an instruction to switch to that branch. 172You should instead write: 173+ 174------------ 175$ git checkout -- hello.c 176------------ 177 178. After working in a wrong branch, switching to the correct 179branch would be done using: 180+ 181------------ 182$ git checkout mytopic 183------------ 184+ 185However, your "wrong" branch and correct "mytopic" branch may 186differ in files that you have locally modified, in which case, 187the above checkout would fail like this: 188+ 189------------ 190$ git checkout mytopic 191fatal: Entry 'frotz' not uptodate. Cannot merge. 192------------ 193+ 194You can give the `-m` flag to the command, which would try a 195three-way merge: 196+ 197------------ 198$ git checkout -m mytopic 199Auto-merging frotz 200------------ 201+ 202After this three-way merge, the local modifications are _not_ 203registered in your index file, so `git diff` would show you what 204changes you made since the tip of the new branch. 205 206. When a merge conflict happens during switching branches with 207the `-m` option, you would see something like this: 208+ 209------------ 210$ git checkout -m mytopic 211Auto-merging frotz 212merge: warning: conflicts during merge 213ERROR: Merge conflict in frotz 214fatal: merge program failed 215------------ 216+ 217At this point, `git diff` shows the changes cleanly merged as in 218the previous example, as well as the changes in the conflicted 219files. Edit and resolve the conflict and mark it resolved with 220`git add` as usual: 221+ 222------------ 223$ edit frotz 224$ git add frotz 225------------ 226 227 228Author 229------ 230Written by Linus Torvalds <torvalds@osdl.org> 231 232Documentation 233-------------- 234Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 235 236GIT 237--- 238Part of the linkgit:git[1] suite