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

[Stefan Beller <sbeller@google.com>]

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.