{"thread":{"id":"54651","subject":"git-log: documenting pathspec usage","startedAt":"2020-11-16T12:38:32Z","lastAt":"2020-11-16T18:56:10Z","messageCount":4,"participants":["Adam Spiers","Ævar Arnfjörð Bjarmason","Philippe Blain","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"410005","messageId":"20201116122230.eyizwe2bmqkmftch@gmail.com","threadId":"54651","inReplyTo":null,"subject":"git-log: documenting pathspec usage","fromName":"Adam Spiers","fromEmail":"git@adamspiers.org","sentAt":"2020-11-16T12:22:30Z","receivedAt":"2020-11-16T12:38:32Z","isPatch":false,"sender":{"key":"git@adamspiers.org","avatar":"https://avatars.githubusercontent.com/u/100738?v=4"},"body":"Hi all,\n\nI just noticed that git-log.txt has: \n\n SYNOPSIS\n --------\n [verse]\n 'git log' [] [] [[--] ...]\n\nand builtin/log.c has: \n\n static const char * const builtin_log_usage[] = {\n N_(\"git log [] [] [[--] ...]\"),\n\nIIUC, the references to should actually be instead,\nas seen with other pathspec-supporting commands such as git add/rm\nwhose man pages are extra helpful in explicitly calling out how\npathspecs can be used, e.g.:\n\n OPTIONS\n -------\n ...::\n Files to add content from. Fileglobs (e.g. `*.c`) can\n be given to add all matching files. Also a\n leading directory name (e.g. `dir` to add `dir/file1`\n and `dir/file2`) can be given to update the index to\n match the current state of the directory as a whole (e.g.\n specifying `dir` will record not just a file `dir/file1`\n modified in the working tree, a file `dir/file2` added to\n the working tree, but also a file `dir/file3` removed from\n the working tree). Note that older versions of Git used\n to ignore removed files; use `--no-all` option if you want\n to add modified or new files but ignore removed ones.\n +\n For more details about the syntax, see the 'pathspec' entry\n in linkgit:gitglossary[7].\n\nWould it be fair to say the git-log usage syntax and man page should\nbe updated to match? If so perhaps I can volunteer for that.\n\nRegards,\nAdam\n"},{"id":"410007","messageId":"878sb1fpep.fsf@evledraar.gmail.com","threadId":"54651","inReplyTo":"20201116122230.eyizwe2bmqkmftch@gmail.com","subject":"Re: git-log: documenting pathspec usage","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2020-11-16T12:37:50Z","receivedAt":"2020-11-16T12:38:42Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Nov 16 2020, Adam Spiers wrote:\n\n> Hi all,\n>\n> I just noticed that git-log.txt has: \n>\n> SYNOPSIS\n> --------\n> [verse]\n> 'git log' [] [] [[--] ...]\n>\n> and builtin/log.c has: \n>\n> static const char * const builtin_log_usage[] = {\n> N_(\"git log [] [] [[--] ...]\"),\n>\n> IIUC, the references to should actually be instead,\n> as seen with other pathspec-supporting commands such as git add/rm\n> whose man pages are extra helpful in explicitly calling out how\n> pathspecs can be used, e.g.:\n>\n> OPTIONS\n> -------\n> ...::\n> Files to add content from. Fileglobs (e.g. `*.c`) can\n> be given to add all matching files. Also a\n> leading directory name (e.g. `dir` to add `dir/file1`\n> and `dir/file2`) can be given to update the index to\n> match the current state of the directory as a whole (e.g.\n> specifying `dir` will record not just a file `dir/file1`\n> modified in the working tree, a file `dir/file2` added to\n> the working tree, but also a file `dir/file3` removed from\n> the working tree). Note that older versions of Git used\n> to ignore removed files; use `--no-all` option if you want\n> to add modified or new files but ignore removed ones.\n> +\n> For more details about the syntax, see the 'pathspec' entry\n> in linkgit:gitglossary[7].\n>\n> Would it be fair to say the git-log usage syntax and man page should\n> be updated to match? If so perhaps I can volunteer for that.\n\nIt seems like a good idea to make these consistent, if you're feeling\nmore ambitious than just git-log's manpage then:\n \n $ git grep '' -- Documentation/git-*.txt|wc -l\n 54\n $ git grep '' -- Documentation/git-*.txt|wc -l\n 161\n\nMost/all of these should probably be changed to one or the other.\n\nI've also long wanted (but haven't come up with a patch for) that part\nof gitglossary to be ripped out into its own manual page,\ne.g. \"gitpathspec(5)\". And if possible for \"PATTERN FORMAT\" in\n\"gitignore\" to be unified with that/other docs that describe how our\nwildmatch.c works.\n\nThere's also the \"Conditional includes\" section in git-config(1) that\nrepeats some of that, and probably other stuff I'm forgetting\n#leftoverbits.\n"},{"id":"410028","messageId":"63667234-DCBD-4ED3-BF80-664CD5981874@gmail.com","threadId":"54651","inReplyTo":"878sb1fpep.fsf@evledraar.gmail.com","subject":"Re: git-log: documenting pathspec usage","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-11-16T17:46:11Z","receivedAt":"2020-11-16T17:46:19Z","isPatch":false,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Adam, Hi Ævar,\n\n> Le 16 nov. 2020 à 07:37, Ævar Arnfjörð Bjarmason a écrit :\n> \n> \n> On Mon, Nov 16 2020, Adam Spiers wrote:\n> \n>> Hi all,\n>> \n>> I just noticed that git-log.txt has: \n>> \n>> SYNOPSIS\n>> --------\n>> [verse]\n>> 'git log' [] [] [[--] ...]\n>> \n>> and builtin/log.c has: \n>> \n>> static const char * const builtin_log_usage[] = {\n>> N_(\"git log [] [] [[--] ...]\"),\n>> \n>> IIUC, the references to should actually be instead,\n>> as seen with other pathspec-supporting commands such as git add/rm\n>> whose man pages are extra helpful in explicitly calling out how\n>> pathspecs can be used, e.g.:\n>> \n>> OPTIONS\n>> -------\n>> ...::\n>> Files to add content from. Fileglobs (e.g. `*.c`) can\n>> be given to add all matching files. Also a\n>> leading directory name (e.g. `dir` to add `dir/file1`\n>> and `dir/file2`) can be given to update the index to\n>> match the current state of the directory as a whole (e.g.\n>> specifying `dir` will record not just a file `dir/file1`\n>> modified in the working tree, a file `dir/file2` added to\n>> the working tree, but also a file `dir/file3` removed from\n>> the working tree). Note that older versions of Git used\n>> to ignore removed files; use `--no-all` option if you want\n>> to add modified or new files but ignore removed ones.\n>> +\n>> For more details about the syntax, see the 'pathspec' entry\n>> in linkgit:gitglossary[7].\n>> \n>> Would it be fair to say the git-log usage syntax and man page should\n>> be updated to match? If so perhaps I can volunteer for that.\n> \n> It seems like a good idea to make these consistent, if you're feeling\n> more ambitious than just git-log's manpage then:\n> \n> $ git grep '' -- Documentation/git-*.txt|wc -l\n> 54\n> $ git grep '' -- Documentation/git-*.txt|wc -l\n> 161\n\nAnd 'ls-files' uses ...\n\n> Most/all of these should probably be changed to one or the other.\n\nI completely agree. I think should be used for every command\nthat takes a pathspec.\n\nIn general, there can be discrepancies between the\nshort help of each command and the \"Synopsis\" section of the long help\n(man page). I wonder what we could do to try to keep these more in sync.\nIn addFor example, some 'git blame' options appear only in the short help, \n\nIdeally, there would be a single source of truth for both of these, in my opinion,\nbut that would mean that the documentation build would somehow have to be taught\nto read the source code and find the 'usage' function for each Git command and feed that\nto the synopsis section (although the synopsis is usually more detailed than\nthe usage). One can always dream...\n\n> I've also long wanted (but haven't come up with a patch for) that part\n> of gitglossary to be ripped out into its own manual page,\n> e.g. \"gitpathspec(5)\".\n\nThat is also on my personal todo list for Git. I think it's a great idea. This way\ncommands that take a pathspec could then link directly to this new guide.\n\nCheers,\n\nPhilippe.\n\n\n"},{"id":"410033","messageId":"xmqqblfx9ln7.fsf@gitster.c.googlers.com","threadId":"54651","inReplyTo":"878sb1fpep.fsf@evledraar.gmail.com","subject":"Re: git-log: documenting pathspec usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-11-16T18:55:40Z","receivedAt":"2020-11-16T18:56:10Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> It seems like a good idea to make these consistent, if you're feeling\n> more ambitious than just git-log's manpage then:\n> \n> $ git grep '' -- Documentation/git-*.txt|wc -l\n> 54\n> $ git grep '' -- Documentation/git-*.txt|wc -l\n> 161\n>\n> Most/all of these should probably be changed to one or the other.\n\nThere is another thing we want to normalize.\n\nOriginally was invented to be a collective noun (i.e. a\nset of one or more wildmatch patterns that specify paths that match\nany of these patterns is called a pathspec). These days, however,\nwe more often refer to each individual pattern as than\nusing the word in its original way. We can look for '...'\nin the documentation to find these more modern usage.\n\nThis latter form would match readers' expectation better, but there\nstill are a few places (e.g. \"stash forget \") that use the\nword as a collection of pattterns. While these places may be using\nthe word \"correctly\", in the modern world, they give an incorrect\nimpression that the command somehow is special and can take a\npathspec with only a single pattern, when they can take one or more\npatterns.\n\nWe should make sure we use \"...\" uniformly in the\ndocumentation in these places.\n\nThanks.\n\n"}]}