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