1git-checkout(1) 2=============== 3 4NAME 5---- 6git-checkout - Checkout and switch to a branch 7 8SYNOPSIS 9-------- 10[verse] 11'git-checkout' [-q] [-f] [-b <new_branch> [-l]] [-m] [<branch>] 12'git-checkout' [<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. 22 23When <paths> are given, this command does *not* switch 24branches. It updates the named paths in the working tree from 25the index file (i.e. it runs `git-checkout-index -f -u`), or a 26named commit. In 27this case, `-f` and `-b` options are 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 33 34OPTIONS 35------- 36-q:: 37 Quiet, supress feedback messages. 38 39-f:: 40 Force a re-read of everything. 41 42-b:: 43 Create a new branch named <new_branch> and start it at 44 <branch>. The new branch name must pass all checks defined 45 by gitlink:git-check-ref-format[1]. Some of these checks 46 may restrict the characters allowed in a branch name. 47 48-l:: 49 Create the new branch's ref log. This activates recording of 50 all changes to made the branch ref, enabling use of date 51 based sha1 expressions such as "<branchname>@{yesterday}". 52 53-m:: 54 If you have local modifications to one or more files that 55 are different between the current branch and the branch to 56 which you are switching, the command refuses to switch 57 branches in order to preserve your modifications in context. 58 However, with this option, a three-way merge between the current 59 branch, your working tree contents, and the new branch 60 is done, and you will be on the new branch. 61+ 62When a merge conflict happens, the index entries for conflicting 63paths are left unmerged, and you need to resolve the conflicts 64and mark the resolved paths with `git update-index`. 65 66<new_branch>:: 67 Name for the new branch. 68 69<branch>:: 70 Branch to checkout; may be any object ID that resolves to a 71 commit. Defaults to HEAD. 72+ 73When this parameter names a non-branch (but still a valid commit object), 74your HEAD becomes 'detached'. 75 76 77Detached HEAD 78------------- 79 80It is sometimes useful to be able to 'checkout' a commit that is 81not at the tip of one of your branches. The most obvious 82example is to check out the commit at a tagged official release 83point, like this: 84 85------------ 86$ git checkout v2.6.18 87------------ 88 89Earlier versions of git did not allow this and asked you to 90create a temporary branch using `-b` option, but starting from 91version 1.5.0, the above command 'detaches' your HEAD from the 92current branch and directly point at the commit named by the tag 93(`v2.6.18` in the above example). 94 95You can use usual git commands while in this state. You can use 96`git-reset --hard $othercommit` to further move around, for 97example. You can make changes and create a new commit on top of 98a detached HEAD. You can even create a merge by using `git 99merge $othercommit`. 100 101The state you are in while your HEAD is detached is not recorded 102by any branch (which is natural --- you are not on any branch). 103What this means is that you can discard your temporary commits 104and merges by switching back to an existing branch (e.g. `git 105checkout master`), and a later `git prune` or `git gc` would 106garbage-collect them. If you did this by mistake, you can ask 107the reflog for HEAD where you were, e.g. 108 109------------ 110$ git log -g -2 HEAD 111------------ 112 113 114EXAMPLES 115-------- 116 117. The following sequence checks out the `master` branch, reverts 118the `Makefile` to two revisions back, deletes hello.c by 119mistake, and gets it back from the index. 120+ 121------------ 122$ git checkout master <1> 123$ git checkout master~2 Makefile <2> 124$ rm -f hello.c 125$ git checkout hello.c <3> 126------------ 127+ 128<1> switch branch 129<2> take out a file out of other commit 130<3> restore hello.c from HEAD of current branch 131+ 132If you have an unfortunate branch that is named `hello.c`, this 133step would be confused as an instruction to switch to that branch. 134You should instead write: 135+ 136------------ 137$ git checkout -- hello.c 138------------ 139 140. After working in a wrong branch, switching to the correct 141branch would be done using: 142+ 143------------ 144$ git checkout mytopic 145------------ 146+ 147However, your "wrong" branch and correct "mytopic" branch may 148differ in files that you have locally modified, in which case, 149the above checkout would fail like this: 150+ 151------------ 152$ git checkout mytopic 153fatal: Entry 'frotz' not uptodate. Cannot merge. 154------------ 155+ 156You can give the `-m` flag to the command, which would try a 157three-way merge: 158+ 159------------ 160$ git checkout -m mytopic 161Auto-merging frotz 162------------ 163+ 164After this three-way merge, the local modifications are _not_ 165registered in your index file, so `git diff` would show you what 166changes you made since the tip of the new branch. 167 168. When a merge conflict happens during switching branches with 169the `-m` option, you would see something like this: 170+ 171------------ 172$ git checkout -m mytopic 173Auto-merging frotz 174merge: warning: conflicts during merge 175ERROR: Merge conflict in frotz 176fatal: merge program failed 177------------ 178+ 179At this point, `git diff` shows the changes cleanly merged as in 180the previous example, as well as the changes in the conflicted 181files. Edit and resolve the conflict and mark it resolved with 182`git update-index` as usual: 183+ 184------------ 185$ edit frotz 186$ git update-index frotz 187------------ 188 189 190Author 191------ 192Written by Linus Torvalds <torvalds@osdl.org> 193 194Documentation 195-------------- 196Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 197 198GIT 199--- 200Part of the gitlink:git[7] suite 201