git-reset man page

Hi

the man page of git-reset, synopsys, does not allow for an argumentless call, and the description does not tell either what is the meaning of it. Suggested changes:

first line of synopsis:

      gitt reset [-q] [<commit>] [ [--] <pathspec> ...]

Description: append to the end of the first paragraph:

     "If no <pathspecs> are specified, all the index entries are reset."

I would suggest to change <paths> with <pathspec> in all the man page because paths in the glossary are called pathspecs.

-Angelo Borsotti

On Sat, Nov 10, 2012 at 10:55:13AM +0100, Angelo Borsotti wrote:

This issue was already reported by Bojan Petrović: http://thread.gmane.org/gmane.comp.version-control.git/208505

and fixed in commit d505865be5c7d72abb74318940e8c4c52aa0db5f (doc: git-reset: make "<mode>" optional) in master branch.

"git reset" is equivalent to "git reset --mixed".

The <paths> issue seems to be bigger - "<path>", "<paths>" and "<pathspec>" are mixed in whole manual:

$ cat Documentation/*.txt | grep -o '<path[^>]*>' | sort | uniq -c |
sort -n -r
    125 <path>
     17 <paths>
     10 <pathspec>
      2 <pathtemplate>
      2 <path-pattern>
      1 <path_to>
      1 <path_from>

In commands it's even worse:
$ cat builtin/*.c | grep -o '<path[^>]*>' | sort | uniq -c | sort -n -r
     14 <path>
     15 <paths>

Note: <path> is not always used for pathspec.

In git-checkout manual in synopsis "<paths>" is used, but in description "<pathspec>".

Maybe we should just add that <paths> is an shortcut for <pathspec> and fix places where paths and pathspec are mixed or <path> is used as <pathspec>.

Thanks,

Krzysiek

Krzysztof Mazur <krzysiek@podlesie.net> writes:

We should unify uses of <paths> and <path> (the former should be <path>... or something).

Some places you need to give exact path (iow, these places you cannot use pathspec), while most other places pathspec (i.e. matching pattern) is accepted.

The manual correctly updated will most likely to use both <path> and <pathspec> appropriately.

On Sat, Nov 10, 2012 at 12:02:12PM -0800, Junio C Hamano wrote:

Currently in most cases "<paths>..." is used ;)

I know, thats why I added a note that "<path> is not always used for pathspec".

So we should always use "<path>" for exact path, and "<pathspec>" for pathspecs patterns as defined in gitglossary. I think it's better to avoid "<paths>" and always use "<path>..." or "<pathspec>...".

Krzysiek

On Sat, Nov 10, 2012 at 3:46 PM, Krzysztof Mazur <krzysiek@podlesie.net> wrote:

I suspect that the only reason why the differentiation between "<path>" and "<paths>" happened is because there may be some places where it was seen that a _list of paths_ was acceptable (which isn't a pathspec, as it isn't a search expression) and other places where _only_ a single path was acceptable. Should that fail to be the case then there would be a good argument for changing the affected instances of "<paths>" to "<path>" in the documentation. (I know of no other good way to pluralize "<path>" myself.)

On Sun, Nov 18, 2012 at 11:55:09AM -0500, Drew Northup wrote:

<paths> is usually used for a list of <pathspec>, not just a list of <path>.

I think it's best to just add "...":

<path> for single exact path, <path>... for a list of exact paths, <pathspec> for single pathspec, <pathspec>... for a list of pathspecs.

Krzysiek