Re: Meta-variable naming convention in documentation

[Mark Lodato <lodatom@gmail.com>]

On Fri, Feb 26, 2010 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> The following accept exact filenames or directories.  If a directory,
>> this matches all files within that directory recursively.
>>
>>       git-archive             path                    fdir
>>
>>       git-bisect              <paths>/<pathspec>      fdir    (f)
>
> What does the gap between these two mean?  Do you mean "bisect and later
> are not in the 'exact filenames or directories' group"?

Each of the three types is divided in two, separated by a blank line.
The first group, all without (f) at the end, die if one of the paths
given on the command line does not exist.  The second group, all with
(f) at the end, do not complain if any of the paths do not match
anything.  I called the latter group "filtering" for lack of a better
term.

So, git-archive, git-add, git-checkout, git-commit, git-rm all take
pathspecs (the first using diff logic, the rest using ls-files logic),
but they complain if any of the pathspecs do not match.  It's probably
not worth documenting this, but it may be worth implementing
--ignore-unmatch for all but git-rm (which already has it.)

Similarly, it may be a nice option to have a --warn-unmatch option (or
a configuration variable) to warn (or possibly die) if any of the
pathspecs hit nothing.   Then again, maybe it's not worth the trouble.

It appears that git-diff-tree and git-ls-tree take some sort of
pathspec - it ignores unmatching patterns, but it does not allow
globbing or directory matches.

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

In this case, I suggest that we use the same meta-variable always:
<file> or <dir>, or a more specific thing like <source>.

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

In these cases, I think we should always use the meta-variable
<pathspec> - never <path>, <file>, etc.

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

You're right, it's not worth having two different meta-variables, but
I do think it is worth noting in the documentation.  In git(1), we
could have something like the following:

<pathspec>::
	Indicates a pattern for filtering paths.  Matches are either exact,
	a leading directory, or a glob(7) pattern on the entire path.
	For example, "doc/help.txt" matches "doc/help.txt", "doc",
	"*.txt", and "d*t", but not "do", "help.txt", or "help.*".

<dir>::
<file>::
	Indicates a physical file or directory relative to
	the current directory.

(Note: the current document says "almost always relative to the root
of the tree structure `GIT_INDEX_FILE` describes."  Is this true?)

Then, for the diff logic commands, we could document that they do not
accept globs.  For example, in git-diff(1):

<pathspec>...::
	If given, limit the diff to paths matching the given parameters.
	(Does not accept glob(7) patterns.)

Once the logic is unified, and these commands do accept globs, we can
just remove the note.

Mark