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 add` (or `git rm` if the merge 65should result in deletion of the path). 66 67<new_branch>:: 68 Name for the new branch. 69 70<branch>:: 71 Branch to checkout; may be any object ID that resolves to a 72 commit. Defaults to HEAD. 73+ 74When this parameter names a non-branch (but still a valid commit object), 75your HEAD becomes 'detached'. 76 77 78Detached HEAD 79------------- 80 81It is sometimes useful to be able to 'checkout' a commit that is 82not at the tip of one of your branches. The most obvious 83example is to check out the commit at a tagged official release 84point, like this: 85 86------------ 87$ git checkout v2.6.18 88------------ 89 90Earlier versions of git did not allow this and asked you to 91create a temporary branch using `-b` option, but starting from 92version 1.5.0, the above command 'detaches' your HEAD from the 93current branch and directly point at the commit named by the tag 94(`v2.6.18` in the above example). 95 96You can use usual git commands while in this state. You can use 97`git-reset --hard $othercommit` to further move around, for 98example. You can make changes and create a new commit on top of 99a detached HEAD. You can even create a merge by using `git 100merge $othercommit`. 101 102The state you are in while your HEAD is detached is not recorded 103by any branch (which is natural --- you are not on any branch). 104What this means is that you can discard your temporary commits 105and merges by switching back to an existing branch (e.g. `git 106checkout master`), and a later `git prune` or `git gc` would 107garbage-collect them. If you did this by mistake, you can ask 108the reflog for HEAD where you were, e.g. 109 110------------ 111$ git log -g -2 HEAD 112------------ 113 114 115EXAMPLES 116-------- 117 118. The following sequence checks out the `master` branch, reverts 119the `Makefile` to two revisions back, deletes hello.c by 120mistake, and gets it back from the index. 121+ 122------------ 123$ git checkout master <1> 124$ git checkout master~2 Makefile <2> 125$ rm -f hello.c 126$ git checkout hello.c <3> 127------------ 128+ 129<1> switch branch 130<2> take out a file out of other commit 131<3> restore hello.c from HEAD of current branch 132+ 133If you have an unfortunate branch that is named `hello.c`, this 134step would be confused as an instruction to switch to that branch. 135You should instead write: 136+ 137------------ 138$ git checkout -- hello.c 139------------ 140 141. After working in a wrong branch, switching to the correct 142branch would be done using: 143+ 144------------ 145$ git checkout mytopic 146------------ 147+ 148However, your "wrong" branch and correct "mytopic" branch may 149differ in files that you have locally modified, in which case, 150the above checkout would fail like this: 151+ 152------------ 153$ git checkout mytopic 154fatal: Entry 'frotz' not uptodate. Cannot merge. 155------------ 156+ 157You can give the `-m` flag to the command, which would try a 158three-way merge: 159+ 160------------ 161$ git checkout -m mytopic 162Auto-merging frotz 163------------ 164+ 165After this three-way merge, the local modifications are _not_ 166registered in your index file, so `git diff` would show you what 167changes you made since the tip of the new branch. 168 169. When a merge conflict happens during switching branches with 170the `-m` option, you would see something like this: 171+ 172------------ 173$ git checkout -m mytopic 174Auto-merging frotz 175merge: warning: conflicts during merge 176ERROR: Merge conflict in frotz 177fatal: merge program failed 178------------ 179+ 180At this point, `git diff` shows the changes cleanly merged as in 181the previous example, as well as the changes in the conflicted 182files. Edit and resolve the conflict and mark it resolved with 183`git add` as usual: 184+ 185------------ 186$ edit frotz 187$ git add frotz 188------------ 189 190 191Author 192------ 193Written by Linus Torvalds <torvalds@osdl.org> 194 195Documentation 196-------------- 197Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 198 199GIT 200--- 201Part of the gitlink:git[7] suite 202