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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html