Skip to content

Commit 9c0119e

Browse files
committed
doc: git-checkout: clarify restoring files section
- Split up the forms `git checkout file.txt` and `git checkout main file.txt` to match what's given in the SYNOPSIS - Remove `-f` from the SYNOPSIS for the second form, since according to this man page it is not relevant in that context - Many Git users do not know what a "tree-ish" is. Clarify by using an example of each case, and by saying "commit or tree" in the text instead of "<tree-ish>" - Many Git users do not know what the "index" is. Instead say "stage the file's contents" where appropriate, since Git often uses "stage" as a verb to mean the same thing as "add to the index" and it's a more familiar term. - Use "Discard unstaged changes" instead of "checking out paths from the index" where relevant Signed-off-by: Julia Evans <[email protected]>
1 parent 6f3e485 commit 9c0119e

File tree

1 file changed

+28
-17
lines changed

1 file changed

+28
-17
lines changed

Documentation/git-checkout.adoc

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]
1212
git checkout [-q] [-f] [-m] --detach [<branch>]
1313
git checkout [-q] [-f] [-m] [--detach] <commit>
1414
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]
1717
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
1818
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
1919
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
@@ -75,25 +75,36 @@ that is, the branch will not be created or modified unless
7575
+
7676
Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
7777
78-
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
79-
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
78+
`git checkout <tree-ish> [--] <pathspec>...`::
79+
`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
8080
81-
Overwrite the contents of the files that match the pathspec.
82-
When the _<tree-ish>_ (most often a commit) is not given,
83-
overwrite working tree with the contents in the index.
84-
When the _<tree-ish>_ is given, overwrite both the index and
85-
the working tree with the contents at the _<tree-ish>_.
81+
Replace the specified files and/or directories with the version from
82+
the given commit or tree.
8683
+
87-
The index may contain unmerged entries because of a previous failed merge.
88-
By default, if you try to check out such an entry from the index, the
89-
checkout operation will fail and nothing will be checked out.
90-
Using `-f` will ignore these unmerged entries. The contents from a
91-
specific side of the merge can be checked out of the index by
92-
using `--ours` or `--theirs`. With `-m`, changes made to the working tree
93-
file can be discarded to re-create the original conflicted merge result.
84+
For example, `git checkout main file.txt` will restore the version
85+
of `file.txt` from `main`. This overwrites the file in the working
86+
directory and stages the file's contents.
9487
88+
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] <pathspec>...`::
89+
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
90+
91+
Replace the specified files and/or directories with the latest
92+
committed or staged version.
93+
+
94+
This overwrites the file(s) you specify with either the staged version
95+
or the version from the current commit if there is no staged version.
96+
For example, if you've been editing `file.txt` and you want to discard
97+
your changes to it, you can run `git checkout file.txt` to replace it
98+
with the latest committed version.
99+
+
100+
This will fail if the file has a merge conflict and you haven't yet run
101+
`git add file.txt` (or something equivalent) to mark it as resolved.
102+
You can use `-f` to ignore the unmerged files instead of failing, use
103+
`--ours` or `--theirs` to replace them with the version from a specific
104+
side of the merge, or use `-m` to replace them with the original
105+
conflicted merge result.
95106
`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
96-
This is similar to the previous mode, but lets you use the
107+
This is similar to the previous two modes, but lets you use the
97108
interactive interface to show the "diff" output and choose which
98109
hunks to use in the result. See below for the description of
99110
`--patch` option.

0 commit comments

Comments
 (0)