From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 03 Sep 2025 21:29:56 GMT
Subject: Re: [PATCH v3 6/6] doc: git-checkout: clarify restoring files section
Message-ID: <xmqqecsndy23.fsf@gitster.g>
In-Reply-To: <90fe48cfe37852b9e245aa0f7b45383f9b879199.1756918202.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> -	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.

Hmph.  I agree that there is no reason to stress that you are not
required to use a commit here (hence not much point in saying
tree-ish).  I do not think avoiding "index" (which is not even a
jargon; it is the official name of the thing) is necessarily a good
idea, given that ...

> +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.

... we'd have to say "from the index to your working tree files"
here.  In contrast, the earlier one is "from the commit to the index
and to your working tree files", and explaining it as such may make
the similarity & differences stand out more clearly.

Also, I personally find it easier to follow if you did
"directories. This works by copying" -> "directories, by copying".
It comes from the same "think again when you find that you are
saying 'it means that' and such" principle.

> +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.

OK.