Documentation/checkout: clarify description
[git/git.git] / Documentation / git-checkout.txt
CommitLineData
215a7ad1
JH
1git-checkout(1)
2===============
7fc9d69f
JH
3
4NAME
5----
76ce9462 6git-checkout - Checkout a branch or paths to the working tree
7fc9d69f
JH
7
8SYNOPSIS
9--------
71bb1033 10[verse]
76cfadfc
JK
11'git checkout' [-q] [-f] [-m] [<branch>]
12'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
eac5a401 13'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
4f353658 14'git checkout' --patch [<tree-ish>] [--] [<paths>...]
7fc9d69f
JH
15
16DESCRIPTION
17-----------
c5b41519
JN
18Retrieves files from the index or specified tree and writes them
19to the working tree.
4aaa7027 20
c5b41519 21'git checkout' [-b <new branch>] [<branch>]::
4aaa7027 22
c5b41519
JN
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+
76cfadfc
JK
27If `-b` is given, a new branch is created and checked out, as if
28linkgit:git-branch[1] were called; in this case you can
29use the --track or --no-track options, which will be passed to `git
30branch`. As a convenience, --track without `-b` implies branch
31creation; see the description of --track below.
bb0ceb62 32
c5b41519 33'git checkout' [--patch] [<tree-ish>] [--] [<pathspec>...]::
4aaa7027 34
c5b41519
JN
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+
db941099
JH
44The index may contain unmerged entries after a failed merge. By
45default, if you try to check out such an entry from the index, the
46checkout operation will fail and nothing will be checked out.
38901a48
JH
47Using -f will ignore these unmerged entries. The contents from a
48specific side of the merge can be checked out of the index by
0cf8581e
JH
49using --ours or --theirs. With -m, changes made to the working tree
50file can be discarded to recreate the original conflicted merge result.
7fc9d69f
JH
51
52OPTIONS
53-------
6124aee5 54-q::
f7aec129 55--quiet::
2be7fcb4 56 Quiet, suppress feedback messages.
6124aee5 57
0270f7c5 58-f::
f7aec129 59--force::
db941099
JH
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+
64When checking out paths from the index, do not fail upon unmerged
65entries; instead, unmerged entries are ignored.
0270f7c5 66
38901a48
JH
67--ours::
68--theirs::
69 When checking out paths from the index, check out stage #2
70 ('ours') or #3 ('theirs') for unmerged paths.
0270f7c5
LAS
71
72-b::
2b1f4247 73 Create a new branch named <new_branch> and start it at
76cfadfc 74 <start_point>; see linkgit:git-branch[1] for details.
7fc9d69f 75
3240240f
SB
76-t::
77--track::
26d22dc6
JK
78 When creating a new branch, set up "upstream" configuration. See
79 "--track" in linkgit:git-branch[1] for details.
bb0ceb62 80+
c7cb12b8
MG
81If no '-b' option is given, the name of the new branch will be
82derived from the remote branch. If "remotes/" or "refs/remotes/"
83is prefixed it is stripped away, and then the part up to the
9188ed89
AR
84next slash (which would be the nickname of the remote) is removed.
85This would tell us to use "hack" as the local branch when branching
86off of "origin/hack" (or "remotes/origin/hack", or even
87"refs/remotes/origin/hack"). If the given name has no slash, or the above
88guessing results in an empty name, the guessing is aborted. You can
971e8352 89explicitly give a name with '-b' in such a case.
0746d19a
PB
90
91--no-track::
167d7445 92 Do not set up "upstream" configuration, even if the
70e96647 93 branch.autosetupmerge configuration variable is true.
0746d19a 94
969d326d 95-l::
26d22dc6
JK
96 Create the new branch's reflog; see linkgit:git-branch[1] for
97 details.
969d326d 98
1be0659e 99-m::
eac5a401 100--merge::
0cf8581e
JH
101 When switching branches,
102 if you have local modifications to one or more files that
71bb1033
JL
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
1be0659e
JH
107 branch, your working tree contents, and the new branch
108 is done, and you will be on the new branch.
109+
110When a merge conflict happens, the index entries for conflicting
111paths are left unmerged, and you need to resolve the conflicts
d7f078b8
SP
112and mark the resolved paths with `git add` (or `git rm` if the merge
113should result in deletion of the path).
0cf8581e
JH
114+
115When checking out paths from the index, this option lets you recreate
116the conflicted merge in the specified paths.
1be0659e 117
eac5a401
JH
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).
1be0659e 124
4f353658
TR
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+
132This means that you can use `git checkout -p` to selectively discard
133edits from your current working tree.
134
0270f7c5 135<branch>::
0808723b
JK
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).
696acf45 141+
dcb11263 142As a special case, the `"@\{-N\}"` syntax for the N-th last branch
696acf45 143checks out the branch (instead of detaching). You may also specify
dcb11263 144`-` which is synonymous with `"@\{-1\}"`.
5e1a2e8c 145
76cfadfc
JK
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
5e1a2e8c
JH
158
159Detached HEAD
160-------------
161
162It is sometimes useful to be able to 'checkout' a commit that is
163not at the tip of one of your branches. The most obvious
164example is to check out the commit at a tagged official release
165point, like this:
166
167------------
168$ git checkout v2.6.18
169------------
170
171Earlier versions of git did not allow this and asked you to
c7cb12b8 172create a temporary branch using the `-b` option, but starting from
5e1a2e8c 173version 1.5.0, the above command 'detaches' your HEAD from the
c7cb12b8
MG
174current branch and directly points at the commit named by the tag
175(`v2.6.18` in the example above).
5e1a2e8c 176
c7cb12b8 177You can use all git commands while in this state. You can use
b1889c36 178`git reset --hard $othercommit` to further move around, for
5e1a2e8c
JH
179example. You can make changes and create a new commit on top of
180a detached HEAD. You can even create a merge by using `git
181merge $othercommit`.
182
183The state you are in while your HEAD is detached is not recorded
184by any branch (which is natural --- you are not on any branch).
185What this means is that you can discard your temporary commits
186and merges by switching back to an existing branch (e.g. `git
187checkout master`), and a later `git prune` or `git gc` would
cec8d146
JH
188garbage-collect them. If you did this by mistake, you can ask
189the reflog for HEAD where you were, e.g.
190
191------------
192$ git log -g -2 HEAD
193------------
7fc9d69f 194
4aaa7027 195
1be0659e
JH
196EXAMPLES
197--------
4aaa7027 198
1be0659e 199. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
200the `Makefile` to two revisions back, deletes hello.c by
201mistake, and gets it back from the index.
1be0659e 202+
4aaa7027 203------------
48aeecdc
SE
204$ git checkout master <1>
205$ git checkout master~2 Makefile <2>
4aaa7027 206$ rm -f hello.c
48aeecdc
SE
207$ git checkout hello.c <3>
208------------
209+
1e2ccd3a 210<1> switch branch
c7cb12b8 211<2> take a file out of another commit
ce8936c3 212<3> restore hello.c from the index
1be0659e 213+
48aeecdc
SE
214If you have an unfortunate branch that is named `hello.c`, this
215step would be confused as an instruction to switch to that branch.
216You should instead write:
1be0659e 217+
4aaa7027
JH
218------------
219$ git checkout -- hello.c
220------------
221
c7cb12b8 222. After working in the wrong branch, switching to the correct
71bb1033 223branch would be done using:
1be0659e
JH
224+
225------------
226$ git checkout mytopic
227------------
228+
229However, your "wrong" branch and correct "mytopic" branch may
c7cb12b8 230differ in files that you have modified locally, in which case
1be0659e
JH
231the above checkout would fail like this:
232+
233------------
234$ git checkout mytopic
235fatal: Entry 'frotz' not uptodate. Cannot merge.
236------------
237+
238You can give the `-m` flag to the command, which would try a
239three-way merge:
240+
241------------
242$ git checkout -m mytopic
243Auto-merging frotz
244------------
245+
246After this three-way merge, the local modifications are _not_
247registered in your index file, so `git diff` would show you what
248changes you made since the tip of the new branch.
249
250. When a merge conflict happens during switching branches with
251the `-m` option, you would see something like this:
252+
253------------
254$ git checkout -m mytopic
255Auto-merging frotz
1be0659e
JH
256ERROR: Merge conflict in frotz
257fatal: merge program failed
258------------
259+
260At this point, `git diff` shows the changes cleanly merged as in
261the previous example, as well as the changes in the conflicted
262files. Edit and resolve the conflict and mark it resolved with
d7f078b8 263`git add` as usual:
1be0659e
JH
264+
265------------
266$ edit frotz
d7f078b8 267$ git add frotz
1be0659e
JH
268------------
269
4aaa7027 270
7fc9d69f
JH
271Author
272------
273Written by Linus Torvalds <torvalds@osdl.org>
274
275Documentation
276--------------
277Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
278
279GIT
280---
9e1f0a85 281Part of the linkgit:git[1] suite