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. 107 108The command would refuse to switch back to make sure that you do 109not discard your temporary state by mistake when your detached 110HEAD is not pointed at by any existing ref. If you did want to 111save your state (e.g. "I was interested in the fifth commit from 112the top of 'master' branch", or "I made two commits to fix minor 113bugs while on a detached HEAD" -- and if you do not want to lose 114these facts), you can create a new branch and switch to it with 115`git checkout -b newbranch` so that you can keep building on 116that state, or tag it first so that you can come back to it 117later and switch to the branch you wanted to switch to with `git 118tag that_state; git checkout master`. On the other hand, if you 119did want to discard the temporary state, you can give `-f` 120option (e.g. `git checkout -f master`) to override this 121behaviour. 122 123 124EXAMPLES 125-------- 126 127. The following sequence checks out the `master` branch, reverts 128the `Makefile` to two revisions back, deletes hello.c by 129mistake, and gets it back from the index. 130+ 131------------ 132$ git checkout master <1> 133$ git checkout master~2 Makefile <2> 134$ rm -f hello.c 135$ git checkout hello.c <3> 136------------ 137+ 138<1> switch branch 139<2> take out a file out of other commit 140<3> restore hello.c from HEAD of current branch 141+ 142If you have an unfortunate branch that is named `hello.c`, this 143step would be confused as an instruction to switch to that branch. 144You should instead write: 145+ 146------------ 147$ git checkout -- hello.c 148------------ 149 150. After working in a wrong branch, switching to the correct 151branch would be done using: 152+ 153------------ 154$ git checkout mytopic 155------------ 156+ 157However, your "wrong" branch and correct "mytopic" branch may 158differ in files that you have locally modified, in which case, 159the above checkout would fail like this: 160+ 161------------ 162$ git checkout mytopic 163fatal: Entry 'frotz' not uptodate. Cannot merge. 164------------ 165+ 166You can give the `-m` flag to the command, which would try a 167three-way merge: 168+ 169------------ 170$ git checkout -m mytopic 171Auto-merging frotz 172------------ 173+ 174After this three-way merge, the local modifications are _not_ 175registered in your index file, so `git diff` would show you what 176changes you made since the tip of the new branch. 177 178. When a merge conflict happens during switching branches with 179the `-m` option, you would see something like this: 180+ 181------------ 182$ git checkout -m mytopic 183Auto-merging frotz 184merge: warning: conflicts during merge 185ERROR: Merge conflict in frotz 186fatal: merge program failed 187------------ 188+ 189At this point, `git diff` shows the changes cleanly merged as in 190the previous example, as well as the changes in the conflicted 191files. Edit and resolve the conflict and mark it resolved with 192`git update-index` as usual: 193+ 194------------ 195$ edit frotz 196$ git update-index frotz 197------------ 198 199 200Author 201------ 202Written by Linus Torvalds <torvalds@osdl.org> 203 204Documentation 205-------------- 206Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 207 208GIT 209--- 210Part of the gitlink:git[7] suite 211