Documentation/git-checkout.txt

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