"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
"[<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

On Wed, May 23, 2018 at 11:50 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:

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

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)

Assume "$pwd/."

the working directory sounds right, not sure which aspect you want to be exposed more clearly.

Stefan Beller <sbeller@google.com> writes:

s/the repository/the top level directory of the working tree/, perhaps?

This is not technically wrong per-se, but I do not think there is any reason to encourage it over just a simple "." dot.

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

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

  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.