freshlybakedca.ke
Git fork
Merge branch 'je/doc-checkout'
Doc updates.
* je/doc-checkout:
doc: git-checkout: clarify restoring files section
doc: git-checkout: split up restoring files section
doc: git-checkout: deduplicate --detach explanation
doc: git-checkout: clarify `-b` and `-B`
doc: git-checkout: clarify `git checkout <branch>`
doc: git-checkout: clarify ARGUMENT DISAMBIGUATION
doc: git-checkout: clarify intro sentence
+74
-73
+74
-73
Documentation/git-checkout.adoc
+74
-73
Documentation/git-checkout.adoc
···
12
12
git checkout [-q] [-f] [-m] --detach [<branch>]
13
13
git checkout [-q] [-f] [-m] [--detach] <commit>
14
14
git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
15
-
git checkout [-f] <tree-ish> [--] <pathspec>...
16
-
git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
15
+
git checkout <tree-ish> [--] <pathspec>...
16
+
git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
17
17
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
18
18
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
19
19
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
20
20
21
21
DESCRIPTION
22
22
-----------
23
-
Updates files in the working tree to match the version in the index
24
-
or the specified tree. If no pathspec was given, `git checkout` will
25
-
also update `HEAD` to set the specified branch as the current
26
-
branch.
23
+
24
+
`git checkout` has two main modes:
25
+
26
+
1. **Switch branches**, with `git checkout <branch>`
27
+
2. **Restore a different version of a file**, for example with
28
+
`git checkout <commit> <filename>` or `git checkout <filename>`
29
+
30
+
See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
27
31
28
32
`git checkout [<branch>]`::
29
-
To prepare for working on _<branch>_, switch to it by updating
30
-
the index and the files in the working tree, and by pointing
31
-
`HEAD` at the branch. Local modifications to the files in the
32
-
working tree are kept, so that they can be committed to the
33
-
_<branch>_.
33
+
Switch to _<branch>_. This sets the current branch to _<branch>_ and
34
+
updates the files in your working directory. The checkout will fail
35
+
if there are uncommitted changes to any files where _<branch>_ and
36
+
your current commit have different content. Uncommitted changes will
37
+
otherwise be kept.
34
38
+
35
39
If _<branch>_ is not found but there does exist a tracking branch in
36
40
exactly one remote (call it _<remote>_) with a matching name and
···
40
44
$ git checkout -b <branch> --track <remote>/<branch>
41
45
------------
42
46
+
43
-
You could omit _<branch>_, in which case the command degenerates to
44
-
"check out the current branch", which is a glorified no-op with
45
-
rather expensive side-effects to show only the tracking information,
46
-
if it exists, for the current branch.
47
+
Running `git checkout` without specifying a branch has no effect except
48
+
to print out the tracking information for the current branch.
47
49
48
-
`git checkout (-b|-B) <new-branch> [<start-point>]`::
50
+
`git checkout -b <new-branch> [<start-point>]`::
49
51
50
-
Specifying `-b` causes a new branch to be created as if
51
-
linkgit:git-branch[1] were called and then checked out. In
52
-
this case you can use the `--track` or `--no-track` options,
53
-
which will be passed to `git branch`. As a convenience,
54
-
`--track` without `-b` implies branch creation; see the
55
-
description of `--track` below.
56
-
+
57
-
If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it
58
-
is reset. This is the transactional equivalent of
59
-
+
60
-
------------
61
-
$ git branch -f <branch> [<start-point>]
62
-
$ git checkout <branch>
63
-
------------
52
+
Create a new branch named _<new-branch>_, start it at _<start-point>_
53
+
(defaults to the current commit), and check out the new branch.
54
+
You can use the `--track` or `--no-track` options to set the branch's
55
+
upstream tracking information.
64
56
+
65
-
that is to say, the branch is not reset/created unless "git checkout" is
66
-
successful (e.g., when the branch is in use in another worktree, not
67
-
just the current branch stays the same, but the branch is not reset to
68
-
the start-point, either).
57
+
This will fail if there's an error checking out _<new-branch>_, for
58
+
example if checking out the `<start-point>` commit would overwrite your
59
+
uncommitted changes.
60
+
61
+
`git checkout -B <branch> [<start-point>]`::
62
+
63
+
The same as `-b`, except that if the branch already exists it
64
+
resets `_<branch>_` to the start point instead of failing.
69
65
70
66
`git checkout --detach [<branch>]`::
71
67
`git checkout [--detach] <commit>`::
72
68
73
-
Prepare to work on top of _<commit>_, by detaching `HEAD` at it
74
-
(see "DETACHED HEAD" section), and updating the index and the
75
-
files in the working tree. Local modifications to the files
76
-
in the working tree are kept, so that the resulting working
77
-
tree will be the state recorded in the commit plus the local
78
-
modifications.
69
+
The same as `git checkout <branch>`, except that instead of pointing
70
+
`HEAD` at the branch, it points `HEAD` at the commit ID.
71
+
See the "DETACHED HEAD" section below for more.
79
72
+
80
-
When the _<commit>_ argument is a branch name, the `--detach` option can
81
-
be used to detach `HEAD` at the tip of the branch (`git checkout
82
-
<branch>` would check out that branch without detaching `HEAD`).
73
+
Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
74
+
75
+
`git checkout <tree-ish> [--] <pathspec>...`::
76
+
`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
77
+
78
+
Replace the specified files and/or directories with the version from
79
+
the given commit or tree and add them to the index
80
+
(also known as "staging area").
83
81
+
84
-
Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
82
+
For example, `git checkout main file.txt` will replace `file.txt`
83
+
with the version from `main`.
85
84
86
-
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
87
-
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
85
+
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
86
+
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
88
87
89
-
Overwrite the contents of the files that match the pathspec.
90
-
When the _<tree-ish>_ (most often a commit) is not given,
91
-
overwrite working tree with the contents in the index.
92
-
When the _<tree-ish>_ is given, overwrite both the index and
93
-
the working tree with the contents at the _<tree-ish>_.
88
+
Replace the specified files and/or directories with the version from
89
+
the index.
94
90
+
95
-
The index may contain unmerged entries because of a previous failed merge.
96
-
By default, if you try to check out such an entry from the index, the
97
-
checkout operation will fail and nothing will be checked out.
98
-
Using `-f` will ignore these unmerged entries. The contents from a
99
-
specific side of the merge can be checked out of the index by
100
-
using `--ours` or `--theirs`. With `-m`, changes made to the working tree
101
-
file can be discarded to re-create the original conflicted merge result.
91
+
For example, if you check out a commit, edit `file.txt`, and then
92
+
decide those changes were a mistake, `git checkout file.txt` will
93
+
discard any unstaged changes to `file.txt`.
94
+
+
95
+
This will fail if the file has a merge conflict and you haven't yet run
96
+
`git add file.txt` (or something equivalent) to mark it as resolved.
97
+
You can use `-f` to ignore the unmerged files instead of failing, use
98
+
`--ours` or `--theirs` to replace them with the version from a specific
99
+
side of the merge, or use `-m` to replace them with the original
100
+
conflicted merge result.
102
101
103
102
`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
104
-
This is similar to the previous mode, but lets you use the
103
+
This is similar to the previous two modes, but lets you use the
105
104
interactive interface to show the "diff" output and choose which
106
105
hunks to use in the result. See below for the description of
107
106
`--patch` option.
···
155
154
see linkgit:git-branch[1] for details.
156
155
157
156
`-B <new-branch>`::
158
-
Creates the branch _<new-branch>_, start it at _<start-point>_;
159
-
if it already exists, then reset it to _<start-point>_. And then
160
-
check the resulting branch out. This is equivalent to running
161
-
`git branch` with `-f` followed by `git checkout` of that branch;
162
-
see linkgit:git-branch[1] for details.
157
+
The same as `-b`, except that if the branch already exists it
158
+
resets `_<branch>_` to the start point instead of failing.
163
159
164
160
`-t`::
165
161
`--track[=(direct|inherit)]`::
166
162
When creating a new branch, set up "upstream" configuration. See
167
-
`--track` in linkgit:git-branch[1] for details.
163
+
`--track` in linkgit:git-branch[1] for details. As a convenience,
164
+
--track without -b implies branch creation.
168
165
+
169
166
If no `-b` option is given, the name of the new branch will be
170
167
derived from the remote-tracking branch, by looking at the local part of
···
511
508
ARGUMENT DISAMBIGUATION
512
509
-----------------------
513
510
514
-
When there is only one argument given and it is not `--` (e.g. `git
515
-
checkout abc`), and when the argument is both a valid _<tree-ish>_
516
-
(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file
517
-
or a directory whose name is "abc" exists), Git would usually ask
518
-
you to disambiguate. Because checking out a branch is so common an
519
-
operation, however, `git checkout abc` takes "abc" as a _<tree-ish>_
520
-
in such a situation. Use `git checkout -- <pathspec>` if you want
521
-
to checkout these paths out of the index.
511
+
When you run `git checkout <something>`, Git tries to guess whether
512
+
`<something>` is intended to be a branch, a commit, or a set of file(s),
513
+
and then either switches to that branch or commit, or restores the
514
+
specified files.
515
+
516
+
If there's any ambiguity, Git will treat `<something>` as a branch or
517
+
commit, but you can use the double dash `--` to force Git to treat the
518
+
parameter as a list of files and/or directories, like this:
519
+
520
+
----------
521
+
git checkout -- file.txt
522
+
----------
522
523
523
524
EXAMPLES
524
525
--------