Re: [PATCH] improve documentation for some commands that use pathspecs

[Junio C Hamano <gitster@pobox.com>]

Joey Hess <joeyh@joeyh.name> writes:

> After being surprised that git-ls-files expands pathspecs, here's a patch
> that would have saved me.
> ---

I have a vague recollection that we originally wanted to
consistently say pathspec but some "user friendliness" folks wanted
to avoid the term as much as possible---blaming might reveal this
may be reverting the description to the original ;-).

I like the general direction, but please sign-off your patch.

> @@ -150,9 +150,10 @@ a space) at the start of each line:
>  \--::
>  	Do not interpret any more arguments as options.
>  
> -<file>::
> +<pathspec>::
>  	Files to show. If no files are given all files which match the other
> -	specified criteria are shown.
> +	specified criteria are shown. (Note that this isn't really raw
> +	pathnames, but rather a list of patterns to match.)

After updating the heading to <pathspec>, it would be clear that it
is not listing filename but a specification to choose path with.  I
do not see the need for this added "Note that".

Perhaps what you need to update is the first sentence "Files to
show".  It is more like "Limit the paths to show with." or
something, perhaps?  Then the "If no files are given" part (which is
wrong after your patch, because this is no longer talking about
giving any "file") can go.  By default we show everything, and
use of pathspecs is merely one of the ways to limit the output, and
you would not want to repeat "if this option is not given, all paths
that match the other specified criteria are shown" to all the other
options that limit what is shown.