Someone mentioned that there were other places where <path> should be
<pathspec> and I looked through the docs a bit to see, and also noted
simple completion fixes.
There were a number of small issues I saw that I'll fix if there's
interest but I want to ask before spending time (I have a few patches
submitted at the moment and can't tell if they are unwelcome or what).
To give an idea what I have in mind the rough notes I made on a first
pass through are below. Note that I haven't got as far as verifying
for sure e.g. what actually takes a pathspec so there may be mistakes
in here.
The question now is is there enough interest that I should proceed or not?
Here's the list:
git-am:
doc: --exclude and --include probably take <pathspec>, but currently refer
to <path>. Note: Underlying git-apply currently says <path-pattern> in
detailed description, <path> in synopsis
doc: --directory=<dir> in synopsis and detailed description but should
probably be <root> since the detailed description in git-am just says
that "These flags are passed to the git apply"
comp: --directory= takes and should complete a dir
git-archive:
doc: is <path> argument really a <path> or should it be <pathspec>?
git-bisect:
doc: mentions of path in main text should be <pathspec> (assuming
guy on mailing list who said it actually takes a <pathspec> was right,
check)
git-clone:
doc: <directory> or <dir>? who cares I think but elsewhere some use <dir>
<dir>
comp: <directory> should be completed
comp: <git-dir> should be completed
git-describe:
doc: synopsis mentions <blob> but later text just mentions blob, I think this
is not how other tools mention such things
git-diff:
doc: are all the mentions of <path> really <path> or should they be
<pathspec>?
doc: is optional arg to --relative really a <path>, or is it a <pathspec>?
comp: there are lots of options that aren't completed that should be
comp: NOTE: <path> should not get completed as dir even if they aren't
<pathspec> since they might be files
comp: NOTE: the optional arg to --relative should not be completed as an
actual dir
git-format-patch:
doc: is optional arg to --relative really a <path>, or is it a <pathspec>?
doc: what is <boundary>?
doc: --from in main text but not synopsis
comp: --to --cc --from don't have optarg completion help for format-patch
as they do for send-email. I notice that according to it's
--git-completion-helper output format-patch doesn't implement --bcc
hmnm is that really true so weird
comp: NOTE: the optional arg to --relative should not be completed as an
actual dir
git-init:
doc: has both [--template=<template-directory>] and
[--separate-git-dir <git-dir>], I see no reason one of these should get
an = and the other not, seems like both should get = and that's how this
command does it though other git commands seem to doc differently
doc: <directory> is mentioned in synopsis but only underlined directory in
body. elsewhere in same file words like this do get their <> and are
underlined also. what is the
actual git way for this? Just underline? Underline and <> (seems
right to me?) Underline seems to be the common utility way (for ls, cp,
ln at least which I checked, but those don't use <> everywhere. I
guess I sort of think it should be one or the other not both and git
uses <> everywhere for args and optargs. FIXME: sheesh I can't quit
tell when bold is even getting used in my terminal font it's similar
enough but actuall bold and <> seems pretty common as well
comp: arg to --template should be completed as a dir
comp: arg to --separate-git-dir should be completed as a dir
comp: the optional [<directory>] arg appears to be the only possible
non-option argument and so should be easy to complete as a dir
git-log:
doc: synopsis says <path>... probably it means <pathspec>... check
doc: full text also mentions <paths> in a number of places, it should
probably by <pathspec>... but at least <path>... (or sometimes just
<pathspec> or <path>)
doc: is optional arg to --relative really a <path>, or is it a <pathspec>?
comp: NOTE: the optional arg to --relative should not be completed as an
actual dir
git-pull:
doc: one option description reads '--squash, --no-squash' while another reads
'--[no-]verify'. I think I like the first way better for easy search
but I think the second might be more common. Find out the preferred
way and make consistent.
git-range-diff:
doc: refers to <path> where it likely means pathspec. highlights <path>
but doesn't underline
git-reset:
doc: says 'can copy the contents of a path out of a commit' I believe it
really means 'contents of a pathspec' but that's so clunky to read
and understand and so much less likely to be what someone is attempting
if they're doing the already somewhat exatic thing described that it's
probably better to just keep on being wrong here.
git-shortlog:
doc: refers to <path> but should probably be <pathspec>
doc: is optional arg to --relative really a <path>, or is it a <pathspec>?
comp: NOTE: the optional arg to --relative should not be completed as an
actual dir
doc: mentions <paths> in one place ('as the <paths>' should be 'as a <path>')
refers to <path> but should probably be <pathspec>
git-submodule:
doc: <path> all over the place but then the text mentions <pathspec> in one
place that looks representative so probably they should all be
<pathspec>
doc: describes <path> (an optional argument) under options
git-worktree:
doc: NOTE: I don't think these should be doced as <pathspec> regardless of
what the actual code takes. Out of curiosity what does actual code
take?
comp: repair subcommand: <path> should be completed to a real dir in this
case
gitk:
doc: says <path> probably means <pathspec>
git-config:
doc: <file-option> appears in synopsis but isn't mentioned in text
git-reflog:
doc: takes <log-options>, argubly should be <log-option>...
git-repack:
comp: --expire-to=<dir> should complete dirs
comp: --filter-to=<dir> should complete dirs
git-bugreport:
doc: in general (not just for this command) should opts that need a path
that's a dir always call it <dir> rather than <path>?
comp: completion needs implemented
comp: -o/--ouput-directory should complete dirs
git-diagnose:
comp: completion needs implemented
comp: -o/--ouput-directory should complete dirs
git-difftool:
comp: there are lots of options that need completion added for underlying
git-diff. For some reason git difftool --git-completion-help doesn't
pull in the git-diff options (unlike send-email does format-patch
options) perhaps this could be fixed?. Or the git-diff options could
be factored into a function so they can be used for both _git_diff
and _git_difftool
git-merge-tree:
doc: --stdin appears pretty significant, but doesn't have an entry of it's
own in the OPTIONS section
comp: not implemented at all yet
git-archimport:
comp: not implemented, probably not worth it
git-cvsexportcommit:
comp: not implemented, probably not worth it
git-cvsserver:
comp: not implemented, probably not worth it
git-quiltimport:
doc: --patches=<dir> might be better than --patches <dir>, how to handle this
in general?
comp: not implemented yet
comp: --patches should complete dirs
git-send-email:
doc: send-email docs --to --from --cc with different docs than the
corresponding format-patch options. Are they not just passed through in
the case where format-patch is being done implicitly? Do they override
for an already-prepared patch series? Hmm
comp: all long opts of send-email and format-patch are accepted via
the --git-completion-helper mechanism. Unfortunately this means all
git-format-patch opts are accepted even when --no-format-patch has been
given. Both commands support --git-completion-helper so in theory
the wrong option set could be filtered back out. It's not possible
to do this from the arg since it probably isn't there yet and might
be ambiguous anyway
* there are at least some opts for which optargs aren't completed:
comp: should --reply-to be completed like --to=*|--cc=*|--bcc=*|--from=* are?
comp: should --envelope-sender be completed like
--to=*|--cc=*|--bcc=*|--from=* are?
comp: optarg to --smtp-encryption could be completed
comp: optarg to --transfer-encoding could be be completed
comp: optarg to --smtp-debug could be be completed
