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