Re: [PATCH] apply: clarify description of --index

[Johannes Sixt <j6t@kdbg.org>]

Am 23.10.20 um 16:38 schrieb Junio C Hamano:
> Johannes Sixt <j6t@kdbg.org> writes:
> 
>>> -	Apply the patch to both the index and the working tree (or
>>> -	merely check that it would apply cleanly to both if `--check` is
>>> -	in effect). Note that `--index` expects index entries and
>>> -	working tree copies for relevant paths to be identical (their
>>> -	contents and metadata such as file mode must match), and will
>>> -	raise an error if they are not, even if the patch would apply
>>> -	cleanly to both the index and the working tree in isolation.
>>> +	After making sure the paths the patch touches in the working
>>> +	tree have no modifications relative to their index entries,
>>> +	apply the patch both to the index entries and to the working
>>> +	tree files or see if it applies	cleanly, when `--check` is in
>>> +	effect.
>>
>> I don't think that this is an improvement. The purpose of --index *is*
>> to apply the patch to both index and worktree, and that should be
>> mentioned first. The check that both are identical, is a prerequisite
>> and not the primary objective of the option.
> 
> Yeah, but this was an attempt to clarify what that "apply to both",
> which is the central part of the operation, exactly means.
> 
> The only mode of operation we offer is that we start from identical
> index and working tree, and make the same change so that we arrive
> at the same outcome.  It is not like you can have some changes in
> the working tree file as long as they do not overlap and collide
> with the incoming patch, make the same change with the patch to
> arrive at different contents as the outcome.  We explicitly forbid
> that, but "apply to both" does not exactly tell it to the readers.

Your have point that the original text muddies the preconditions a bit,
but I still think that "what it does" must be the first thing to be
mentioned, and the preconditions the second.

-- Hannes