{"thread":{"id":"48556","subject":"\"git grep\" and \"working tree\" vs \"working directory\"","startedAt":"2018-05-23T18:51:58Z","lastAt":"2018-05-25T10:58:58Z","messageCount":4,"participants":["Robert P. J. Day","Stefan Beller","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"348382","messageId":"alpine.LFD.2.21.1805231434010.28811@localhost.localdomain","threadId":"48556","inReplyTo":null,"subject":"\"git grep\" and \"working tree\" vs \"working directory\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-23T18:50:12Z","receivedAt":"2018-05-23T18:51:58Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n more puzzling terminology, this time in the man page for \"git grep\".\nthe SYNOPSIS shows, at the very end, the clearly optional\n\"[...]\",\n\n git grep ...\n ... snip ...\n [--] [...]\n\nbut nowhere in the man page is there an explanation as to the default\nvalue used if there is no pathspec, and here's why that's confusing.\n\n first, what is the proper phrase for the *entire* checked out repo?\nworking tree? working directory? either? and is that the proper phrase\nto use *regardless* of where you happen to be located, perhaps in a\nsubdirectory?\n\n i did a quick test and, if i don't supply a pathspec, then \"git\ngrep\" (quite reasonably) recursively searches only the *current*\nworking directory (example from linux kernel source repo):\n\n $ cd scripts\n $ git grep -il torvalds --\n checkstack.pl\n get_maintainer.pl\n package/mkdebian\n $\n\nhowever, if you peruse the very first part of the OPTIONS section of\nthat man page, you read:\n\n --cached\n Instead of searching tracked files in the working tree,\n search blobs registered in the index file.\n\n --no-index\n Search files in the current directory that is not managed by Git.\n\n --untracked\n In addition to searching in the tracked files in the\n working tree, search also in untracked files.\n\n ... snip ...\n\nnote how a couple of those options are described as searching \"the\nworking tree\", when they clearly(?) do no such thing if you happen to\nbe located in a subdirectory.\n\n also, at the bottom of that section, one reads:\n\n ...\n If given, limit the search to paths matching at least one\n pattern. Both leading paths match and glob(7) patterns are supported.\n\n For more details about the syntax, see the pathspec\n entry in gitglossary(7).\n\nbut, again, what if is *not* given? then what?\n\n finally, the first example has the same problem:\n\n git grep 'time_t' -- '*.[ch]'\n Looks for time_t in all tracked .c and .h files in the\n working directory and its subdirectories.\n\nin \"the working directory\"?\n\n what is the proper terminology to be used here?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca/dokuwiki\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"348489","messageId":"CAGZ79kavmH5KVS2Byc5+Hg3dOvVwGD11KZ3yzZTLwp8Ok9ZDTg@mail.gmail.com","threadId":"48556","inReplyTo":"alpine.LFD.2.21.1805231434010.28811@localhost.localdomain","subject":"Re: \"git grep\" and \"working tree\" vs \"working directory\"","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-05-24T20:50:56Z","receivedAt":"2018-05-24T20:51:01Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, May 23, 2018 at 11:50 AM, Robert P. J. Day\n wrote:\n>\n> more puzzling terminology, this time in the man page for \"git grep\".\n> the SYNOPSIS shows, at the very end, the clearly optional\n> \"[...]\",\n>\n> git grep ...\n> ... snip ...\n> [--] [...]\n>\n> but nowhere in the man page is there an explanation as to the default\n> value used if there is no pathspec, and here's why that's confusing.\n>\n> first, what is the proper phrase for the *entire* checked out repo?\n\nWhat is the *entirety* of a checked out repo?\n(Is it just the main working tree, or do you mean all directories that are\nfound \"git worktree --list\" ?)\n\nhttp://public-inbox.org/git/xmqqo9wy4hxa.fsf@gitster.mtv.corp.google.com\ngives insights into \"worktree vs working tree\", the former being the command\nand the latter being the directory you work in -- a working directory if you\nwill -- but the terminology is working tree. There was another recent discussion\non that, why it stuck with \"tree\".\n\n\n> working tree? working directory? either? and is that the proper phrase\n> to use *regardless* of where you happen to be located, perhaps in a\n> subdirectory?\n>\n> i did a quick test and, if i don't supply a pathspec, then \"git\n> grep\" (quite reasonably) recursively searches only the *current*\n> working directory (example from linux kernel source repo):\n>\n> $ cd scripts\n> $ git grep -il torvalds --\n> checkstack.pl\n> get_maintainer.pl\n> package/mkdebian\n> $\n>\n> however, if you peruse the very first part of the OPTIONS section of\n> that man page, you read:\n>\n> --cached\n> Instead of searching tracked files in the working tree,\n> search blobs registered in the index file.\n>\n> --no-index\n> Search files in the current directory that is not managed by Git.\n>\n> --untracked\n> In addition to searching in the tracked files in the\n> working tree, search also in untracked files.\n>\n> ... snip ...\n>\n> note how a couple of those options are described as searching \"the\n> working tree\", when they clearly(?) do no such thing if you happen to\n> be located in a subdirectory.\n\nThere are 2 dimensions to it:\n* (where you are)\n if you run git-grep from a sub directory of the repository, then the\n\"sub-working-tree\"\n will be searched. Extend the example from above by calling\n cd scripts\n git rm --cached checkstack.pl\n git grep -il torvalds --\n ls checkstack.pl\n\n* (what is searched)\n The options mentioned above specify what exactly is used as the base\nfor searching\n (the file system, the index, or a commit)\n\n\n> also, at the bottom of that section, one reads:\n>\n> ...\n> If given, limit the search to paths matching at least one\n> pattern. Both leading paths match and glob(7) patterns are supported.\n>\n> For more details about the syntax, see the pathspec\n> entry in gitglossary(7).\n>\n> but, again, what if is *not* given? then what?\n\nAssume \"$pwd/.\"\n\n>\n> finally, the first example has the same problem:\n>\n> git grep 'time_t' -- '*.[ch]'\n> Looks for time_t in all tracked .c and .h files in the\n> working directory and its subdirectories.\n>\n> in \"the working directory\"?\n>\n> what is the proper terminology to be used here?\n\nthe working directory sounds right, not sure which aspect you want to be\nexposed more clearly.\n"},{"id":"348502","messageId":"xmqqa7sor1t3.fsf@gitster-ct.c.googlers.com","threadId":"48556","inReplyTo":"CAGZ79kavmH5KVS2Byc5+Hg3dOvVwGD11KZ3yzZTLwp8Ok9ZDTg@mail.gmail.com","subject":"Re: \"git grep\" and \"working tree\" vs \"working directory\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-05-25T00:55:52Z","receivedAt":"2018-05-25T00:56:00Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> There are 2 dimensions to it:\n> * (where you are)\n> if you run git-grep from a sub directory of the repository, then the\n> \"sub-working-tree\"\n> will be searched.\n\ns/the repository/the top level directory of the working tree/, perhaps?\n\n>> also, at the bottom of that section, one reads:\n>>\n>> ...\n>> If given, limit the search to paths matching at least one\n>> pattern. Both leading paths match and glob(7) patterns are supported.\n>>\n>> For more details about the syntax, see the pathspec\n>> entry in gitglossary(7).\n>>\n>> but, again, what if is *not* given? then what?\n>\n> Assume \"$pwd/.\"\n\nThis is not technically wrong per-se, but I do not think there is\nany reason to encourage it over just a simple \".\" dot.\n\n>> finally, the first example has the same problem:\n>>\n>> git grep 'time_t' -- '*.[ch]'\n>> Looks for time_t in all tracked .c and .h files in the\n>> working directory and its subdirectories.\n>>\n>> in \"the working directory\"?\n>>\n>> what is the proper terminology to be used here?\n>\n> the working directory sounds right, not sure which aspect you want to be\n> exposed more clearly.\n\n\"The part of the working tree below and including your current\nworking directory\", if you really want to be pedantic ;-).\n\nBut almost all the examples that show how to work _with_ Git\ninspecting and manipulating tracked contents assume that your\ncurrent working directory _is_ inside a working tree of the\nrepository you are working on, so the above is equivalent to \"The\ncurrent working directory\" should be clear enough for most readers,\nI would think.\n\n"},{"id":"348535","messageId":"alpine.LFD.2.21.1805250649180.11158@localhost.localdomain","threadId":"48556","inReplyTo":"xmqqa7sor1t3.fsf@gitster-ct.c.googlers.com","subject":"Re: \"git grep\" and \"working tree\" vs \"working directory\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-25T10:56:57Z","receivedAt":"2018-05-25T10:58:58Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Fri, 25 May 2018, Junio C Hamano wrote:\n\n> Stefan Beller writes:\n>\n> > There are 2 dimensions to it:\n> > * (where you are)\n> > if you run git-grep from a sub directory of the repository, then the\n> > \"sub-working-tree\"\n> > will be searched.\n>\n> s/the repository/the top level directory of the working tree/, perhaps?\n>\n> >> also, at the bottom of that section, one reads:\n> >>\n> >> ...\n> >> If given, limit the search to paths matching at least one\n> >> pattern. Both leading paths match and glob(7) patterns are supported.\n> >>\n> >> For more details about the syntax, see the pathspec\n> >> entry in gitglossary(7).\n> >>\n> >> but, again, what if is *not* given? then what?\n> >\n> > Assume \"$pwd/.\"\n>\n> This is not technically wrong per-se, but I do not think there is\n> any reason to encourage it over just a simple \".\" dot.\n>\n> >> finally, the first example has the same problem:\n> >>\n> >> git grep 'time_t' -- '*.[ch]'\n> >> Looks for time_t in all tracked .c and .h files in the\n> >> working directory and its subdirectories.\n> >>\n> >> in \"the working directory\"?\n> >>\n> >> what is the proper terminology to be used here?\n> >\n> > the working directory sounds right, not sure which aspect you want to be\n> > exposed more clearly.\n>\n> \"The part of the working tree below and including your current\n> working directory\", if you really want to be pedantic ;-).\n>\n> But almost all the examples that show how to work _with_ Git\n> inspecting and manipulating tracked contents assume that your\n> current working directory _is_ inside a working tree of the\n> repository you are working on, so the above is equivalent to \"The\n> current working directory\" should be clear enough for most readers,\n> I would think.\n\n against my better judgment, i'm going to try to summarize this.\nfirst, it appears everyone agrees that the proper way to refer to the\n*entirety* of the checked out content is \"working tree\", and that is\nthe phrase to use, regardless of your current location in said working\ntree. so, given that, one might say that the command \"git status\"\nwould normally display all untracked files in the working tree\n(because it does so regardless of your current working directory.)\n\n related to that, it would seem that the phrase \"working tree\" is,\nfar and away, the preferred way to refer to the checked out content.\n\n on the other end, the meaning of \"current working directory\" should\nbe self-evident.\n\n it's the middle ground, \"working directory\", that is the problem,\nsince lots of documentation and comments use that phrase\ninterchangeably with \"working tree\", and i doubt that confusion is\never going away. all one needs to do is:\n\n $ grep -r \"working directory\" *\n\nin the git code base to see its prevalence. so, what *should* it mean?\nor is there any point in even trying to clarify it?\n\nrday\n\np.s. i absolutely will not entertain the introduction of the weirdness\nthat is \"sub-working-tree.\" it's just a subdirectory, that's all.\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca/dokuwiki\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"}]}