From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 19 Nov 2019 06:05:10 GMT
Subject: Re: [PATCH v2 3/6] doc: reset: unify <pathspec> description
Message-ID: <xmqqv9rgxuy1.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <f961a5155a5ec1590652ce7b5a549eead71930e1.1573055478.git.gitgitgadget@gmail.com>

"Alexandr Miloslavskiy via GitGitGadget" <gitgitgadget@gmail.com>
writes:

> -'git reset' [-q] [<tree-ish>] [--] <paths>...
> -'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]
> +'git reset' [-q] [<tree-ish>] [--] <pathspec>...
> +'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]

Good.

> @@ -18,24 +18,26 @@ In the first and second form, copy entries from `<tree-ish>` to the index.
>  In the third form, set the current branch head (`HEAD`) to `<commit>`,
>  optionally modifying index and working tree to match.
>  The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms.
> +The <pathspec> is used to limit the paths affected by the operation
> +(see the entry for 'pathspec' in linkgit:gitglossary[7] for more details).

Good.

> -'git reset' [-q] [<tree-ish>] [--] <paths>...::
> -	This form resets the index entries for all `<paths>` to their
> +'git reset' [-q] [<tree-ish>] [--] <pathspec>...::
> +	This form resets the index entries for all `<pathspec>` to their

This is not so good.  The original pretended as if <paths> are the
exact pathnames, so it was sort-of OK for it to say "for all paths".
Since we are highlighting the fact that these are not pathnames but
the patterns to match pathnames, however, the description needs a
slight update to match, perhaps like

	ths form resets the index entries for all paths that match
	the `<pathspec>` to their...

>  	state at `<tree-ish>`.  (It does not affect the working tree or
>  	the current branch.)

Thanks.