Re: [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer

["Philip Oakley" <philipoakley@iee.org>]

From: "Junio C Hamano" <gitster@pobox.com>    Sent: Tuesday, April 18, 2017 
1:31 AM
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>>> If we'd created and added a file d just before the checkout, what
>>>> should
>>>> have happened to d, and why?
>>>
>>> I understand what the command does. It behaves perfectly as I expected
>>> it to. I did not find this script but wrote it to demonstrate that what
>>> the documentation says is different from how it behaves after having
>>> read what the documentation says it should do and noticing that that's
>>> not how I expected it to work from experience.
>>>
>>> What it really does is to copy all files described by the given paths
>>> from the given tree-ish to the working directory. Or at least that's my
>>> expectation of what it does.
>>>
>>> The documentation, however, says that the given paths are *restored*.
>>> This is different.
>>
>> I don't see that difference in the phrase *restored*, compared to your
>> 'copy all files described by the given paths'. Could you explain a
>> little more?
>
> I am obviously not Christoph, and I was the one that defined how
> "checkout <tree> -- <pathspec>" should work, but when you say
> "restore" (which is not what I wrote ;-)) it is fair to expect lack
> of 'd' could also be "restored", in addition to path that was in the
> directory.
>
> Obviously, "grab all paths that match <pathspec> out of <tree>, add
> them to the index and copy them out to the working tree" will never
> be able to _restore_ the lack of 'd', even it may match the
> <pathspec> being used to do this checkout, by removing it from the
> current index and the working tree.
>
My attempt at asking about an additional file 'd' ended up being a bit of a 
red herring as it went off at a tangent.

Hopefully Christoph will hang in to help clarify the original issue. I think 
I'm getting a sense of the potential confusion between the different 
messages Git sends out, and which one is the right one here. On the one hand 
Git promotes the two step staging area approach, but on the other hand the 
checkout of a file suggests IIUC that all checkouts will end up as staged 
revisions (one step only).

Philip