Meta-variable naming convention in documentation

[Mark Lodato <lodatom@gmail.com>]

Currently, git's documentation and usage statements are inconsistent in
the meta-variables (e.g., <path>) used to described positional arguments
that denote a path.  This post is an attempt to document the existing
issues and to propose a potential solution.

To begin, I ran each of the git sub-commands in git 1.7.0 and documented
its behavior.  Each row contains the program, the meta-variables, and
the type.  If the man page and the '-h' usage statement differ, I list
both.  For example, git-annotate uses "file" in both the man page and
the usage statement, while git-blame uses "<file>" in the man page but
"file" in the usage statement.

The following accept exact filenames.  No directory recursion or
globing is applied.  The first group die if the file does not exist,
while the second group "filters" (f) -- they silently ignore
non-matching files.

	program			man[/usage]		type
	-------			-----------		----
	git-annotate		file			file
	git-blame		<file>/file		file
	git-checkout-index	<file>			file
	git-hash-object		<file>			file
	git-mailsplit		<mbox>|<Maildir>	file
	git-merge-file		<current-file> ...	file
	git-merge-index		<file>/<filename>	file
	git-merge-one-file	<path>			file
	git-mergetool		<file>/file to merge	file
	git-mv			<args>/<source>		file
	git-pack-redundant	.pack filename/<...>	file
	git-send-email		<file>			file
	git-update-index	<file>			file
	git-am			<dir>			dir
	git-clone		<directory>		dir
	git-cvsserver		<directory>		dir
	git-daemon		<directory>		dir
	git-fetch-pack		<directory>		dir
	git-filter-branch	<directory>		dir
	git-format-patch	<dir>			dir
	git-fsck		<dir>			dir
	git-mailsplit		<directory>		dir
	git-peek-remote		<directory>		dir
	git-quiltimport		<dir>			dir
	git-receive-pack	<directory>		dir
	git-relink		<dir>			dir
	git-send-pack		<directory>		dir
	git-submodule		<path>			dir
	git-upload-archive	<directory>		dir
	git-upload-pack		<directory>		dir
	git-bundle		<file>			outfile
	git-mailinfo		<patch>			outfile
	git-pack-objects	base-name		outfile

	git-diff-tree		<path>			file	(f)
	git-ls-tree		paths/path		file	(f)

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)
	git-diff		<path>			fdir	(f)
	git-diff-files		<path>			fdir	(f)
	git-diff-index		<path>			fdir	(f)
	git-difftool		<path>/(nothing)	fdir	(f)
	git-log			<path>			fdir	(f)
	git-reset		<paths>			fdir	(f)
	git-rev-list		<paths>/paths		fdir	(f)
	git-show		(undoc)/<path>		fdir	(f)
	git-whatchanged		(undocumented)		fdir	(f)
	gitk			<path>			fdir	(f)

The following accept recursive directory matches or path globs.

	git-add			<filepattern>		glob
	git-checkout		<paths>/<file>		glob
	git-commit		<file>/<filepattern>	glob
	git-rm			<file>			glob

	git-clean		<path>/<paths>		glob	(f)
	git-grep		<path>/path		glob	(f)
	git-ls-files		<file>			glob	(f)
	git-status	<pathspec>/<filepattern>	glob?	(f)

* git-rm has --ignore-unmatch, which causes it to "filter"
* git-status only accepts globs for untracked files (currently a bug?)

Here are some examples showing what I mean by "type".  (May be useful to
have something like this in the documentation.)

    pattern            file  fdir  glob
    -------            ----  ----  ----
    path/to/base.ext   yes   yes   yes
    path                -    yes   yes
    *xt                 -     -    yes
    p*t                 -     -    yes
    base.ext            -     -     -
    b*                  -     -     -
    to                  -     -     -

>From the above, it appears that there are four major groups:
* 'file' or 'dir'
* 'fdir' (f)
* 'glob'
* 'glob' (f)

(The only exceptions are git-diff-tree, git-ls-tree, and git-archive.)

Therefore, I suggest that we stick to a consistent naming convention for
these four groups, and document them in git(1).  Here's is a proposal,
but I'm not tied to these names.
* <file> for 'file'
* <dir> for 'dir'
* <path> for 'fdir' (f)
* <filepattern> for 'glob'
* <pathspec> for 'glob' (f)

We would have to come up with something for the three exceptions above,
and some commands would benefit from more detailed meta-vars, such as
"<source>... <destination>" for git-mv.

Additionally, it would be nice if all non-filtering commands had
--ignore-unmatch, and all filtering commands had an option to die/warn
if any arguments did not match.  But, this is much more work than
a simple documentation change.

Anyway, what do you think of this proposal?  I am not sure that I have
my partitioning correct, but I would like to see some sort of
consistency in the documentation.  I would be happy to implement
whatever is decided.