Re: "git grep" and "working tree" vs "working directory"
On Fri, 25 May 2018, Junio C Hamano wrote: > Stefan Bellerwrites: > > > There are 2 dimensions to it: > > * (where you are) > > if you run git-grep from a sub directory of the repository, then the > > "sub-working-tree" > > will be searched. > > s/the repository/the top level directory of the working tree/, perhaps? > > >> also, at the bottom of that section, one reads: > >> > >> ... > >> If given, limit the search to paths matching at least one > >> pattern. Both leading paths match and glob(7) patterns are supported. > >> > >> For more details about the syntax, see the pathspec > >> entry in gitglossary(7). > >> > >> but, again, what if is *not* given? then what? > > > > Assume "$pwd/." > > This is not technically wrong per-se, but I do not think there is > any reason to encourage it over just a simple "." dot. > > >> finally, the first example has the same problem: > >> > >> git grep 'time_t' -- '*.[ch]' > >> Looks for time_t in all tracked .c and .h files in the > >> working directory and its subdirectories. > >> > >> in "the working directory"? > >> > >> what is the proper terminology to be used here? > > > > the working directory sounds right, not sure which aspect you want to be > > exposed more clearly. > > "The part of the working tree below and including your current > working directory", if you really want to be pedantic ;-). > > But almost all the examples that show how to work _with_ Git > inspecting and manipulating tracked contents assume that your > current working directory _is_ inside a working tree of the > repository you are working on, so the above is equivalent to "The > current working directory" should be clear enough for most readers, > I would think. against my better judgment, i'm going to try to summarize this. first, it appears everyone agrees that the proper way to refer to the *entirety* of the checked out content is "working tree", and that is the phrase to use, regardless of your current location in said working tree. so, given that, one might say that the command "git status" would normally display all untracked files in the working tree (because it does so regardless of your current working directory.) related to that, it would seem that the phrase "working tree" is, far and away, the preferred way to refer to the checked out content. on the other end, the meaning of "current working directory" should be self-evident. it's the middle ground, "working directory", that is the problem, since lots of documentation and comments use that phrase interchangeably with "working tree", and i doubt that confusion is ever going away. all one needs to do is: $ grep -r "working directory" * in the git code base to see its prevalence. so, what *should* it mean? or is there any point in even trying to clarify it? rday p.s. i absolutely will not entertain the introduction of the weirdness that is "sub-working-tree." it's just a subdirectory, that's all. -- Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca/dokuwiki Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday
Re: "git grep" and "working tree" vs "working directory"
Stefan Bellerwrites: > There are 2 dimensions to it: > * (where you are) > if you run git-grep from a sub directory of the repository, then the > "sub-working-tree" > will be searched. s/the repository/the top level directory of the working tree/, perhaps? >> also, at the bottom of that section, one reads: >> >> ... >> If given, limit the search to paths matching at least one >> pattern. Both leading paths match and glob(7) patterns are supported. >> >> For more details about the syntax, see the pathspec >> entry in gitglossary(7). >> >> but, again, what if is *not* given? then what? > > Assume "$pwd/." This is not technically wrong per-se, but I do not think there is any reason to encourage it over just a simple "." dot. >> finally, the first example has the same problem: >> >> git grep 'time_t' -- '*.[ch]' >> Looks for time_t in all tracked .c and .h files in the >> working directory and its subdirectories. >> >> in "the working directory"? >> >> what is the proper terminology to be used here? > > the working directory sounds right, not sure which aspect you want to be > exposed more clearly. "The part of the working tree below and including your current working directory", if you really want to be pedantic ;-). But almost all the examples that show how to work _with_ Git inspecting and manipulating tracked contents assume that your current working directory _is_ inside a working tree of the repository you are working on, so the above is equivalent to "The current working directory" should be clear enough for most readers, I would think.
Re: "git grep" and "working tree" vs "working directory"
On Wed, May 23, 2018 at 11:50 AM, Robert P. J. Daywrote: > > more puzzling terminology, this time in the man page for "git grep". > the SYNOPSIS shows, at the very end, the clearly optional > "[...]", > > git grep ... >... snip ... >[--] [...] > > but nowhere in the man page is there an explanation as to the default > value used if there is no pathspec, and here's why that's confusing. > > first, what is the proper phrase for the *entire* checked out repo? What is the *entirety* of a checked out repo? (Is it just the main working tree, or do you mean all directories that are found "git worktree --list" ?) http://public-inbox.org/git/xmqqo9wy4hxa@gitster.mtv.corp.google.com gives insights into "worktree vs working tree", the former being the command and the latter being the directory you work in -- a working directory if you will -- but the terminology is working tree. There was another recent discussion on that, why it stuck with "tree". > working tree? working directory? either? and is that the proper phrase > to use *regardless* of where you happen to be located, perhaps in a > subdirectory? > > i did a quick test and, if i don't supply a pathspec, then "git > grep" (quite reasonably) recursively searches only the *current* > working directory (example from linux kernel source repo): > > $ cd scripts > $ git grep -il torvalds -- > checkstack.pl > get_maintainer.pl > package/mkdebian > $ > > however, if you peruse the very first part of the OPTIONS section of > that man page, you read: > > --cached > Instead of searching tracked files in the working tree, > search blobs registered in the index file. > > --no-index > Search files in the current directory that is not managed by Git. > > --untracked > In addition to searching in the tracked files in the > working tree, search also in untracked files. > > ... snip ... > > note how a couple of those options are described as searching "the > working tree", when they clearly(?) do no such thing if you happen to > be located in a subdirectory. There are 2 dimensions to it: * (where you are) if you run git-grep from a sub directory of the repository, then the "sub-working-tree" will be searched. Extend the example from above by calling cd scripts git rm --cached checkstack.pl git grep -il torvalds -- ls checkstack.pl * (what is searched) The options mentioned above specify what exactly is used as the base for searching (the file system, the index, or a commit) > also, at the bottom of that section, one reads: > > ... > If given, limit the search to paths matching at least one > pattern. Both leading paths match and glob(7) patterns are supported. > > For more details about the syntax, see the pathspec > entry in gitglossary(7). > > but, again, what if is *not* given? then what? Assume "$pwd/." > > finally, the first example has the same problem: > > git grep 'time_t' -- '*.[ch]' > Looks for time_t in all tracked .c and .h files in the > working directory and its subdirectories. > > in "the working directory"? > > what is the proper terminology to be used here? the working directory sounds right, not sure which aspect you want to be exposed more clearly.
"git grep" and "working tree" vs "working directory"
more puzzling terminology, this time in the man page for "git grep". the SYNOPSIS shows, at the very end, the clearly optional "[...]", git grep ... ... snip ... [--] [...] but nowhere in the man page is there an explanation as to the default value used if there is no pathspec, and here's why that's confusing. first, what is the proper phrase for the *entire* checked out repo? working tree? working directory? either? and is that the proper phrase to use *regardless* of where you happen to be located, perhaps in a subdirectory? i did a quick test and, if i don't supply a pathspec, then "git grep" (quite reasonably) recursively searches only the *current* working directory (example from linux kernel source repo): $ cd scripts $ git grep -il torvalds -- checkstack.pl get_maintainer.pl package/mkdebian $ however, if you peruse the very first part of the OPTIONS section of that man page, you read: --cached Instead of searching tracked files in the working tree, search blobs registered in the index file. --no-index Search files in the current directory that is not managed by Git. --untracked In addition to searching in the tracked files in the working tree, search also in untracked files. ... snip ... note how a couple of those options are described as searching "the working tree", when they clearly(?) do no such thing if you happen to be located in a subdirectory. also, at the bottom of that section, one reads: ... If given, limit the search to paths matching at least one pattern. Both leading paths match and glob(7) patterns are supported. For more details about the syntax, see the pathspec entry in gitglossary(7). but, again, what if is *not* given? then what? finally, the first example has the same problem: git grep 'time_t' -- '*.[ch]' Looks for time_t in all tracked .c and .h files in the working directory and its subdirectories. in "the working directory"? what is the proper terminology to be used here? rday -- Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca/dokuwiki Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday