{"thread":{"id":"42750","subject":"[RFD] Place to document magic pathspecs like \":/\" and pathspec handling","startedAt":"2016-06-29T19:49:06Z","lastAt":"2016-07-01T13:18:14Z","messageCount":8,"participants":["Jakub Narębski","Junio C Hamano","Duy Nguyen","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"290524","messageId":"577425EF.6030900@gmail.com","threadId":"42750","inReplyTo":null,"subject":"[RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-06-29T19:47:59Z","receivedAt":"2016-06-29T19:49:06Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Hello,\n\n123456789012345678901234567890123456789012345678901234567890123456789012345|\n\nI have noticed that the magic pathspec \":/\" is described only in RelNotes\nfor revision 1.7.6:\n\n|* A magic pathspec \":/\" tells a command that limits its operation to the current directory when ran from a subdirectory to work on the entire working tree. In general, \":/path/to/file\" would be relative to the root of the working tree hierarchy. After \"git reset --hard; edit Makefile; cd t/\", \"git add -u\" would be a no-op, but \"git add -u :/\" would add the updated contents of the Makefile at the top level. If you want to name a path in the current subdirectory whose unusual name begins with \":/\", you can name it by \"./:/that/path\" or by \"\\:/that/path\".|\n\n||\n|I think the reason might be that there was no good place to put that\ninformation in.  Nowadays we have gitcli(7) manual page, but perhaps\nit would be better to create a separate manpage for issues related\nto pathspec handling (of which \":/\" is only one part)... but then\nwhat should it be named?\n\nWhat do you think?\n-- \nJakub Narębski\n|||\n\n"},{"id":"290525","messageId":"CAPc5daVqjhWrJjNX6monHdMTRwimbjz==j9B2FS-nXNCqPDCYQ@mail.gmail.com","threadId":"42750","inReplyTo":"577425EF.6030900@gmail.com","subject":"Re: [RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-29T19:51:49Z","receivedAt":"2016-06-29T19:52:21Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"On Wed, Jun 29, 2016 at 12:47 PM, Jakub Narębski <jnareb@gmail.com> wrote:\n>\n> I have noticed that the magic pathspec \":/\" is described only in RelNotes\n> for revision 1.7.6:\n> |I think the reason might be that there was no good place to put that\n> information in.  Nowadays we have gitcli(7) manual page, but perhaps\n\n$ git help glossary\n\nlook for pathspec.\n"},{"id":"290539","messageId":"57743BFB.9040709@gmail.com","threadId":"42750","inReplyTo":"CAPc5daVqjhWrJjNX6monHdMTRwimbjz==j9B2FS-nXNCqPDCYQ@mail.gmail.com","subject":"Re: [RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-06-29T21:22:03Z","receivedAt":"2016-06-29T21:22:50Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 2016-06-29 o 21:51, Junio C Hamano pisze:\n> On Wed, Jun 29, 2016 at 12:47 PM, Jakub Narębski <jnareb@gmail.com> wrote:\n>> I have noticed that the magic pathspec \":/\" is described only in RelNotes\n>> for revision 1.7.6:\n>> |I think the reason might be that there was no good place to put that\n>> information in.  Nowadays we have gitcli(7) manual page, but perhaps\n> $ git help glossary\n>\n> look for pathspec.\nThanks. I haven't noticed that.\n\nBut I think it is not the best place to keep this documentation.\nThere are the following issues with it:\n\n* it is hard to find; I did not search _glossary_ for information\n  about how Git handles pathspecs, I would search it if I didn't know\n  what pathspec means.\n\n* it is longest entry in glossary, and the only one with nested\n  list, but\n\n* it is also too short to describe how Git handles pathspecs in detail,\n  and a bit cryptic; there are no examples (so grepping docs for '\":/\"'\n  didn't found it).\n\n-- \nJakub Narębski\n\n"},{"id":"290541","messageId":"xmqqy45n1y8a.fsf@gitster.mtv.corp.google.com","threadId":"42750","inReplyTo":"57743BFB.9040709@gmail.com","subject":"Re: [RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-29T21:28:21Z","receivedAt":"2016-06-29T21:28:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> writes:\n\n> But I think it is not the best place to keep this documentation.\n\nAll true.  In case it was not obvious, I didn't mean to say \"Here\nyou find the information, shut up.\"  It was \"here is a pointer if\nyou didn't find it, so that you can use it as a starting point to\nmake a better documentation.\"\n\nAn analogous entity in the world model of Git that appears\neverywhere and is not limited to a single command is the revision\nset calculus.  Where do we describe it and how do we make it\ndiscoverable?  Can the new way to describe pathspec and pathspec\nmagic mimic the way it is done for the revisions?\n"},{"id":"290582","messageId":"5774E992.7070905@gmail.com","threadId":"42750","inReplyTo":"xmqqy45n1y8a.fsf@gitster.mtv.corp.google.com","subject":"Re: [RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-06-30T09:42:42Z","receivedAt":"2016-06-30T09:44:06Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 2016-06-29 o 23:28, Junio C Hamano pisze:\n> Jakub Narębski <jnareb@gmail.com> writes:\n> \n>> But I think it is not the best place to keep this documentation.\n> \n> All true.  In case it was not obvious, I didn't mean to say \"Here\n> you find the information, shut up.\"  It was \"here is a pointer if\n> you didn't find it, so that you can use it as a starting point to\n> make a better documentation.\"\n> \n> An analogous entity in the world model of Git that appears\n> everywhere and is not limited to a single command is the revision\n> set calculus.  Where do we describe it and how do we make it\n> discoverable?  Can the new way to describe pathspec and pathspec\n> magic mimic the way it is done for the revisions?\n\nIs that a trick question? :-P\n\nThe revision set calculus is described as a standalone documentation\nin the gitrevisions(7) manpage (titled \"specifying revisions and\n[revision] ranges for Git\"... well, the \"[revision]\" isn't there).\nThis documentation is also accessible via `git help revisions`,\nwhich is cool.  It is referenced in the \"Symbolic Identifiers\"\nsection of the git(1) manual page.\n\nLong time ago the description of revision set calculus was hidden\nin the manpage for the plumbing command git-rev-parse, and is still\nincluded in it (the common part is, via \"include::revisions.txt[]\").\n\nAs I wrote:\n\n>>>> Nowadays we have gitcli(7) manual page, but perhaps\n>>>> it would be better to create a separate manpage for issues related\n>>>> to pathspec handling (of which \":/\" is only one part)... but then\n>>>> what should it be named?\n\nSo we could describe how Git handles pathspecs and pathspec magic\nin the new manual page named gitpathspec(7), or gitpaths(7). The\nformer has the advantage of the name being identical to the entry\nin gitglossary(7). The latter has the probable advantage of being\neasier for the Git novice to find, and that it could be used to\ngather various ways to generate list of files in Git (files in\nthe working area, files in the staging area aka the index, files\nin the revision / tree object, changed files, etc.); the pathspec\nin strict sense is about the input. Well, we could have 'manpage\nalias' of gitpaths to gitpathspec, or vice versa.\n\n Sidenote: I wonder if people (especially novices) have problem\n finding relevant documentation, and if adding something like \n \"git apropos <topic>\" command (\"apropos\", or \"man -k\"), or\n add the '--apropos' option to \"git help\" would be useful...\n and if it would be easy to create.\n\nThe description from gitglossary would be a good start, as would\nparts of gitcli and relevant RelNotes. It would need to be linked\nfrom git(1) manpage, and probably also from gitcli.\n\nNow only to start it...\n-- \nJakub Narębski\n\n\n"},{"id":"290597","messageId":"CACsJy8AES0iu341DU6FDYZq6fmssbD3QSZaiwi9BntTnMQS5Gw@mail.gmail.com","threadId":"42750","inReplyTo":"5774E992.7070905@gmail.com","subject":"Re: [RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2016-06-30T15:14:15Z","receivedAt":"2016-06-30T15:15:15Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"Hi Jakub,\n\nWhere have you been all these years? :D\n\nOn Thu, Jun 30, 2016 at 11:42 AM, Jakub Narębski <jnareb@gmail.com> wrote:\n>>>>> Nowadays we have gitcli(7) manual page, but perhaps\n>>>>> it would be better to create a separate manpage for issues related\n>>>>> to pathspec handling (of which \":/\" is only one part)... but then\n>>>>> what should it be named?\n>\n> So we could describe how Git handles pathspecs and pathspec magic\n> in the new manual page named gitpathspec(7), or gitpaths(7). The\n> former has the advantage of the name being identical to the entry\n> in gitglossary(7). The latter has the probable advantage of being\n> easier for the Git novice to find,\n\ngit-pathspec(7) is a great idea. It bugs me that all the pathspec\ndetails are hidden in that glossary file (though I didn't know it was\nalso available via \"git help glossary\", which probably just reinforces\nits invisibility). The closet place I could think of was git(1) but\nthat page is already very long.\n\n> and that it could be used to\n> gather various ways to generate list of files in Git (files in\n> the working area, files in the staging area aka the index, files\n> in the revision / tree object, changed files, etc.);\n\nYou mean the list of commands in this man page? OK. Another thing we\ncould do is the reverse direction, add gitpathspec(7) as a reference\nto all commands that may need it.\n\n> the pathspec\n> in strict sense is about the input. Well, we could have 'manpage\n> alias' of gitpaths to gitpathspec, or vice versa.\n\n>  Sidenote: I wonder if people (especially novices) have problem\n>  finding relevant documentation, and if adding something like\n>  \"git apropos <topic>\" command (\"apropos\", or \"man -k\"), or\n>  add the '--apropos' option to \"git help\" would be useful...\n>  and if it would be easy to create.\n\nI have that problem sometimes and I don't think I can call myself a\nnoob anymore. I usually need to do some grepping. So yeah \"git\napropos\" would be great.\n-- \nDuy\n"},{"id":"290634","messageId":"20160701064224.GD5358@sigill.intra.peff.net","threadId":"42750","inReplyTo":"CACsJy8AES0iu341DU6FDYZq6fmssbD3QSZaiwi9BntTnMQS5Gw@mail.gmail.com","subject":"Re: [RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-07-01T06:42:24Z","receivedAt":"2016-07-01T06:42:54Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Jun 30, 2016 at 05:14:15PM +0200, Duy Nguyen wrote:\n\n> > So we could describe how Git handles pathspecs and pathspec magic\n> > in the new manual page named gitpathspec(7), or gitpaths(7). The\n> > former has the advantage of the name being identical to the entry\n> > in gitglossary(7). The latter has the probable advantage of being\n> > easier for the Git novice to find,\n> \n> git-pathspec(7) is a great idea. It bugs me that all the pathspec\n> details are hidden in that glossary file (though I didn't know it was\n> also available via \"git help glossary\", which probably just reinforces\n> its invisibility). The closet place I could think of was git(1) but\n> that page is already very long.\n> \n> > and that it could be used to\n> > gather various ways to generate list of files in Git (files in\n> > the working area, files in the staging area aka the index, files\n> > in the revision / tree object, changed files, etc.);\n> \n> You mean the list of commands in this man page? OK. Another thing we\n> could do is the reverse direction, add gitpathspec(7) as a reference\n> to all commands that may need it.\n\nI'll second (third?) this. Some of our manpages are quite unwieldy, and\nI don't think we are doing any favors to users when we auto-include the\nsame content in multiple places. I think we should instead be splitting\nconcepts into their own pages and referring to them. That helps users\nbuild the mental model (\"aha, pathspecs; I read that concept page and\nknow how those work!\" instead of \"here's 3 pages of description on how\ngit-diff handles paths. Is it identical to the 3 pages in git-log?\").\n\nI suspect some things like diff options could benefit from a similar\nsplit.\n\n> >  Sidenote: I wonder if people (especially novices) have problem\n> >  finding relevant documentation, and if adding something like\n> >  \"git apropos <topic>\" command (\"apropos\", or \"man -k\"), or\n> >  add the '--apropos' option to \"git help\" would be useful...\n> >  and if it would be easy to create.\n> \n> I have that problem sometimes and I don't think I can call myself a\n> noob anymore. I usually need to do some grepping. So yeah \"git\n> apropos\" would be great.\n\nI think better searching would help a lot if we split things into more\npages (right now, a legitimate technique is \"man git-foo\", using search\nin the pager, and wading through all of the false positives. That sucks,\nbut at least you can find what you want _eventually_).\n\nI'm not sure if \"man -k\" is all that great, though, for two reasons:\n\n  1. AFAIK there isn't an easy way to restrict it only to git manpages\n     (try \"man -k git\"; oh, hello \"isxdigit(3posix)\").\n\n  2. It only searches the title lines. So it's great for finding the\n     pathspec page, but you could probably already do that by guessing\n     it's called \"git help pathspecs\". But if you're looking for\n     discussion of a particular diff option, say, it would be nice to be\n     able to search for all mentions of \"--word-diff-regex\", or\n     something.\n\n     There is \"man -K\", but it kind of sucks (it seems to just dump you\n     in any manpage that matches, in a list).\n\nI don't think those are problems that _git_ should necessarily be\nsolving, though. It's a general problem for manpages. And there may be\nbetter \"man\" implementations than I'm used to (or even options or\nconfiguration I don't know about).\n\n-Peff\n"},{"id":"290658","messageId":"57766D5C.3040200@gmail.com","threadId":"42750","inReplyTo":"20160701064224.GD5358@sigill.intra.peff.net","subject":"Re: [RFD] Place to document magic pathspecs like \":/\" and pathspec handling","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-07-01T13:17:16Z","receivedAt":"2016-07-01T13:18:14Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 2016-07-01 o 08:42, Jeff King pisze:\n> On Thu, Jun 30, 2016 at 05:14:15PM +0200, Duy Nguyen wrote:\n> \n>>> So we could describe how Git handles pathspecs and pathspec magic\n>>> in the new manual page named gitpathspec(7), or gitpaths(7). The\n>>> former has the advantage of the name being identical to the entry\n>>> in gitglossary(7). The latter has the probable advantage of being\n>>> easier for the Git novice to find,\n>>\n>> git-pathspec(7) is a great idea. It bugs me that all the pathspec\n>> details are hidden in that glossary file (though I didn't know it was\n>> also available via \"git help glossary\", which probably just reinforces\n>> its invisibility). The closet place I could think of was git(1) but\n>> that page is already very long.\n>>\n>>> and that it could be used to\n>>> gather various ways to generate list of files in Git (files in\n>>> the working area, files in the staging area aka the index, files\n>>> in the revision / tree object, changed files, etc.);\n>>\n>> You mean the list of commands in this man page? OK. Another thing we\n>> could do is the reverse direction, add gitpathspec(7) as a reference\n>> to all commands that may need it.\n> \n> I'll second (third?) this. Some of our manpages are quite unwieldy, and\n> I don't think we are doing any favors to users when we auto-include the\n> same content in multiple places. I think we should instead be splitting\n> concepts into their own pages and referring to them. That helps users\n> build the mental model (\"aha, pathspecs; I read that concept page and\n> know how those work!\" instead of \"here's 3 pages of description on how\n> git-diff handles paths. Is it identical to the 3 pages in git-log?\").\n> \n> I suspect some things like diff options could benefit from a similar\n> split.\n\nI'd rather we keep manpages self-contained; one reason is as you said\nbelow easier searching.  I also prefer not to have to follow from one\npage to another.\n\nOn the contrary, I think it would be good idea to include full list\nof a configuration variables affecting specific command in its manpage.\nCurrently almost all configuration variables are in git-config(1)\nmanpage, but some are in individual manpages, and only linked there.\n\nRedundancy in reference documentation is not bad, provided that it\ndoesn't require duplication in documentation sources, and that the\ndocumentation itself is not too long, and not too unwieldy.\n\n>>>  Sidenote: I wonder if people (especially novices) have problem\n>>>  finding relevant documentation, and if adding something like\n>>>  \"git apropos <topic>\" command (\"apropos\", or \"man -k\"), or\n>>>  add the '--apropos' option to \"git help\" would be useful...\n>>>  and if it would be easy to create.\n>>\n>> I have that problem sometimes and I don't think I can call myself a\n>> noob anymore. I usually need to do some grepping. So yeah \"git\n>> apropos\" would be great.\n> \n> I think better searching would help a lot if we split things into more\n> pages (right now, a legitimate technique is \"man git-foo\", using search\n> in the pager, and wading through all of the false positives. That sucks,\n> but at least you can find what you want _eventually_).\n> \n> I'm not sure if \"man -k\" is all that great, though, for two reasons:\n> \n>   1. AFAIK there isn't an easy way to restrict it only to git manpages\n>      (try \"man -k git\"; oh, hello \"isxdigit(3posix)\").\n\nOne solution would be to use \"apropos\" / \"man -k\" and then filter it\n(e.g. with /^git/) to filter out non-git manpages. \n\nAnother would be to search whatis database ourselves. Yet another \nto create whatis-like database, and put it in /usr/share/doc/*.\nIn both of those cases Git would search the 'database' itself.\n\n>   2. It only searches the title lines. So it's great for finding the\n>      pathspec page, but you could probably already do that by guessing\n>      it's called \"git help pathspecs\". But if you're looking for\n>      discussion of a particular diff option, say, it would be nice to be\n>      able to search for all mentions of \"--word-diff-regex\", or\n>      something.\n\nWell, for apropos-like command to work well we would need better\ndescription of manpages, isn't it?. It is getting better, but we still\nhave a bit to go...\n\nIf Git was to create a whatis-like database (for future \"--apropos\" and\n\"--whatis\" options to \"git help\"), it could add extra information, for\nexample keywords (which would have to be added to manpages sources,\nand embedded in whatis-like database when creating man, html, etc.\ndocumentaion formats, i.e. when building documentation).\n \n>      There is \"man -K\", but it kind of sucks (it seems to just dump you\n>      in any manpage that matches, in a list).\n\nBy default Git installs into /usr/share/doc/git-x.y.z the *.txt and *.html\ndocumentation formats. We could follow \"man -K\" / \"man --global-apropos\"\nexample and search sources... but then we would need to follow inclusions\nat least for it to be useful. We could search HTML version of manpages...\nbut then we would have to strip formatting codes before performing a search.\n \n> I don't think those are problems that _git_ should necessarily be\n> solving, though. It's a general problem for manpages. And there may be\n> better \"man\" implementations than I'm used to (or even options or\n> configuration I don't know about).\n\nI wonder what other version control systems do, like Mercurial, or\nSubversion, or Veracity with providing access to their reference docs...\n\n-- \nJakub Narębski\n\n\n"}]}