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