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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 31, 2015, 16:38 UTC
Message-ID: <xmqqd23prukg.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20150331152224.GA16617@kitenet.net>

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.

Show 10 quoted lines

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