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

[Johannes Sixt <j6t@kdbg.org>]

Am 23.10.20 um 05:49 schrieb Junio C Hamano:
> Instead of explaining the requirement for the paths to be up-to-date,
> as if it is an afterthought, state it upfront.
> 
> The updated description matches how the checks actually are
> performed.  A path that is "dirty" stops the patch application from
> being attempted to either working tree files or to the index.
> 
> Hopefully this change would help users to form a better mental
> model.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> 
>  * Just noticed while reviewing how "apply" (and "am") are explained.
> 
>  Documentation/git-apply.txt | 12 +++++-------
>  1 file changed, 5 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
> index 91d9a8601c..1be7751f58 100644
> --- a/Documentation/git-apply.txt
> +++ b/Documentation/git-apply.txt
> @@ -61,13 +61,11 @@ OPTIONS
>  	file and detects errors.  Turns off "apply".
>  
>  --index::
> -	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.

>  
>  --cached::
>  	Apply the patch to just the index, without touching the working
> 

-- Hannes