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

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

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