On Mon, Nov 16 2020, Adam Spiers wrote:
> Hi all,
>
> I just noticed that git-log.txt has:
>
> SYNOPSIS
> --------
> [verse]
> 'git log' [<options>] [<revision range>] [[--] <path>...]
>
> and builtin/log.c has:
>
> static const char * const builtin_log_usage[] = {
> N_("git log [<options>] [<revision-range>] [[--] <path>...]"),
>
> IIUC, the references to <path> should actually be <pathspec> instead,
> as seen with other pathspec-supporting commands such as git add/rm
> whose man pages are extra helpful in explicitly calling out how
> pathspecs can be used, e.g.:
>
> OPTIONS
> -------
> <pathspec>...::
> Files to add content from. Fileglobs (e.g. `*.c`) can
> be given to add all matching files. Also a
> leading directory name (e.g. `dir` to add `dir/file1`
> and `dir/file2`) can be given to update the index to
> match the current state of the directory as a whole (e.g.
> specifying `dir` will record not just a file `dir/file1`
> modified in the working tree, a file `dir/file2` added to
> the working tree, but also a file `dir/file3` removed from
> the working tree). Note that older versions of Git used
> to ignore removed files; use `--no-all` option if you want
> to add modified or new files but ignore removed ones.
> +
> For more details about the <pathspec> syntax, see the 'pathspec' entry
> in linkgit:gitglossary[7].
>
> Would it be fair to say the git-log usage syntax and man page should
> be updated to match? If so perhaps I can volunteer for that.
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.
I've also long wanted (but haven't come up with a patch for) that part
of gitglossary to be ripped out into its own manual page,
e.g. "gitpathspec(5)". And if possible for "PATTERN FORMAT" in
"gitignore" to be unified with that/other docs that describe how our
wildmatch.c works.
There's also the "Conditional includes" section in git-config(1) that
repeats some of that, and probably other stuff I'm forgetting
#leftoverbits.
