Merge commit 'refs/top-bases/girocco' into girocco
[git/repo.git] / Documentation / git-checkout.txt
blob82e154de4970c1c2cb35335591cfe457e80a89c1
1 git-checkout(1)
2 ===============
4 NAME
5 ----
6 git-checkout - Checkout a branch or paths to the working tree
8 SYNOPSIS
9 --------
10 [verse]
11 'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
12 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
14 DESCRIPTION
15 -----------
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`.
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.
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, or from a named commit.  In
31 this case, the `-b` options is meaningless and giving
32 either of them results in an error.  <tree-ish> argument can be
33 used to specify a specific tree-ish (i.e. commit, tag or tree)
34 to update the index for the given paths before updating the
35 working tree.
37 The index may contain unmerged entries after a failed merge.  By
38 default, if you try to check out such an entry from the index, the
39 checkout operation will fail and nothing will be checked out.
40 Using -f will ignore these unmerged entries.  The contents from a
41 specific side of the merge can be checked out of the index by
42 using --ours or --theirs.  With -m, changes made to the working tree
43 file can be discarded to recreate the original conflicted merge result.
45 OPTIONS
46 -------
47 -q::
48         Quiet, suppress feedback messages.
50 -f::
51         When switching branches, proceed even if the index or the
52         working tree differs from HEAD.  This is used to throw away
53         local changes.
55 When checking out paths from the index, do not fail upon unmerged
56 entries; instead, unmerged entries are ignored.
58 --ours::
59 --theirs::
60         When checking out paths from the index, check out stage #2
61         ('ours') or #3 ('theirs') for unmerged paths.
63 -b::
64         Create a new branch named <new_branch> and start it at
65         <branch>.  The new branch name must pass all checks defined
66         by linkgit:git-check-ref-format[1].  Some of these checks
67         may restrict the characters allowed in a branch name.
69 -t::
70 --track::
71         When creating a new branch, set up configuration so that 'git-pull'
72         will automatically retrieve data from the start point, which must be
73         a branch. Use this if you always pull from the same upstream branch
74         into the new branch, and if you don't want to use "git pull
75         <repository> <refspec>" explicitly. This behavior is the default
76         when the start point is a remote branch. Set the
77         branch.autosetupmerge configuration variable to `false` if you want
78         'git-checkout' and 'git-branch' to always behave as if '--no-track' were
79         given. Set it to `always` if you want this behavior when the
80         start-point is either a local or remote branch.
82 If no '-b' option was given, the name of the new branch will be
83 derived from the remote branch, by attempting to guess the name
84 of the branch on remote system.  If "remotes/" or "refs/remotes/"
85 are prefixed, it is stripped away, and then the part up to the
86 next slash (which would be the nickname of the remote) is removed.
87 This would tell us to use "hack" as the local branch when branching
88 off of "origin/hack" (or "remotes/origin/hack", or even
89 "refs/remotes/origin/hack").  If the given name has no slash, or the above
90 guessing results in an empty name, the guessing is aborted.  You can
91 exlicitly give a name with '-b' in such a case.
93 --no-track::
94         Ignore the branch.autosetupmerge configuration variable.
96 -l::
97         Create the new branch's reflog.  This activates recording of
98         all changes made to the branch ref, enabling use of date
99         based sha1 expressions such as "<branchname>@\{yesterday}".
101 -m::
102 --merge::
103         When switching branches,
104         if you have local modifications to one or more files that
105         are different between the current branch and the branch to
106         which you are switching, the command refuses to switch
107         branches in order to preserve your modifications in context.
108         However, with this option, a three-way merge between the current
109         branch, your working tree contents, and the new branch
110         is done, and you will be on the new branch.
112 When a merge conflict happens, the index entries for conflicting
113 paths are left unmerged, and you need to resolve the conflicts
114 and mark the resolved paths with `git add` (or `git rm` if the merge
115 should result in deletion of the path).
117 When checking out paths from the index, this option lets you recreate
118 the conflicted merge in the specified paths.
120 --conflict=<style>::
121         The same as --merge option above, but changes the way the
122         conflicting hunks are presented, overriding the
123         merge.conflictstyle configuration variable.  Possible values are
124         "merge" (default) and "diff3" (in addition to what is shown by
125         "merge" style, shows the original contents).
127 <new_branch>::
128         Name for the new branch.
130 <branch>::
131         Branch to checkout; may be any object ID that resolves to a
132         commit.  Defaults to HEAD.
134 When this parameter names a non-branch (but still a valid commit object),
135 your HEAD becomes 'detached'.
138 Detached HEAD
139 -------------
141 It is sometimes useful to be able to 'checkout' a commit that is
142 not at the tip of one of your branches.  The most obvious
143 example is to check out the commit at a tagged official release
144 point, like this:
146 ------------
147 $ git checkout v2.6.18
148 ------------
150 Earlier versions of git did not allow this and asked you to
151 create a temporary branch using `-b` option, but starting from
152 version 1.5.0, the above command 'detaches' your HEAD from the
153 current branch and directly point at the commit named by the tag
154 (`v2.6.18` in the above example).
156 You can use usual git commands while in this state.  You can use
157 `git reset --hard $othercommit` to further move around, for
158 example.  You can make changes and create a new commit on top of
159 a detached HEAD.  You can even create a merge by using `git
160 merge $othercommit`.
162 The state you are in while your HEAD is detached is not recorded
163 by any branch (which is natural --- you are not on any branch).
164 What this means is that you can discard your temporary commits
165 and merges by switching back to an existing branch (e.g. `git
166 checkout master`), and a later `git prune` or `git gc` would
167 garbage-collect them.  If you did this by mistake, you can ask
168 the reflog for HEAD where you were, e.g.
170 ------------
171 $ git log -g -2 HEAD
172 ------------
175 EXAMPLES
176 --------
178 . The following sequence checks out the `master` branch, reverts
179 the `Makefile` to two revisions back, deletes hello.c by
180 mistake, and gets it back from the index.
182 ------------
183 $ git checkout master             <1>
184 $ git checkout master~2 Makefile  <2>
185 $ rm -f hello.c
186 $ git checkout hello.c            <3>
187 ------------
189 <1> switch branch
190 <2> take out a file out of other commit
191 <3> restore hello.c from HEAD of current branch
193 If you have an unfortunate branch that is named `hello.c`, this
194 step would be confused as an instruction to switch to that branch.
195 You should instead write:
197 ------------
198 $ git checkout -- hello.c
199 ------------
201 . After working in a wrong branch, switching to the correct
202 branch would be done using:
204 ------------
205 $ git checkout mytopic
206 ------------
208 However, your "wrong" branch and correct "mytopic" branch may
209 differ in files that you have locally modified, in which case,
210 the above checkout would fail like this:
212 ------------
213 $ git checkout mytopic
214 fatal: Entry 'frotz' not uptodate. Cannot merge.
215 ------------
217 You can give the `-m` flag to the command, which would try a
218 three-way merge:
220 ------------
221 $ git checkout -m mytopic
222 Auto-merging frotz
223 ------------
225 After this three-way merge, the local modifications are _not_
226 registered in your index file, so `git diff` would show you what
227 changes you made since the tip of the new branch.
229 . When a merge conflict happens during switching branches with
230 the `-m` option, you would see something like this:
232 ------------
233 $ git checkout -m mytopic
234 Auto-merging frotz
235 merge: warning: conflicts during merge
236 ERROR: Merge conflict in frotz
237 fatal: merge program failed
238 ------------
240 At this point, `git diff` shows the changes cleanly merged as in
241 the previous example, as well as the changes in the conflicted
242 files.  Edit and resolve the conflict and mark it resolved with
243 `git add` as usual:
245 ------------
246 $ edit frotz
247 $ git add frotz
248 ------------
251 Author
252 ------
253 Written by Linus Torvalds <torvalds@osdl.org>
255 Documentation
256 --------------
257 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
261 Part of the linkgit:git[1] suite