From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 18 Apr 2017 00:31:33 GMT
Subject: Re: [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer
Message-ID: <xmqqa87eimje.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <5FD0803E166B4D2F9F64D8D21AC23EB3@PhilipOakley>

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