[PATCH v3 6/6] doc: git-checkout: clarify restoring files section
From: Julia Evans <julia@jvns.ca>
- Reword to avoid jargon ("tree-ish", "index") where possible.
Use "commit or tree" and "stage" (as a verb) instead where appropriate
- Add examples
- Use a simpler sentence structure to describe options for handling
unmerged entries: "use -f to.., use --ours to..., or use -m to.."Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-checkout.adoc | 28 ++++++++++++++++------------
1 file changed, 16 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index b361ff011a..ae19565f4f 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -74,23 +74,27 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
`git checkout <tree-ish> [--] <pathspec>...`::
`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
- Overwrite both the index and the working tree with the
- contents at the _<tree-ish>_ for the files that match the pathspec.
+ Replace the specified files and/or directories with the version from
+ the given commit or tree and stage the files' contents.
++
+For example, `git checkout main file.txt` will replace `file.txt`
+with the version from `main`.
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
- Overwrite working tree with the contents in the index for the files
- that match the pathspec.
+ Discard any unstaged changes to the specified files and/or directories.
+ This works by copying the file from the index to your working directory.
+ For example, `git checkout file.txt` will replace `file.txt` with either
+ the staged version of `file.txt` (if there is one) or the version from the
+ current commit.
+
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using `-f` will ignore these unmerged entries. The contents from a
-specific side of the merge can be checked out of the index by
-using `--ours` or `--theirs`. With `-m`, changes made to the working tree
-file can be discarded to re-create the original conflicted merge result.
-
+This will fail if the file has a merge conflict and you haven't yet run
+`git add file.txt` (or something equivalent) to mark it as resolved.
+You can use `-f` to ignore the unmerged files instead of failing, use
+`--ours` or `--theirs` to replace them with the version from a specific
+side of the merge, or use `-m` to replace them with the original
+conflicted merge result.
`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
This is similar to the previous two modes, but lets you use the
interactive interface to show the "diff" output and choose which
--
gitgitgadget
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>