Re: Meta-variable naming convention in documentation

Mark Lodato <lodatom@gmail.com> writes:

What does the gap between these two mean? Do you mean "bisect and later are not in the 'exact filenames or directories' group"?

In general, unless the command takes only one filesystem entity (e.g. in "format-patch -o <dir>", <dir> cannot be anything but a single directory; in "blame <file>", <file> cannot be anything but a single file), you never give a single "filename" to git command. Even when you say "git add Makefile", you are _not_ giving a filename that is "M' "a" "k" "e" ...; you are giving a _pattern_ to be matched with files git would find by traversing the filesystem. In the case of "Makefile", it may happen to match only one single file.

This pattern is called "pathspec", and commands that can take one pathspec can always take more than one.

Unfortunately, for historical reasons, there are two semantics of pathspec, and at least three implementations of pathspec logic.

 - diff family (diff, log, show, rev-list) does not support glob.  The
   pattern is matched either as a leading directory path, or exact name.

 - ls-files family (I think "clean" also uses the logic internally) does
   support glob.  The pattern is matched either as a leading directory
   path, exact name, or a glob.

 - grep implements the same logic as ls-files but uses a newer
   implementation better suited for optimized tree traversal.

And there are higher level commands that internally use logic from either diff family or ls-files family. You can guess which pathspec is used if you think about how you would implement what they do. For example:

 - "add <pathspec>" traverses the work tree using ls-files logic and adds
   found files to the index.

 - "add -u <pathspec>" compares the index and the work tree using
   diff-files logic and adds paths with differences to the index.

 - "status" uses "diff-index --cached" logic to come up with 'Changed to
   be committed' list, "diff-files" logic to come up with 'Changed but not
   updated' list, and "ls-files" logic to list 'Untracked' files.

Unifying the two different semantics of pathspecs is one of the suggested topics for GSoC, by the way.

I think it would make sense to document which ones are concrete paths (e.g. "blame takes a filename" vs "diff takes zero or more pathspecs"), but it would not make much sense to document the two different pathspecs. The effort is better spent at fixing the difference --- obviously we would eventually want to be able to say "git diff 'lib/*.h'".