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] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
  12 'git checkout' [<tree-ish>] [--] <paths>...
  13
  14 DESCRIPTION
  15 -----------
  16
  17 When <paths> are not given, this command switches branches by
  18 updating the index and working tree to reflect the specified
  19 branch, <branch>, and updating HEAD to be <branch> or, if
  20 specified, <new_branch>.  Using -b will cause <new_branch> to
  21 be created; in this case you can use the --track or --no-track
  22 options, which will be passed to `git branch`.
  23
  24 As a convenience, --track will default to create a branch whose
  25 name is constructed from the specified branch name by stripping
  26 the first namespace level.
  27
  28 When <paths> are given, this command does *not* switch
  29 branches.  It updates the named paths in the working tree from
  30 the index file (i.e. it runs `git checkout-index -f -u`), or
  31 from a named commit.  In
  32 this case, the `-f` and `-b` options are meaningless and giving
  33 either of them results in an error.  <tree-ish> argument can be
  34 used to specify a specific tree-ish (i.e. commit, tag or tree)
  35 to update the index for the given paths before updating the
  36 working tree.
  37
  38
  39 OPTIONS
  40 -------
  41 -q::
  42         Quiet, suppress feedback messages.
  43
  44 -f::
  45         Proceed even if the index or the working tree differs
  46         from HEAD.  This is used to throw away local changes.
  47
  48 -b::
  49         Create a new branch named <new_branch> and start it at
  50         <branch>.  The new branch name must pass all checks defined
  51         by linkgit:git-check-ref-format[1].  Some of these checks
  52         may restrict the characters allowed in a branch name.
  53
  54 -t::
  55 --track::
  56         When creating a new branch, set up configuration so that 'git-pull'
  57         will automatically retrieve data from the start point, which must be
  58         a branch. Use this if you always pull from the same upstream branch
  59         into the new branch, and if you don't want to use "git pull
  60         <repository> <refspec>" explicitly. This behavior is the default
  61         when the start point is a remote branch. Set the
  62         branch.autosetupmerge configuration variable to `false` if you want
  63         'git-checkout' and 'git-branch' to always behave as if '--no-track' were
  64         given. Set it to `always` if you want this behavior when the
  65         start-point is either a local or remote branch.
  66 +
  67 If no '-b' option was given, the name of the new branch will be
  68 derived from the remote branch, by attempting to guess the name
  69 of the branch on remote system.  If "remotes/" or "refs/remotes/"
  70 are prefixed, it is stripped away, and then the part up to the
  71 next slash (which would be the nickname of the remote) is removed.
  72 This would tell us to use "hack" as the local branch when branching
  73 off of "origin/hack" (or "remotes/origin/hack", or even
  74 "refs/remotes/origin/hack").  If the given name has no slash, or the above
  75 guessing results in an empty name, the guessing is aborted.  You can
  76 exlicitly give a name with '-b' in such a case.
  77
  78 --no-track::
  79         Ignore the branch.autosetupmerge configuration variable.
  80
  81 -l::
  82         Create the new branch's reflog.  This activates recording of
  83         all changes made to the branch ref, enabling use of date
  84         based sha1 expressions such as "<branchname>@\{yesterday}".
  85
  86 -m::
  87         If you have local modifications to one or more files that
  88         are different between the current branch and the branch to
  89         which you are switching, the command refuses to switch
  90         branches in order to preserve your modifications in context.
  91         However, with this option, a three-way merge between the current
  92         branch, your working tree contents, and the new branch
  93         is done, and you will be on the new branch.
  94 +
  95 When a merge conflict happens, the index entries for conflicting
  96 paths are left unmerged, and you need to resolve the conflicts
  97 and mark the resolved paths with `git add` (or `git rm` if the merge
  98 should result in deletion of the path).
  99
 100 <new_branch>::
 101         Name for the new branch.
 102
 103 <branch>::
 104         Branch to checkout; may be any object ID that resolves to a
 105         commit.  Defaults to HEAD.
 106 +
 107 When this parameter names a non-branch (but still a valid commit object),
 108 your HEAD becomes 'detached'.
 109
 110
 111 Detached HEAD
 112 -------------
 113
 114 It is sometimes useful to be able to 'checkout' a commit that is
 115 not at the tip of one of your branches.  The most obvious
 116 example is to check out the commit at a tagged official release
 117 point, like this:
 118
 119 ------------
 120 $ git checkout v2.6.18
 121 ------------
 122
 123 Earlier versions of git did not allow this and asked you to
 124 create a temporary branch using `-b` option, but starting from
 125 version 1.5.0, the above command 'detaches' your HEAD from the
 126 current branch and directly point at the commit named by the tag
 127 (`v2.6.18` in the above example).
 128
 129 You can use usual git commands while in this state.  You can use
 130 `git reset --hard $othercommit` to further move around, for
 131 example.  You can make changes and create a new commit on top of
 132 a detached HEAD.  You can even create a merge by using `git
 133 merge $othercommit`.
 134
 135 The state you are in while your HEAD is detached is not recorded
 136 by any branch (which is natural --- you are not on any branch).
 137 What this means is that you can discard your temporary commits
 138 and merges by switching back to an existing branch (e.g. `git
 139 checkout master`), and a later `git prune` or `git gc` would
 140 garbage-collect them.  If you did this by mistake, you can ask
 141 the reflog for HEAD where you were, e.g.
 142
 143 ------------
 144 $ git log -g -2 HEAD
 145 ------------
 146
 147
 148 EXAMPLES
 149 --------
 150
 151 . The following sequence checks out the `master` branch, reverts
 152 the `Makefile` to two revisions back, deletes hello.c by
 153 mistake, and gets it back from the index.
 154 +
 155 ------------
 156 $ git checkout master             <1>
 157 $ git checkout master~2 Makefile  <2>
 158 $ rm -f hello.c
 159 $ git checkout hello.c            <3>
 160 ------------
 161 +
 162 <1> switch branch
 163 <2> take out a file out of other commit
 164 <3> restore hello.c from HEAD of current branch
 165 +
 166 If you have an unfortunate branch that is named `hello.c`, this
 167 step would be confused as an instruction to switch to that branch.
 168 You should instead write:
 169 +
 170 ------------
 171 $ git checkout -- hello.c
 172 ------------
 173
 174 . After working in a wrong branch, switching to the correct
 175 branch would be done using:
 176 +
 177 ------------
 178 $ git checkout mytopic
 179 ------------
 180 +
 181 However, your "wrong" branch and correct "mytopic" branch may
 182 differ in files that you have locally modified, in which case,
 183 the above checkout would fail like this:
 184 +
 185 ------------
 186 $ git checkout mytopic
 187 fatal: Entry 'frotz' not uptodate. Cannot merge.
 188 ------------
 189 +
 190 You can give the `-m` flag to the command, which would try a
 191 three-way merge:
 192 +
 193 ------------
 194 $ git checkout -m mytopic
 195 Auto-merging frotz
 196 ------------
 197 +
 198 After this three-way merge, the local modifications are _not_
 199 registered in your index file, so `git diff` would show you what
 200 changes you made since the tip of the new branch.
 201
 202 . When a merge conflict happens during switching branches with
 203 the `-m` option, you would see something like this:
 204 +
 205 ------------
 206 $ git checkout -m mytopic
 207 Auto-merging frotz
 208 merge: warning: conflicts during merge
 209 ERROR: Merge conflict in frotz
 210 fatal: merge program failed
 211 ------------
 212 +
 213 At this point, `git diff` shows the changes cleanly merged as in
 214 the previous example, as well as the changes in the conflicted
 215 files.  Edit and resolve the conflict and mark it resolved with
 216 `git add` as usual:
 217 +
 218 ------------
 219 $ edit frotz
 220 $ git add frotz
 221 ------------
 222
 223
 224 Author
 225 ------
 226 Written by Linus Torvalds <torvalds@osdl.org>
 227
 228 Documentation
 229 --------------
 230 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 231
 232 GIT
 233 ---
 234 Part of the linkgit:git[1] suite