On Tue, Aug 26, 2025, at 6:43 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > >> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc >> index b343d292b30b..9f2b86ac5368 100644 >> --- a/Documentation/git-checkout.adoc >> +++ b/Documentation/git-checkout.adoc >> @@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch. >> `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`:: >> `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`:: >> >> - Overwrite the contents of the files that match the pathspec. >> - When the _<tree-ish>_ (most often a commit) is not given, >> - overwrite working tree with the contents in the index. >> - When the _<tree-ish>_ is given, overwrite both the index and >> - the working tree with the contents at the _<tree-ish>_. >> + Restore another version of the file(s) that match the pathspec. > > The same comment about "files and directories from a different > version" applies here. > > Also, I am not so sure about the claim that the verb "restore" is > better understood than "overwrite" due to the presence of "git > restore". If you are working on, say, an older maintenance track, > and want to borrow what is in a few files from the development > branch, you may say "git restore --source=develop files..." go grab > them down to your current working tree. But at least to me, > "restore" has a connotation to get back what you used to have, but > the contents in these files you are grabbing had not existed on the > older maintenance track you are working on, ever, and "restore" had > always made me go "Huh?". > > I am not suggesting to change the command name "restore"; I am > suggesting the operation that command does using a verb that is > different from "restore" (in an ancient thread, we tried to explain > "checkout" without using "checkout" as the primary verb to describe > what it does, it is the same thing). > >> + >> -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 > >> +If you specify a commit or tree to restore from (for example `git >> +checkout main file.txt`), this will restore the version of the file(s) >> +from that commit or tree. This overwrites the file in the working >> +directory and stages the file's contents. > > OK. I suspect the most common is to "restore" from HEAD, and the > "Huh?"ness of using the verb "restore" goes away. It clearly is > getting you back to where you were back when your working tree was > in sync with HEAD. Perhaps use "git checkout HEAD file.txt" for the > example? > >> +If you do not specify where to restore from (for example `git checkout >> +file.txt`), this will replace the file(s) with the version from the index. > > That is a very negative way to state it. It is not "do not specify > where". If you do not give tree, you are actively specifying that > you want things from the index. > >> +If you check out a file with an unresolved merge >> +conflict, the checkout operation will fail and no changes will be made. > > This is confusing in a way different from the original. During a > conflicted merge, you will see a few stages until they are resolved. > > (1) The working tree file has conflict markers and text from > multiple variants. The index has higher-stage cache entry for > such a path. > > (2) The user edits the working tree file to resolve the conflicts. > Once all the conflict markers are removed, some people may say > "the merge conflict has been resolved". To Git, the path is > still unmerged. > > (3) The user tells the index what the resolution is, with commands > like "git add", "git rm", and the like. The higher-stage cache > entries in the index for the path are moved and replaced with a > single stage-0 entry. To Git, the path is now merged. > > So, "a file with an unresolved merge conflict" would not mean what > you wanted to say for those who consider that dealing with the > working tree files is enough to declare victory and consider the > conflict has been resolved. > >> +Using `-f` will ignore the merge conflict. The contents from a > > This changes the meaning to most people from what the original > meant. If you have a file F with merge conflicts in the earlier > part but the later part merged cleanly, does "git checkout -f F" > ignore the conflicted part and overwrite the rest of the file > somehow? > > If you wanted to avoid the term "unmerged cache entries", you can > say "unmerged paths". > > Taking all of the above into consideration, perhaps... > > When you are in the middle of a conflicted merge (or > cherry-pick, "stash pop", etc.) and haven't told Git what the > resolution for these conflicted paths are with "git add" and > friends, using "git checkout" to check out such an unmerged path > out of the index would fail and the command exits with non-zero > exit status. > > When the `-f` option is given, these unmerged paths are left > untouched, instead of triggering an error. For all other > (i.e. merged) paths that match the <pathspec>, the working tree > files are overwritten by the version recorded in the index. > > or something along that line, but with a readability enhancement > like you have been doing in your series ;-). Thanks, this section of the man page is not easy and this is very useful feedback. Will work on improving all of these points.
