On Sat, Oct 01 2022, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes: > >> For "rerere" say "pathspec" consistently, and list the subcommands in >> the order that they're discussed in the "COMMANDS" section of the >> documentation. > > pathspec refers to the entire set of patterns, which consists of one > or more "pathspec element"s, so there is no need for "..." there. Maybe I'm misreading this, but are you suggesting that whenever "<pathspec>" appears in the text the user should understand it as "<pathspec>...", i.e. as is the case with the special-case that is "<options>". I'm not opposet do that, but I really wish we could avoid further special-cases, there's no current user of "<pathspecs>" (with an "s" for plural. If you're saying that "<pathspec>" now should be interpretet like that then surely e.g.: Documentation/git-clone.txt:--recurse-submodules[=<pathspec>]:: Should be read as supporting: --recurse-submodules some/path some-other-path We could say that using it in that option context is a further special-case, but I think this way lies madness, it would mean that e.g.: git some-cmd [--option=<pathspec>] [-- <pathspec>] would have "<pathspec>" mean different things in those two contexts. We also have various examples of "<pathspec>..." meaning what it means in the post-image here (including in one of the version of the "rerere" docs): Documentation/git-add.txt: [--] [<pathspec>...] Documentation/git-commit.txt: [--] [<pathspec>...] Documentation/git-reset.txt:'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...] FWIW it should arguably be [<pathspec>...] here, but per 5d2c3b01604 (rerere forget: deprecate invocation without pathspec, 2011-03-01) it looks as though we want to advertise the other usage.
