From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 26 Aug 2025 22:43:25 GMT
Subject: Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section
Message-ID: <xmqqiki9hfg2.fsf@gitster.g>
In-Reply-To: <b641874627b3898831c3965616e936bd4ee310df.1756148933.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> 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 ;-).