Fix sizeof usage in get_permutations
[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>]
32669671 12'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
02ac9837 13'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
eac5a401 14'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
a31538e2 15'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]
7fc9d69f
JH
16
17DESCRIPTION
18-----------
b831deda
JN
19Updates files in the working tree to match the version in the index
20or the specified tree. If no paths are given, 'git checkout' will
21also update `HEAD` to set the specified branch as the current
76cfadfc 22branch.
4aaa7027 23
b831deda 24'git checkout' [<branch>]::
02ac9837 25'git checkout' -b|-B <new_branch> [<start point>]::
32669671 26'git checkout' [--detach] [<commit>]::
4aaa7027 27
b831deda 28 This form switches branches by updating the index, working
32669671 29 tree, and HEAD to reflect the specified branch or commit.
c5b41519 30+
b831deda
JN
31If `-b` is given, a new branch is created as if linkgit:git-branch[1]
32were called and then checked out; in this case you can
33use the `--track` or `--no-track` options, which will be passed to
34'git branch'. As a convenience, `--track` without `-b` implies branch
35creation; see the description of `--track` below.
02ac9837
TRC
36+
37If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it
38is reset. This is the transactional equivalent of
39+
40------------
41$ git branch -f <branch> [<start point>]
42$ git checkout <branch>
43------------
44+
45that is to say, the branch is not reset/created unless "git checkout" is
46successful.
bb0ceb62 47
a31538e2 48'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
4aaa7027 49
442cb08f
LT
50 When <paths> or `--patch` are given, 'git checkout' does *not*
51 switch branches. It updates the named paths in the working tree
52 from the index file or from a named <tree-ish> (most often a
53 commit). In this case, the `-b` and `--track` options are
54 meaningless and giving either of them results in an error. The
55 <tree-ish> argument can be used to specify a specific tree-ish
56 (i.e. commit, tag or tree) to update the index for the given
57 paths before updating the working tree.
c5b41519 58+
b831deda
JN
59The index may contain unmerged entries because of a previous failed merge.
60By default, if you try to check out such an entry from the index, the
db941099 61checkout operation will fail and nothing will be checked out.
b831deda 62Using `-f` will ignore these unmerged entries. The contents from a
38901a48 63specific side of the merge can be checked out of the index by
b831deda
JN
64using `--ours` or `--theirs`. With `-m`, changes made to the working tree
65file can be discarded to re-create the original conflicted merge result.
7fc9d69f
JH
66
67OPTIONS
68-------
6124aee5 69-q::
f7aec129 70--quiet::
2be7fcb4 71 Quiet, suppress feedback messages.
6124aee5 72
0270f7c5 73-f::
f7aec129 74--force::
db941099
JH
75 When switching branches, proceed even if the index or the
76 working tree differs from HEAD. This is used to throw away
77 local changes.
78+
79When checking out paths from the index, do not fail upon unmerged
80entries; instead, unmerged entries are ignored.
0270f7c5 81
38901a48
JH
82--ours::
83--theirs::
84 When checking out paths from the index, check out stage #2
85 ('ours') or #3 ('theirs') for unmerged paths.
0270f7c5 86
45aaf031 87-b <new_branch>::
2b1f4247 88 Create a new branch named <new_branch> and start it at
76cfadfc 89 <start_point>; see linkgit:git-branch[1] for details.
7fc9d69f 90
45aaf031 91-B <new_branch>::
02ac9837
TRC
92 Creates the branch <new_branch> and start it at <start_point>;
93 if it already exists, then reset it to <start_point>. This is
94 equivalent to running "git branch" with "-f"; see
95 linkgit:git-branch[1] for details.
96
3240240f
SB
97-t::
98--track::
26d22dc6
JK
99 When creating a new branch, set up "upstream" configuration. See
100 "--track" in linkgit:git-branch[1] for details.
bb0ceb62 101+
c7cb12b8 102If no '-b' option is given, the name of the new branch will be
29b9a66f 103derived from the remote-tracking branch. If "remotes/" or "refs/remotes/"
c7cb12b8 104is prefixed it is stripped away, and then the part up to the
9188ed89
AR
105next slash (which would be the nickname of the remote) is removed.
106This would tell us to use "hack" as the local branch when branching
107off of "origin/hack" (or "remotes/origin/hack", or even
108"refs/remotes/origin/hack"). If the given name has no slash, or the above
109guessing results in an empty name, the guessing is aborted. You can
971e8352 110explicitly give a name with '-b' in such a case.
0746d19a
PB
111
112--no-track::
167d7445 113 Do not set up "upstream" configuration, even if the
70e96647 114 branch.autosetupmerge configuration variable is true.
0746d19a 115
969d326d 116-l::
26d22dc6
JK
117 Create the new branch's reflog; see linkgit:git-branch[1] for
118 details.
969d326d 119
32669671
JH
120--detach::
121 Rather than checking out a branch to work on it, check out a
122 commit for inspection and discardable experiments.
123 This is the default behavior of "git checkout <commit>" when
124 <commit> is not a branch name. See the "DETACHED HEAD" section
125 below for details.
126
45aaf031 127--orphan <new_branch>::
feb98d13
EM
128 Create a new 'orphan' branch, named <new_branch>, started from
129 <start_point> and switch to it. The first commit made on this
130 new branch will have no parents and it will be the root of a new
131 history totally disconnected from all the other branches and
132 commits.
9db5ebf4 133+
feb98d13
EM
134The index and the working tree are adjusted as if you had previously run
135"git checkout <start_point>". This allows you to start a new history
136that records a set of paths similar to <start_point> by easily running
137"git commit -a" to make the root commit.
9db5ebf4 138+
feb98d13
EM
139This can be useful when you want to publish the tree from a commit
140without exposing its full history. You might want to do this to publish
141an open source branch of a project whose current tree is "clean", but
142whose full history contains proprietary or otherwise encumbered bits of
143code.
144+
145If you want to start a disconnected history that records a set of paths
146that is totally different from the one of <start_point>, then you should
147clear the index and the working tree right after creating the orphan
148branch by running "git rm -rf ." from the top level of the working tree.
149Afterwards you will be ready to prepare your new files, repopulating the
150working tree, by copying them from elsewhere, extracting a tarball, etc.
9db5ebf4 151
1be0659e 152-m::
eac5a401 153--merge::
0cf8581e
JH
154 When switching branches,
155 if you have local modifications to one or more files that
71bb1033
JL
156 are different between the current branch and the branch to
157 which you are switching, the command refuses to switch
158 branches in order to preserve your modifications in context.
159 However, with this option, a three-way merge between the current
1be0659e
JH
160 branch, your working tree contents, and the new branch
161 is done, and you will be on the new branch.
162+
163When a merge conflict happens, the index entries for conflicting
164paths are left unmerged, and you need to resolve the conflicts
d7f078b8
SP
165and mark the resolved paths with `git add` (or `git rm` if the merge
166should result in deletion of the path).
0cf8581e
JH
167+
168When checking out paths from the index, this option lets you recreate
169the conflicted merge in the specified paths.
1be0659e 170
eac5a401
JH
171--conflict=<style>::
172 The same as --merge option above, but changes the way the
173 conflicting hunks are presented, overriding the
174 merge.conflictstyle configuration variable. Possible values are
175 "merge" (default) and "diff3" (in addition to what is shown by
176 "merge" style, shows the original contents).
1be0659e 177
4f353658
TR
178-p::
179--patch::
180 Interactively select hunks in the difference between the
181 <tree-ish> (or the index, if unspecified) and the working
182 tree. The chosen hunks are then applied in reverse to the
183 working tree (and if a <tree-ish> was specified, the index).
184+
185This means that you can use `git checkout -p` to selectively discard
a31538e2 186edits from your current working tree. See the ``Interactive Mode''
6cf378f0 187section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
4f353658 188
0270f7c5 189<branch>::
0808723b
JK
190 Branch to checkout; if it refers to a branch (i.e., a name that,
191 when prepended with "refs/heads/", is a valid ref), then that
192 branch is checked out. Otherwise, if it refers to a valid
193 commit, your HEAD becomes "detached" and you are no longer on
194 any branch (see below for details).
696acf45 195+
6cf378f0 196As a special case, the `"@{-N}"` syntax for the N-th last branch
696acf45 197checks out the branch (instead of detaching). You may also specify
6cf378f0 198`-` which is synonymous with `"@{-1}"`.
873c3472 199+
6cf378f0 200As a further special case, you may use `"A...B"` as a shortcut for the
873c3472
MG
201merge base of `A` and `B` if there is exactly one merge base. You can
202leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
5e1a2e8c 203
76cfadfc
JK
204<new_branch>::
205 Name for the new branch.
206
207<start_point>::
208 The name of a commit at which to start the new branch; see
209 linkgit:git-branch[1] for details. Defaults to HEAD.
210
211<tree-ish>::
212 Tree to checkout from (when paths are given). If not specified,
213 the index will be used.
214
215
5e1a2e8c 216
32669671 217DETACHED HEAD
5e1a2e8c 218-------------
be8ef33c
JS
219HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each
220branch refers to a specific commit. Let's look at a repo with three
221commits, one of them tagged, and with branch 'master' checked out:
5e1a2e8c 222
be8ef33c
JS
223------------
224 HEAD (refers to branch 'master')
225 |
226 v
227a---b---c branch 'master' (refers to commit 'c')
228 ^
229 |
230 tag 'v2.0' (refers to commit 'b')
231------------
232
233When a commit is created in this state, the branch is updated to refer to
234the new commit. Specifically, 'git commit' creates a new commit 'd', whose
235parent is commit 'c', and then updates branch 'master' to refer to new
236commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers
237to commit 'd':
5e1a2e8c
JH
238
239------------
be8ef33c
JS
240$ edit; git add; git commit
241
242 HEAD (refers to branch 'master')
243 |
244 v
245a---b---c---d branch 'master' (refers to commit 'd')
246 ^
247 |
248 tag 'v2.0' (refers to commit 'b')
5e1a2e8c
JH
249------------
250
be8ef33c
JS
251It is sometimes useful to be able to checkout a commit that is not at
252the tip of any named branch, or even to create a new commit that is not
253referenced by a named branch. Let's look at what happens when we
254checkout commit 'b' (here we show two ways this may be done):
cec8d146
JH
255
256------------
be8ef33c
JS
257$ git checkout v2.0 # or
258$ git checkout master^^
259
260 HEAD (refers to commit 'b')
261 |
262 v
263a---b---c---d branch 'master' (refers to commit 'd')
264 ^
265 |
266 tag 'v2.0' (refers to commit 'b')
267------------
5e1a2e8c 268
be8ef33c
JS
269Notice that regardless of which checkout command we use, HEAD now refers
270directly to commit 'b'. This is known as being in detached HEAD state.
271It means simply that HEAD refers to a specific commit, as opposed to
272referring to a named branch. Let's see what happens when we create a commit:
cec8d146 273
cec8d146 274------------
be8ef33c
JS
275$ edit; git add; git commit
276
277 HEAD (refers to commit 'e')
278 |
279 v
280 e
281 /
282a---b---c---d branch 'master' (refers to commit 'd')
283 ^
284 |
285 tag 'v2.0' (refers to commit 'b')
cec8d146 286------------
7fc9d69f 287
be8ef33c
JS
288There is now a new commit 'e', but it is referenced only by HEAD. We can
289of course add yet another commit in this state:
7fc9d69f 290
be8ef33c
JS
291------------
292$ edit; git add; git commit
293
294 HEAD (refers to commit 'f')
295 |
296 v
297 e---f
298 /
299a---b---c---d branch 'master' (refers to commit 'd')
300 ^
301 |
302 tag 'v2.0' (refers to commit 'b')
303------------
304
305In fact, we can perform all the normal git operations. But, let's look
306at what happens when we then checkout master:
307
308------------
309$ git checkout master
310
311 HEAD (refers to branch 'master')
312 e---f |
313 / v
314a---b---c---d branch 'master' (refers to commit 'd')
315 ^
316 |
317 tag 'v2.0' (refers to commit 'b')
318------------
319
320It is important to realize that at this point nothing refers to commit
321'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted
322by the routine git garbage collection process, unless we create a reference
323before that happens. If we have not yet moved away from commit 'f',
324any of these will create a reference to it:
325
326------------
327$ git checkout -b foo <1>
328$ git branch foo <2>
329$ git tag foo <3>
330------------
331
332<1> creates a new branch 'foo', which refers to commit 'f', and then
333updates HEAD to refer to branch 'foo'. In other words, we'll no longer
334be in detached HEAD state after this command.
335
336<2> similarly creates a new branch 'foo', which refers to commit 'f',
337but leaves HEAD detached.
338
339<3> creates a new tag 'foo', which refers to commit 'f',
340leaving HEAD detached.
341
342If we have moved away from commit 'f', then we must first recover its object
343name (typically by using git reflog), and then we can create a reference to
344it. For example, to see the last two commits to which HEAD referred, we
345can use either of these commands:
346
347------------
348$ git reflog -2 HEAD # or
349$ git log -g -2 HEAD
350------------
4aaa7027 351
1be0659e
JH
352EXAMPLES
353--------
4aaa7027 354
1be0659e 355. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
356the `Makefile` to two revisions back, deletes hello.c by
357mistake, and gets it back from the index.
1be0659e 358+
4aaa7027 359------------
48aeecdc
SE
360$ git checkout master <1>
361$ git checkout master~2 Makefile <2>
4aaa7027 362$ rm -f hello.c
48aeecdc
SE
363$ git checkout hello.c <3>
364------------
365+
1e2ccd3a 366<1> switch branch
c7cb12b8 367<2> take a file out of another commit
ce8936c3 368<3> restore hello.c from the index
1be0659e 369+
caae319e
JH
370If you want to check out _all_ C source files out of the index,
371you can say
372+
373------------
374$ git checkout -- '*.c'
375------------
376+
377Note the quotes around `*.c`. The file `hello.c` will also be
378checked out, even though it is no longer in the working tree,
379because the file globbing is used to match entries in the index
380(not in the working tree by the shell).
381+
48aeecdc
SE
382If you have an unfortunate branch that is named `hello.c`, this
383step would be confused as an instruction to switch to that branch.
384You should instead write:
1be0659e 385+
4aaa7027
JH
386------------
387$ git checkout -- hello.c
388------------
389
c7cb12b8 390. After working in the wrong branch, switching to the correct
71bb1033 391branch would be done using:
1be0659e
JH
392+
393------------
394$ git checkout mytopic
395------------
396+
397However, your "wrong" branch and correct "mytopic" branch may
c7cb12b8 398differ in files that you have modified locally, in which case
1be0659e
JH
399the above checkout would fail like this:
400+
401------------
402$ git checkout mytopic
142183d0 403error: You have local changes to 'frotz'; not switching branches.
1be0659e
JH
404------------
405+
406You can give the `-m` flag to the command, which would try a
407three-way merge:
408+
409------------
410$ git checkout -m mytopic
411Auto-merging frotz
412------------
413+
414After this three-way merge, the local modifications are _not_
415registered in your index file, so `git diff` would show you what
416changes you made since the tip of the new branch.
417
418. When a merge conflict happens during switching branches with
419the `-m` option, you would see something like this:
420+
421------------
422$ git checkout -m mytopic
423Auto-merging frotz
1be0659e
JH
424ERROR: Merge conflict in frotz
425fatal: merge program failed
426------------
427+
428At this point, `git diff` shows the changes cleanly merged as in
429the previous example, as well as the changes in the conflicted
430files. Edit and resolve the conflict and mark it resolved with
d7f078b8 431`git add` as usual:
1be0659e
JH
432+
433------------
434$ edit frotz
d7f078b8 435$ git add frotz
1be0659e
JH
436------------
437
7fc9d69f
JH
438GIT
439---
9e1f0a85 440Part of the linkgit:git[1] suite