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