checkout: pass whole struct to parse_branchname_arg instead of individual flags
[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>]
26776c97
JH
12'git checkout' [-q] [-f] [-m] --detach [<branch>]
13'git checkout' [-q] [-f] [-m] [--detach] <commit>
02ac9837 14'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
eac5a401 15'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
a31538e2 16'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]
7fc9d69f
JH
17
18DESCRIPTION
19-----------
b831deda
JN
20Updates files in the working tree to match the version in the index
21or the specified tree. If no paths are given, 'git checkout' will
22also update `HEAD` to set the specified branch as the current
76cfadfc 23branch.
4aaa7027 24
e1cdf633
CR
25'git checkout' <branch>::
26 To prepare for working on <branch>, switch to it by updating
27 the index and the files in the working tree, and by pointing
28 HEAD at the branch. Local modifications to the files in the
29 working tree are kept, so that they can be committed to the
30 <branch>.
31+
00bb4378
CR
32If <branch> is not found but there does exist a tracking branch in
33exactly one remote (call it <remote>) with a matching name, treat as
34equivalent to
35+
36------------
37$ git checkout -b <branch> --track <remote>/<branch>
38------------
39+
e1cdf633
CR
40You could omit <branch>, in which case the command degenerates to
41"check out the current branch", which is a glorified no-op with a
42rather expensive side-effects to show only the tracking information,
43if exists, for the current branch.
44
02ac9837 45'git checkout' -b|-B <new_branch> [<start point>]::
4aaa7027 46
e1cdf633
CR
47 Specifying `-b` causes a new branch to be created as if
48 linkgit:git-branch[1] were called and then checked out. In
49 this case you can use the `--track` or `--no-track` options,
50 which will be passed to 'git branch'. As a convenience,
51 `--track` without `-b` implies branch creation; see the
52 description of `--track` below.
02ac9837
TRC
53+
54If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it
55is reset. This is the transactional equivalent of
56+
57------------
58$ git branch -f <branch> [<start point>]
59$ git checkout <branch>
60------------
61+
62that is to say, the branch is not reset/created unless "git checkout" is
63successful.
bb0ceb62 64
e1cdf633 65'git checkout' --detach [<branch>]::
26776c97 66'git checkout' [--detach] <commit>::
e1cdf633
CR
67
68 Prepare to work on top of <commit>, by detaching HEAD at it
69 (see "DETACHED HEAD" section), and updating the index and the
70 files in the working tree. Local modifications to the files
71 in the working tree are kept, so that the resulting working
72 tree will be the state recorded in the commit plus the local
73 modifications.
74+
26776c97
JH
75When the <commit> argument is a branch name, the `--detach` option can
76be used to detach HEAD at the tip of the branch (`git checkout
77<branch>` would check out that branch without detaching HEAD).
78+
79Omitting <branch> detaches HEAD at the tip of the current branch.
e1cdf633 80
a31538e2 81'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
4aaa7027 82
442cb08f
LT
83 When <paths> or `--patch` are given, 'git checkout' does *not*
84 switch branches. It updates the named paths in the working tree
85 from the index file or from a named <tree-ish> (most often a
86 commit). In this case, the `-b` and `--track` options are
87 meaningless and giving either of them results in an error. The
88 <tree-ish> argument can be used to specify a specific tree-ish
89 (i.e. commit, tag or tree) to update the index for the given
90 paths before updating the working tree.
c5b41519 91+
b831deda
JN
92The index may contain unmerged entries because of a previous failed merge.
93By default, if you try to check out such an entry from the index, the
db941099 94checkout operation will fail and nothing will be checked out.
b831deda 95Using `-f` will ignore these unmerged entries. The contents from a
38901a48 96specific side of the merge can be checked out of the index by
b831deda
JN
97using `--ours` or `--theirs`. With `-m`, changes made to the working tree
98file can be discarded to re-create the original conflicted merge result.
7fc9d69f
JH
99
100OPTIONS
101-------
6124aee5 102-q::
f7aec129 103--quiet::
2be7fcb4 104 Quiet, suppress feedback messages.
6124aee5 105
0270f7c5 106-f::
f7aec129 107--force::
db941099
JH
108 When switching branches, proceed even if the index or the
109 working tree differs from HEAD. This is used to throw away
110 local changes.
111+
112When checking out paths from the index, do not fail upon unmerged
113entries; instead, unmerged entries are ignored.
0270f7c5 114
38901a48
JH
115--ours::
116--theirs::
117 When checking out paths from the index, check out stage #2
118 ('ours') or #3 ('theirs') for unmerged paths.
0270f7c5 119
45aaf031 120-b <new_branch>::
2b1f4247 121 Create a new branch named <new_branch> and start it at
76cfadfc 122 <start_point>; see linkgit:git-branch[1] for details.
7fc9d69f 123
45aaf031 124-B <new_branch>::
02ac9837
TRC
125 Creates the branch <new_branch> and start it at <start_point>;
126 if it already exists, then reset it to <start_point>. This is
127 equivalent to running "git branch" with "-f"; see
128 linkgit:git-branch[1] for details.
129
3240240f
SB
130-t::
131--track::
26d22dc6
JK
132 When creating a new branch, set up "upstream" configuration. See
133 "--track" in linkgit:git-branch[1] for details.
bb0ceb62 134+
c7cb12b8 135If no '-b' option is given, the name of the new branch will be
fa83a33b
JH
136derived from the remote-tracking branch, by looking at the local part of
137the refspec configured for the corresponding remote, and then stripping
138the initial part up to the "*".
9188ed89
AR
139This would tell us to use "hack" as the local branch when branching
140off of "origin/hack" (or "remotes/origin/hack", or even
141"refs/remotes/origin/hack"). If the given name has no slash, or the above
142guessing results in an empty name, the guessing is aborted. You can
971e8352 143explicitly give a name with '-b' in such a case.
0746d19a
PB
144
145--no-track::
167d7445 146 Do not set up "upstream" configuration, even if the
70e96647 147 branch.autosetupmerge configuration variable is true.
0746d19a 148
969d326d 149-l::
26d22dc6
JK
150 Create the new branch's reflog; see linkgit:git-branch[1] for
151 details.
969d326d 152
32669671
JH
153--detach::
154 Rather than checking out a branch to work on it, check out a
155 commit for inspection and discardable experiments.
156 This is the default behavior of "git checkout <commit>" when
157 <commit> is not a branch name. See the "DETACHED HEAD" section
158 below for details.
159
45aaf031 160--orphan <new_branch>::
feb98d13
EM
161 Create a new 'orphan' branch, named <new_branch>, started from
162 <start_point> and switch to it. The first commit made on this
163 new branch will have no parents and it will be the root of a new
164 history totally disconnected from all the other branches and
165 commits.
9db5ebf4 166+
feb98d13
EM
167The index and the working tree are adjusted as if you had previously run
168"git checkout <start_point>". This allows you to start a new history
169that records a set of paths similar to <start_point> by easily running
170"git commit -a" to make the root commit.
9db5ebf4 171+
feb98d13
EM
172This can be useful when you want to publish the tree from a commit
173without exposing its full history. You might want to do this to publish
174an open source branch of a project whose current tree is "clean", but
175whose full history contains proprietary or otherwise encumbered bits of
176code.
177+
178If you want to start a disconnected history that records a set of paths
179that is totally different from the one of <start_point>, then you should
180clear the index and the working tree right after creating the orphan
181branch by running "git rm -rf ." from the top level of the working tree.
182Afterwards you will be ready to prepare your new files, repopulating the
183working tree, by copying them from elsewhere, extracting a tarball, etc.
9db5ebf4 184
08d595dc
NTND
185--ignore-skip-worktree-bits::
186 In sparse checkout mode, `git checkout -- <paths>` would
187 update only entries matched by <paths> and sparse patterns
188 in $GIT_DIR/info/sparse-checkout. This option ignores
189 the sparse patterns and adds back any files in <paths>.
190
1be0659e 191-m::
eac5a401 192--merge::
0cf8581e
JH
193 When switching branches,
194 if you have local modifications to one or more files that
71bb1033
JL
195 are different between the current branch and the branch to
196 which you are switching, the command refuses to switch
197 branches in order to preserve your modifications in context.
198 However, with this option, a three-way merge between the current
1be0659e
JH
199 branch, your working tree contents, and the new branch
200 is done, and you will be on the new branch.
201+
202When a merge conflict happens, the index entries for conflicting
203paths are left unmerged, and you need to resolve the conflicts
d7f078b8
SP
204and mark the resolved paths with `git add` (or `git rm` if the merge
205should result in deletion of the path).
0cf8581e
JH
206+
207When checking out paths from the index, this option lets you recreate
208the conflicted merge in the specified paths.
1be0659e 209
eac5a401
JH
210--conflict=<style>::
211 The same as --merge option above, but changes the way the
212 conflicting hunks are presented, overriding the
213 merge.conflictstyle configuration variable. Possible values are
214 "merge" (default) and "diff3" (in addition to what is shown by
215 "merge" style, shows the original contents).
1be0659e 216
4f353658
TR
217-p::
218--patch::
219 Interactively select hunks in the difference between the
220 <tree-ish> (or the index, if unspecified) and the working
221 tree. The chosen hunks are then applied in reverse to the
222 working tree (and if a <tree-ish> was specified, the index).
223+
224This means that you can use `git checkout -p` to selectively discard
a31538e2 225edits from your current working tree. See the ``Interactive Mode''
6cf378f0 226section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
4f353658 227
529fef20
NTND
228--to=<path>::
229 Check out a branch in a separate working directory at
230 `<path>`. A new working directory is linked to the current
231 repository, sharing everything except working directory
232 specific files such as HEAD, index... See "MULTIPLE WORKING
233 TREES" section for more information.
234
0270f7c5 235<branch>::
0808723b
JK
236 Branch to checkout; if it refers to a branch (i.e., a name that,
237 when prepended with "refs/heads/", is a valid ref), then that
238 branch is checked out. Otherwise, if it refers to a valid
239 commit, your HEAD becomes "detached" and you are no longer on
240 any branch (see below for details).
696acf45 241+
75d6e552
TR
242As a special case, the `"@{-N}"` syntax for the N-th last branch/commit
243checks out branches (instead of detaching). You may also specify
6cf378f0 244`-` which is synonymous with `"@{-1}"`.
873c3472 245+
6cf378f0 246As a further special case, you may use `"A...B"` as a shortcut for the
873c3472
MG
247merge base of `A` and `B` if there is exactly one merge base. You can
248leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
5e1a2e8c 249
76cfadfc
JK
250<new_branch>::
251 Name for the new branch.
252
253<start_point>::
254 The name of a commit at which to start the new branch; see
255 linkgit:git-branch[1] for details. Defaults to HEAD.
256
257<tree-ish>::
258 Tree to checkout from (when paths are given). If not specified,
259 the index will be used.
260
261
5e1a2e8c 262
32669671 263DETACHED HEAD
5e1a2e8c 264-------------
be8ef33c
JS
265HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each
266branch refers to a specific commit. Let's look at a repo with three
267commits, one of them tagged, and with branch 'master' checked out:
5e1a2e8c 268
be8ef33c
JS
269------------
270 HEAD (refers to branch 'master')
271 |
272 v
273a---b---c branch 'master' (refers to commit 'c')
274 ^
275 |
276 tag 'v2.0' (refers to commit 'b')
277------------
278
279When a commit is created in this state, the branch is updated to refer to
280the new commit. Specifically, 'git commit' creates a new commit 'd', whose
281parent is commit 'c', and then updates branch 'master' to refer to new
282commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers
283to commit 'd':
5e1a2e8c
JH
284
285------------
be8ef33c
JS
286$ edit; git add; git commit
287
288 HEAD (refers to branch 'master')
289 |
290 v
291a---b---c---d branch 'master' (refers to commit 'd')
292 ^
293 |
294 tag 'v2.0' (refers to commit 'b')
5e1a2e8c
JH
295------------
296
be8ef33c
JS
297It is sometimes useful to be able to checkout a commit that is not at
298the tip of any named branch, or even to create a new commit that is not
299referenced by a named branch. Let's look at what happens when we
300checkout commit 'b' (here we show two ways this may be done):
cec8d146
JH
301
302------------
be8ef33c
JS
303$ git checkout v2.0 # or
304$ git checkout master^^
305
306 HEAD (refers to commit 'b')
307 |
308 v
309a---b---c---d branch 'master' (refers to commit 'd')
310 ^
311 |
312 tag 'v2.0' (refers to commit 'b')
313------------
5e1a2e8c 314
be8ef33c
JS
315Notice that regardless of which checkout command we use, HEAD now refers
316directly to commit 'b'. This is known as being in detached HEAD state.
317It means simply that HEAD refers to a specific commit, as opposed to
318referring to a named branch. Let's see what happens when we create a commit:
cec8d146 319
cec8d146 320------------
be8ef33c
JS
321$ edit; git add; git commit
322
323 HEAD (refers to commit 'e')
324 |
325 v
326 e
327 /
328a---b---c---d branch 'master' (refers to commit 'd')
329 ^
330 |
331 tag 'v2.0' (refers to commit 'b')
cec8d146 332------------
7fc9d69f 333
be8ef33c
JS
334There is now a new commit 'e', but it is referenced only by HEAD. We can
335of course add yet another commit in this state:
7fc9d69f 336
be8ef33c
JS
337------------
338$ edit; git add; git commit
339
340 HEAD (refers to commit 'f')
341 |
342 v
343 e---f
344 /
345a---b---c---d branch 'master' (refers to commit 'd')
346 ^
347 |
348 tag 'v2.0' (refers to commit 'b')
349------------
350
2de9b711 351In fact, we can perform all the normal Git operations. But, let's look
be8ef33c
JS
352at what happens when we then checkout master:
353
354------------
355$ git checkout master
356
357 HEAD (refers to branch 'master')
358 e---f |
359 / v
360a---b---c---d branch 'master' (refers to commit 'd')
361 ^
362 |
363 tag 'v2.0' (refers to commit 'b')
364------------
365
366It is important to realize that at this point nothing refers to commit
367'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted
2de9b711 368by the routine Git garbage collection process, unless we create a reference
be8ef33c
JS
369before that happens. If we have not yet moved away from commit 'f',
370any of these will create a reference to it:
371
372------------
373$ git checkout -b foo <1>
374$ git branch foo <2>
375$ git tag foo <3>
376------------
377
378<1> creates a new branch 'foo', which refers to commit 'f', and then
379updates HEAD to refer to branch 'foo'. In other words, we'll no longer
380be in detached HEAD state after this command.
381
382<2> similarly creates a new branch 'foo', which refers to commit 'f',
383but leaves HEAD detached.
384
385<3> creates a new tag 'foo', which refers to commit 'f',
386leaving HEAD detached.
387
388If we have moved away from commit 'f', then we must first recover its object
389name (typically by using git reflog), and then we can create a reference to
390it. For example, to see the last two commits to which HEAD referred, we
391can use either of these commands:
392
393------------
394$ git reflog -2 HEAD # or
395$ git log -g -2 HEAD
396------------
4aaa7027 397
529fef20
NTND
398MULTIPLE WORKING TREES
399----------------------
400
401A git repository can support multiple working trees, allowing you to check
402out more than one branch at a time. With `git checkout --to` a new working
403tree is associated with the repository. This new working tree is called a
404"linked working tree" as opposed to the "main working tree" prepared by "git
405init" or "git clone". A repository has one main working tree (if it's not a
406bare repository) and zero or more linked working trees.
407
408Each linked working tree has a private sub-directory in the repository's
409$GIT_DIR/worktrees directory. The private sub-directory's name is usually
410the base name of the linked working tree's path, possibly appended with a
411number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the
412command `git checkout --to /path/other/test-next next` creates the linked
413working tree in `/path/other/test-next` and also creates a
414`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
415if `test-next` is already taken).
416
417Within a linked working tree, $GIT_DIR is set to point to this private
418directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and
419$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR
420(e.g. `/path/main/.git`). These settings are made in a `.git` file located at
421the top directory of the linked working tree.
422
423Path resolution via `git rev-parse --git-path` uses either
424$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the
425linked working tree `git rev-parse --git-path HEAD` returns
426`/path/main/.git/worktrees/test-next/HEAD` (not
427`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git
428rev-parse --git-path refs/heads/master` uses
429$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`,
430since refs are shared across all working trees.
431
432See linkgit:gitrepository-layout[5] for more information. The rule of
433thumb is do not make any assumption about whether a path belongs to
434$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
435inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
436
23af91d1 437When you are done with a linked working tree you can simply delete it.
e3df33bb
NTND
438The working tree's entry in the repository's $GIT_DIR/worktrees
439directory will eventually be removed automatically (see
440`gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run
441`git prune --worktrees` in the main or any linked working tree to
442clean up any stale entries in $GIT_DIR/worktrees.
23af91d1
NTND
443
444If you move a linked working directory to another file system, or
445within a file system that does not support hard links, you need to run
446at least one git command inside the linked working directory
447(e.g. `git status`) in order to update its entry in $GIT_DIR/worktrees
448so that it does not get automatically removed.
449
e3df33bb
NTND
450To prevent a $GIT_DIR/worktrees entry from from being pruned (which
451can be useful in some situations, such as when the
23af91d1
NTND
452entry's working tree is stored on a portable device), add a file named
453'locked' to the entry's directory. The file contains the reason in
454plain text. For example, if a linked working tree's `.git` file points
455to `/path/main/.git/worktrees/test-next` then a file named
456`/path/main/.git/worktrees/test-next/locked` will prevent the
457`test-next` entry from being pruned. See
458linkgit:gitrepository-layout[5] for details.
459
1be0659e
JH
460EXAMPLES
461--------
4aaa7027 462
1be0659e 463. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
464the `Makefile` to two revisions back, deletes hello.c by
465mistake, and gets it back from the index.
1be0659e 466+
4aaa7027 467------------
48aeecdc
SE
468$ git checkout master <1>
469$ git checkout master~2 Makefile <2>
4aaa7027 470$ rm -f hello.c
48aeecdc
SE
471$ git checkout hello.c <3>
472------------
473+
1e2ccd3a 474<1> switch branch
c7cb12b8 475<2> take a file out of another commit
ce8936c3 476<3> restore hello.c from the index
1be0659e 477+
caae319e
JH
478If you want to check out _all_ C source files out of the index,
479you can say
480+
481------------
482$ git checkout -- '*.c'
483------------
484+
485Note the quotes around `*.c`. The file `hello.c` will also be
486checked out, even though it is no longer in the working tree,
487because the file globbing is used to match entries in the index
488(not in the working tree by the shell).
489+
48aeecdc
SE
490If you have an unfortunate branch that is named `hello.c`, this
491step would be confused as an instruction to switch to that branch.
492You should instead write:
1be0659e 493+
4aaa7027
JH
494------------
495$ git checkout -- hello.c
496------------
497
c7cb12b8 498. After working in the wrong branch, switching to the correct
71bb1033 499branch would be done using:
1be0659e
JH
500+
501------------
502$ git checkout mytopic
503------------
504+
505However, your "wrong" branch and correct "mytopic" branch may
c7cb12b8 506differ in files that you have modified locally, in which case
1be0659e
JH
507the above checkout would fail like this:
508+
509------------
510$ git checkout mytopic
142183d0 511error: You have local changes to 'frotz'; not switching branches.
1be0659e
JH
512------------
513+
514You can give the `-m` flag to the command, which would try a
515three-way merge:
516+
517------------
518$ git checkout -m mytopic
519Auto-merging frotz
520------------
521+
522After this three-way merge, the local modifications are _not_
523registered in your index file, so `git diff` would show you what
524changes you made since the tip of the new branch.
525
526. When a merge conflict happens during switching branches with
527the `-m` option, you would see something like this:
528+
529------------
530$ git checkout -m mytopic
531Auto-merging frotz
1be0659e
JH
532ERROR: Merge conflict in frotz
533fatal: merge program failed
534------------
535+
536At this point, `git diff` shows the changes cleanly merged as in
537the previous example, as well as the changes in the conflicted
538files. Edit and resolve the conflict and mark it resolved with
d7f078b8 539`git add` as usual:
1be0659e
JH
540+
541------------
542$ edit frotz
d7f078b8 543$ git add frotz
1be0659e
JH
544------------
545
7fc9d69f
JH
546GIT
547---
9e1f0a85 548Part of the linkgit:git[1] suite