Re: git-log: documenting pathspec usage

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 16, 2020, 18:55 UTC
Message-ID: <xmqqblfx9ln7.fsf@gitster.c.googlers.com>
In-Reply-To: <878sb1fpep.fsf@evledraar.gmail.com>

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

Show 9 quoted lines

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