From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 16 Nov 2020 18:55:40 GMT
Subject: Re: git-log: documenting pathspec usage
Message-ID: <xmqqblfx9ln7.fsf@gitster.c.googlers.com>
In-Reply-To: <878sb1fpep.fsf@evledraar.gmail.com>

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> It seems like a good idea to make these consistent, if you're feeling
> more ambitious than just git-log's manpage then:
>     
>     $ git grep '<pathspec>' -- Documentation/git-*.txt|wc -l
>     54
>     $ git grep '<path>' -- Documentation/git-*.txt|wc -l
>     161
>
> Most/all of these should probably be changed to one or the other.

There is another thing we want to normalize.

Originally <pathspec> was invented to be a collective noun (i.e. a
set of one or more wildmatch patterns that specify paths that match
any of these patterns is called a pathspec).  These days, however,
we more often refer to each individual pattern as <pathspec> than
using the word in its original way.  We can look for '<pathspec>...'
in the documentation to find these more modern usage.

This latter form would match readers' expectation better, but there
still are a few places (e.g. "stash forget <pathspec>") that use the
word as a collection of pattterns.  While these places may be using
the word "correctly", in the modern world, they give an incorrect
impression that the command somehow is special and can take a
pathspec with only a single pattern, when they can take one or more
patterns.

We should make sure we use "<pathspec>..."  uniformly in the
documentation in these places.

Thanks.