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

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

[Robert P. J. Day]

  more puzzling terminology, this time in the man page for "git grep".
the SYNOPSIS shows, at the very end, the clearly optional
"[<pathspec>...]",

    git grep ...
           ... snip ...
           [--] [<pathspec>...]

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:

  <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?

  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
========================================================================

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

[Stefan Beller]

On Wed, May 23, 2018 at 11:50 AM, Robert P. J. Day
<rpjday@crashcourse.ca> wrote:
>
>   more puzzling terminology, this time in the man page for "git grep".
> the SYNOPSIS shows, at the very end, the clearly optional
> "[<pathspec>...]",
>
>     git grep ...
>            ... snip ...
>            [--] [<pathspec>...]
>
> 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.fsf@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:
>
>   <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/."

>
>   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.

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

[Junio C Hamano]

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.

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

[Robert P. J. Day]

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
========================================================================