From: Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
Date: Wed, 03 Sep 2025 16:50:02 GMT
Subject: [PATCH v3 6/6] doc: git-checkout: clarify restoring files section
Message-ID: <90fe48cfe37852b9e245aa0f7b45383f9b879199.1756918202.git.gitgitgadget@gmail.com>
In-Reply-To: <pull.1962.v3.git.1756918202.gitgitgadget@gmail.com>

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