1GIT-CHECKOUT(1)                   Git Manual                   GIT-CHECKOUT(1)
2
3
4

NAME

6       git-checkout - Switch branches or restore working tree files
7

SYNOPSIS

9       git checkout [-q] [-f] [-m] [<branch>]
10       git checkout [-q] [-f] [-m] --detach [<branch>]
11       git checkout [-q] [-f] [-m] [--detach] <commit>
12       git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
13       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...
14       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
15       git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
16

DESCRIPTION

18       Updates files in the working tree to match the version in the index or
19       the specified tree. If no pathspec was given, git checkout will also
20       update HEAD to set the specified branch as the current branch.
21
22       git checkout [<branch>]
23           To prepare for working on <branch>, switch to it by updating the
24           index and the files in the working tree, and by pointing HEAD at
25           the branch. Local modifications to the files in the working tree
26           are kept, so that they can be committed to the <branch>.
27
28           If <branch> is not found but there does exist a tracking branch in
29           exactly one remote (call it <remote>) with a matching name and
30           --no-guess is not specified, treat as equivalent to
31
32               $ git checkout -b <branch> --track <remote>/<branch>
33
34           You could omit <branch>, in which case the command degenerates to
35           "check out the current branch", which is a glorified no-op with
36           rather expensive side-effects to show only the tracking
37           information, if exists, for the current branch.
38
39       git checkout -b|-B <new-branch> [<start-point>]
40           Specifying -b causes a new branch to be created as if git-branch(1)
41           were called and then checked out. In this case you can use the
42           --track or --no-track options, which will be passed to git branch.
43           As a convenience, --track without -b implies branch creation; see
44           the description of --track below.
45
46           If -B is given, <new-branch> is created if it doesn’t exist;
47           otherwise, it is reset. This is the transactional equivalent of
48
49               $ git branch -f <branch> [<start-point>]
50               $ git checkout <branch>
51
52           that is to say, the branch is not reset/created unless "git
53           checkout" is successful.
54
55       git checkout --detach [<branch>], git checkout [--detach] <commit>
56           Prepare to work on top of <commit>, by detaching HEAD at it (see
57           "DETACHED HEAD" section), and updating the index and the files in
58           the working tree. Local modifications to the files in the working
59           tree are kept, so that the resulting working tree will be the state
60           recorded in the commit plus the local modifications.
61
62           When the <commit> argument is a branch name, the --detach option
63           can be used to detach HEAD at the tip of the branch (git checkout
64           <branch> would check out that branch without detaching HEAD).
65
66           Omitting <branch> detaches HEAD at the tip of the current branch.
67
68       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>]
69       [--] <pathspec>..., git checkout
70       [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>]
71       --pathspec-from-file=<file> [--pathspec-file-nul]
72           Overwrite the contents of the files that match the pathspec. When
73           the <tree-ish> (most often a commit) is not given, overwrite
74           working tree with the contents in the index. When the <tree-ish> is
75           given, overwrite both the index and the working tree with the
76           contents at the <tree-ish>.
77
78           The index may contain unmerged entries because of a previous failed
79           merge. By default, if you try to check out such an entry from the
80           index, the checkout operation will fail and nothing will be checked
81           out. Using -f will ignore these unmerged entries. The contents from
82           a specific side of the merge can be checked out of the index by
83           using --ours or --theirs. With -m, changes made to the working tree
84           file can be discarded to re-create the original conflicted merge
85           result.
86
87       git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
88           This is similar to the previous mode, but lets you use the
89           interactive interface to show the "diff" output and choose which
90           hunks to use in the result. See below for the description of
91           --patch option.
92

OPTIONS

94       -q, --quiet
95           Quiet, suppress feedback messages.
96
97       --progress, --no-progress
98           Progress status is reported on the standard error stream by default
99           when it is attached to a terminal, unless --quiet is specified.
100           This flag enables progress reporting even if not attached to a
101           terminal, regardless of --quiet.
102
103       -f, --force
104           When switching branches, proceed even if the index or the working
105           tree differs from HEAD, and even if there are untracked files in
106           the way. This is used to throw away local changes and any untracked
107           files or directories that are in the way.
108
109           When checking out paths from the index, do not fail upon unmerged
110           entries; instead, unmerged entries are ignored.
111
112       --ours, --theirs
113           When checking out paths from the index, check out stage #2 (ours)
114           or #3 (theirs) for unmerged paths.
115
116           Note that during git rebase and git pull --rebase, ours and theirs
117           may appear swapped; --ours gives the version from the branch the
118           changes are rebased onto, while --theirs gives the version from the
119           branch that holds your work that is being rebased.
120
121           This is because rebase is used in a workflow that treats the
122           history at the remote as the shared canonical one, and treats the
123           work done on the branch you are rebasing as the third-party work to
124           be integrated, and you are temporarily assuming the role of the
125           keeper of the canonical history during the rebase. As the keeper of
126           the canonical history, you need to view the history from the remote
127           as ours (i.e. "our shared canonical history"), while what you did
128           on your side branch as theirs (i.e. "one contributor’s work on top
129           of it").
130
131       -b <new-branch>
132           Create a new branch named <new-branch> and start it at
133           <start-point>; see git-branch(1) for details.
134
135       -B <new-branch>
136           Creates the branch <new-branch> and start it at <start-point>; if
137           it already exists, then reset it to <start-point>. This is
138           equivalent to running "git branch" with "-f"; see git-branch(1) for
139           details.
140
141       -t, --track[=(direct|inherit)]
142           When creating a new branch, set up "upstream" configuration. See
143           "--track" in git-branch(1) for details.
144
145           If no -b option is given, the name of the new branch will be
146           derived from the remote-tracking branch, by looking at the local
147           part of the refspec configured for the corresponding remote, and
148           then stripping the initial part up to the "*". This would tell us
149           to use hack as the local branch when branching off of origin/hack
150           (or remotes/origin/hack, or even refs/remotes/origin/hack). If the
151           given name has no slash, or the above guessing results in an empty
152           name, the guessing is aborted. You can explicitly give a name with
153           -b in such a case.
154
155       --no-track
156           Do not set up "upstream" configuration, even if the
157           branch.autoSetupMerge configuration variable is true.
158
159       --guess, --no-guess
160           If <branch> is not found but there does exist a tracking branch in
161           exactly one remote (call it <remote>) with a matching name, treat
162           as equivalent to
163
164               $ git checkout -b <branch> --track <remote>/<branch>
165
166           If the branch exists in multiple remotes and one of them is named
167           by the checkout.defaultRemote configuration variable, we’ll use
168           that one for the purposes of disambiguation, even if the <branch>
169           isn’t unique across all remotes. Set it to e.g.
170           checkout.defaultRemote=origin to always checkout remote branches
171           from there if <branch> is ambiguous but exists on the origin
172           remote. See also checkout.defaultRemote in git-config(1).
173
174           --guess is the default behavior. Use --no-guess to disable it.
175
176           The default behavior can be set via the checkout.guess
177           configuration variable.
178
179       -l
180           Create the new branch’s reflog; see git-branch(1) for details.
181
182       -d, --detach
183           Rather than checking out a branch to work on it, check out a commit
184           for inspection and discardable experiments. This is the default
185           behavior of git checkout <commit> when <commit> is not a branch
186           name. See the "DETACHED HEAD" section below for details.
187
188       --orphan <new-branch>
189           Create a new orphan branch, named <new-branch>, started from
190           <start-point> and switch to it. The first commit made on this new
191           branch will have no parents and it will be the root of a new
192           history totally disconnected from all the other branches and
193           commits.
194
195           The index and the working tree are adjusted as if you had
196           previously run git checkout <start-point>. This allows you to start
197           a new history that records a set of paths similar to <start-point>
198           by easily running git commit -a to make the root commit.
199
200           This can be useful when you want to publish the tree from a commit
201           without exposing its full history. You might want to do this to
202           publish an open source branch of a project whose current tree is
203           "clean", but whose full history contains proprietary or otherwise
204           encumbered bits of code.
205
206           If you want to start a disconnected history that records a set of
207           paths that is totally different from the one of <start-point>, then
208           you should clear the index and the working tree right after
209           creating the orphan branch by running git rm -rf .  from the top
210           level of the working tree. Afterwards you will be ready to prepare
211           your new files, repopulating the working tree, by copying them from
212           elsewhere, extracting a tarball, etc.
213
214       --ignore-skip-worktree-bits
215           In sparse checkout mode, git checkout -- <paths> would update only
216           entries matched by <paths> and sparse patterns in
217           $GIT_DIR/info/sparse-checkout. This option ignores the sparse
218           patterns and adds back any files in <paths>.
219
220       -m, --merge
221           When switching branches, if you have local modifications to one or
222           more files that are different between the current branch and the
223           branch to which you are switching, the command refuses to switch
224           branches in order to preserve your modifications in context.
225           However, with this option, a three-way merge between the current
226           branch, your working tree contents, and the new branch is done, and
227           you will be on the new branch.
228
229           When a merge conflict happens, the index entries for conflicting
230           paths are left unmerged, and you need to resolve the conflicts and
231           mark the resolved paths with git add (or git rm if the merge should
232           result in deletion of the path).
233
234           When checking out paths from the index, this option lets you
235           recreate the conflicted merge in the specified paths.
236
237           When switching branches with --merge, staged changes may be lost.
238
239       --conflict=<style>
240           The same as --merge option above, but changes the way the
241           conflicting hunks are presented, overriding the merge.conflictStyle
242           configuration variable. Possible values are "merge" (default),
243           "diff3", and "zdiff3".
244
245       -p, --patch
246           Interactively select hunks in the difference between the <tree-ish>
247           (or the index, if unspecified) and the working tree. The chosen
248           hunks are then applied in reverse to the working tree (and if a
249           <tree-ish> was specified, the index).
250
251           This means that you can use git checkout -p to selectively discard
252           edits from your current working tree. See the “Interactive Mode”
253           section of git-add(1) to learn how to operate the --patch mode.
254
255           Note that this option uses the no overlay mode by default (see also
256           --overlay), and currently doesn’t support overlay mode.
257
258       --ignore-other-worktrees
259           git checkout refuses when the wanted ref is already checked out by
260           another worktree. This option makes it check the ref out anyway. In
261           other words, the ref can be held by more than one worktree.
262
263       --overwrite-ignore, --no-overwrite-ignore
264           Silently overwrite ignored files when switching branches. This is
265           the default behavior. Use --no-overwrite-ignore to abort the
266           operation when the new branch contains ignored files.
267
268       --recurse-submodules, --no-recurse-submodules
269           Using --recurse-submodules will update the content of all active
270           submodules according to the commit recorded in the superproject. If
271           local modifications in a submodule would be overwritten the
272           checkout will fail unless -f is used. If nothing (or
273           --no-recurse-submodules) is used, submodules working trees will not
274           be updated. Just like git-submodule(1), this will detach HEAD of
275           the submodule.
276
277       --overlay, --no-overlay
278           In the default overlay mode, git checkout never removes files from
279           the index or the working tree. When specifying --no-overlay, files
280           that appear in the index and working tree, but not in <tree-ish>
281           are removed, to make them match <tree-ish> exactly.
282
283       --pathspec-from-file=<file>
284           Pathspec is passed in <file> instead of commandline args. If <file>
285           is exactly - then standard input is used. Pathspec elements are
286           separated by LF or CR/LF. Pathspec elements can be quoted as
287           explained for the configuration variable core.quotePath (see git-
288           config(1)). See also --pathspec-file-nul and global
289           --literal-pathspecs.
290
291       --pathspec-file-nul
292           Only meaningful with --pathspec-from-file. Pathspec elements are
293           separated with NUL character and all other characters are taken
294           literally (including newlines and quotes).
295
296       <branch>
297           Branch to checkout; if it refers to a branch (i.e., a name that,
298           when prepended with "refs/heads/", is a valid ref), then that
299           branch is checked out. Otherwise, if it refers to a valid commit,
300           your HEAD becomes "detached" and you are no longer on any branch
301           (see below for details).
302
303           You can use the @{-N} syntax to refer to the N-th last
304           branch/commit checked out using "git checkout" operation. You may
305           also specify - which is synonymous to @{-1}.
306
307           As a special case, you may use A...B as a shortcut for the merge
308           base of A and B if there is exactly one merge base. You can leave
309           out at most one of A and B, in which case it defaults to HEAD.
310
311       <new-branch>
312           Name for the new branch.
313
314       <start-point>
315           The name of a commit at which to start the new branch; see git-
316           branch(1) for details. Defaults to HEAD.
317
318           As a special case, you may use "A...B" as a shortcut for the merge
319           base of A and B if there is exactly one merge base. You can leave
320           out at most one of A and B, in which case it defaults to HEAD.
321
322       <tree-ish>
323           Tree to checkout from (when paths are given). If not specified, the
324           index will be used.
325
326           As a special case, you may use "A...B" as a shortcut for the merge
327           base of A and B if there is exactly one merge base. You can leave
328           out at most one of A and B, in which case it defaults to HEAD.
329
330       --
331           Do not interpret any more arguments as options.
332
333       <pathspec>...
334           Limits the paths affected by the operation.
335
336           For more details, see the pathspec entry in gitglossary(7).
337

DETACHED HEAD

339       HEAD normally refers to a named branch (e.g. master). Meanwhile, each
340       branch refers to a specific commit. Let’s look at a repo with three
341       commits, one of them tagged, and with branch master checked out:
342
343                      HEAD (refers to branch 'master')
344                       |
345                       v
346           a---b---c  branch 'master' (refers to commit 'c')
347               ^
348               |
349             tag 'v2.0' (refers to commit 'b')
350
351       When a commit is created in this state, the branch is updated to refer
352       to the new commit. Specifically, git commit creates a new commit d,
353       whose parent is commit c, and then updates branch master to refer to
354       new commit d. HEAD still refers to branch master and so indirectly now
355       refers to commit d:
356
357           $ edit; git add; git commit
358
359                          HEAD (refers to branch 'master')
360                           |
361                           v
362           a---b---c---d  branch 'master' (refers to commit 'd')
363               ^
364               |
365             tag 'v2.0' (refers to commit 'b')
366
367       It is sometimes useful to be able to checkout a commit that is not at
368       the tip of any named branch, or even to create a new commit that is not
369       referenced by a named branch. Let’s look at what happens when we
370       checkout commit b (here we show two ways this may be done):
371
372           $ git checkout v2.0  # or
373           $ git checkout master^^
374
375              HEAD (refers to commit 'b')
376               |
377               v
378           a---b---c---d  branch 'master' (refers to commit 'd')
379               ^
380               |
381             tag 'v2.0' (refers to commit 'b')
382
383       Notice that regardless of which checkout command we use, HEAD now
384       refers directly to commit b. This is known as being in detached HEAD
385       state. It means simply that HEAD refers to a specific commit, as
386       opposed to referring to a named branch. Let’s see what happens when we
387       create a commit:
388
389           $ edit; git add; git commit
390
391                HEAD (refers to commit 'e')
392                 |
393                 v
394                 e
395                /
396           a---b---c---d  branch 'master' (refers to commit 'd')
397               ^
398               |
399             tag 'v2.0' (refers to commit 'b')
400
401       There is now a new commit e, but it is referenced only by HEAD. We can
402       of course add yet another commit in this state:
403
404           $ edit; git add; git commit
405
406                    HEAD (refers to commit 'f')
407                     |
408                     v
409                 e---f
410                /
411           a---b---c---d  branch 'master' (refers to commit 'd')
412               ^
413               |
414             tag 'v2.0' (refers to commit 'b')
415
416       In fact, we can perform all the normal Git operations. But, let’s look
417       at what happens when we then checkout master:
418
419           $ git checkout master
420
421                          HEAD (refers to branch 'master')
422                 e---f     |
423                /          v
424           a---b---c---d  branch 'master' (refers to commit 'd')
425               ^
426               |
427             tag 'v2.0' (refers to commit 'b')
428
429       It is important to realize that at this point nothing refers to commit
430       f. Eventually commit f (and by extension commit e) will be deleted by
431       the routine Git garbage collection process, unless we create a
432       reference before that happens. If we have not yet moved away from
433       commit f, any of these will create a reference to it:
434
435           $ git checkout -b foo   (1)
436           $ git branch foo        (2)
437           $ git tag foo           (3)
438
439
440        1. creates a new branch foo, which refers to commit f, and
441           then updates HEAD to refer to branch foo. In other words,
442           we’ll no longer be in detached HEAD state after this
443           command.
444        2. similarly creates a new branch foo, which refers to commit
445           f, but leaves HEAD detached.
446        3. creates a new tag foo, which refers to commit f, leaving
447           HEAD detached.
448
449       If we have moved away from commit f, then we must first recover its
450       object name (typically by using git reflog), and then we can create a
451       reference to it. For example, to see the last two commits to which HEAD
452       referred, we can use either of these commands:
453
454           $ git reflog -2 HEAD # or
455           $ git log -g -2 HEAD
456

ARGUMENT DISAMBIGUATION

458       When there is only one argument given and it is not -- (e.g. git
459       checkout abc), and when the argument is both a valid <tree-ish> (e.g. a
460       branch abc exists) and a valid <pathspec> (e.g. a file or a directory
461       whose name is "abc" exists), Git would usually ask you to disambiguate.
462       Because checking out a branch is so common an operation, however, git
463       checkout abc takes "abc" as a <tree-ish> in such a situation. Use git
464       checkout -- <pathspec> if you want to checkout these paths out of the
465       index.
466

EXAMPLES

468        1. The following sequence checks out the master branch, reverts the
469           Makefile to two revisions back, deletes hello.c by mistake, and
470           gets it back from the index.
471
472               $ git checkout master             (1)
473               $ git checkout master~2 Makefile  (2)
474               $ rm -f hello.c
475               $ git checkout hello.c            (3)
476
477
478            1. switch branch
479            2. take a file out of another commit
480            3. restore hello.c from the index
481           If you want to check out all C source files out of the index, you
482           can say
483
484               $ git checkout -- '*.c'
485
486           Note the quotes around *.c. The file hello.c will also be checked
487           out, even though it is no longer in the working tree, because the
488           file globbing is used to match entries in the index (not in the
489           working tree by the shell).
490
491           If you have an unfortunate branch that is named hello.c, this step
492           would be confused as an instruction to switch to that branch. You
493           should instead write:
494
495               $ git checkout -- hello.c
496
497        2. After working in the wrong branch, switching to the correct branch
498           would be done using:
499
500               $ git checkout mytopic
501
502           However, your "wrong" branch and correct mytopic branch may differ
503           in files that you have modified locally, in which case the above
504           checkout would fail like this:
505
506               $ git checkout mytopic
507               error: You have local changes to 'frotz'; not switching branches.
508
509           You can give the -m flag to the command, which would try a
510           three-way merge:
511
512               $ git checkout -m mytopic
513               Auto-merging frotz
514
515           After this three-way merge, the local modifications are not
516           registered in your index file, so git diff would show you what
517           changes you made since the tip of the new branch.
518
519        3. When a merge conflict happens during switching branches with the -m
520           option, you would see something like this:
521
522               $ git checkout -m mytopic
523               Auto-merging frotz
524               ERROR: Merge conflict in frotz
525               fatal: merge program failed
526
527           At this point, git diff shows the changes cleanly merged as in the
528           previous example, as well as the changes in the conflicted files.
529           Edit and resolve the conflict and mark it resolved with git add as
530           usual:
531
532               $ edit frotz
533               $ git add frotz
534

SEE ALSO

536       git-switch(1), git-restore(1)
537

GIT

539       Part of the git(1) suite
540
541
542
543Git 2.36.1                        2022-05-05                   GIT-CHECKOUT(1)
Impressum