Re: "git grep" and "working tree" vs "working directory"

["Robert P. J. Day" <rpjday@crashcourse.ca>]

On Fri, 25 May 2018, Junio C Hamano wrote:

> Stefan Beller <sbeller@google.com> writes:
>
> > 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:
> >>
> >>   <pathspec>...
> >>       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 <pathspec> syntax, see the pathspec
> >>       entry in gitglossary(7).
> >>
> >> but, again, what if <pathspec> 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
========================================================================