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, a name will be made up for you, by stripping
  68 the part up to the first slash of the tracked branch.  For example, if you
  69 called 'git checkout --track origin/next', the branch name will be 'next'.
  70
  71 --no-track::
  72         Ignore the branch.autosetupmerge configuration variable.
  73
  74 -l::
  75         Create the new branch's reflog.  This activates recording of
  76         all changes made to the branch ref, enabling use of date
  77         based sha1 expressions such as "<branchname>@\{yesterday}".
  78
  79 -m::
  80         If you have local modifications to one or more files that
  81         are different between the current branch and the branch to
  82         which you are switching, the command refuses to switch
  83         branches in order to preserve your modifications in context.
  84         However, with this option, a three-way merge between the current
  85         branch, your working tree contents, and the new branch
  86         is done, and you will be on the new branch.
  87 +
  88 When a merge conflict happens, the index entries for conflicting
  89 paths are left unmerged, and you need to resolve the conflicts
  90 and mark the resolved paths with `git add` (or `git rm` if the merge
  91 should result in deletion of the path).
  92
  93 <new_branch>::
  94         Name for the new branch.
  95
  96 <branch>::
  97         Branch to checkout; may be any object ID that resolves to a
  98         commit.  Defaults to HEAD.
  99 +
 100 When this parameter names a non-branch (but still a valid commit object),
 101 your HEAD becomes 'detached'.
 102
 103
 104 Detached HEAD
 105 -------------
 106
 107 It is sometimes useful to be able to 'checkout' a commit that is
 108 not at the tip of one of your branches.  The most obvious
 109 example is to check out the commit at a tagged official release
 110 point, like this:
 111
 112 ------------
 113 $ git checkout v2.6.18
 114 ------------
 115
 116 Earlier versions of git did not allow this and asked you to
 117 create a temporary branch using `-b` option, but starting from
 118 version 1.5.0, the above command 'detaches' your HEAD from the
 119 current branch and directly point at the commit named by the tag
 120 (`v2.6.18` in the above example).
 121
 122 You can use usual git commands while in this state.  You can use
 123 `git reset --hard $othercommit` to further move around, for
 124 example.  You can make changes and create a new commit on top of
 125 a detached HEAD.  You can even create a merge by using `git
 126 merge $othercommit`.
 127
 128 The state you are in while your HEAD is detached is not recorded
 129 by any branch (which is natural --- you are not on any branch).
 130 What this means is that you can discard your temporary commits
 131 and merges by switching back to an existing branch (e.g. `git
 132 checkout master`), and a later `git prune` or `git gc` would
 133 garbage-collect them.  If you did this by mistake, you can ask
 134 the reflog for HEAD where you were, e.g.
 135
 136 ------------
 137 $ git log -g -2 HEAD
 138 ------------
 139
 140
 141 EXAMPLES
 142 --------
 143
 144 . The following sequence checks out the `master` branch, reverts
 145 the `Makefile` to two revisions back, deletes hello.c by
 146 mistake, and gets it back from the index.
 147 +
 148 ------------
 149 $ git checkout master             <1>
 150 $ git checkout master~2 Makefile  <2>
 151 $ rm -f hello.c
 152 $ git checkout hello.c            <3>
 153 ------------
 154 +
 155 <1> switch branch
 156 <2> take out a file out of other commit
 157 <3> restore hello.c from HEAD of current branch
 158 +
 159 If you have an unfortunate branch that is named `hello.c`, this
 160 step would be confused as an instruction to switch to that branch.
 161 You should instead write:
 162 +
 163 ------------
 164 $ git checkout -- hello.c
 165 ------------
 166
 167 . After working in a wrong branch, switching to the correct
 168 branch would be done using:
 169 +
 170 ------------
 171 $ git checkout mytopic
 172 ------------
 173 +
 174 However, your "wrong" branch and correct "mytopic" branch may
 175 differ in files that you have locally modified, in which case,
 176 the above checkout would fail like this:
 177 +
 178 ------------
 179 $ git checkout mytopic
 180 fatal: Entry 'frotz' not uptodate. Cannot merge.
 181 ------------
 182 +
 183 You can give the `-m` flag to the command, which would try a
 184 three-way merge:
 185 +
 186 ------------
 187 $ git checkout -m mytopic
 188 Auto-merging frotz
 189 ------------
 190 +
 191 After this three-way merge, the local modifications are _not_
 192 registered in your index file, so `git diff` would show you what
 193 changes you made since the tip of the new branch.
 194
 195 . When a merge conflict happens during switching branches with
 196 the `-m` option, you would see something like this:
 197 +
 198 ------------
 199 $ git checkout -m mytopic
 200 Auto-merging frotz
 201 merge: warning: conflicts during merge
 202 ERROR: Merge conflict in frotz
 203 fatal: merge program failed
 204 ------------
 205 +
 206 At this point, `git diff` shows the changes cleanly merged as in
 207 the previous example, as well as the changes in the conflicted
 208 files.  Edit and resolve the conflict and mark it resolved with
 209 `git add` as usual:
 210 +
 211 ------------
 212 $ edit frotz
 213 $ git add frotz
 214 ------------
 215
 216
 217 Author
 218 ------
 219 Written by Linus Torvalds <torvalds@osdl.org>
 220
 221 Documentation
 222 --------------
 223 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 224
 225 GIT
 226 ---
 227 Part of the linkgit:git[1] suite