From: Krzysztof Mazur <krzysiek@podlesie.net>
Date: Sat, 10 Nov 2012 15:57:18 GMT
Subject: Re: git-reset man page
Message-ID: <20121110155718.GA29321@shrek.podlesie.net>
In-Reply-To: <CAB9Jk9AdTBJotrB0fndZawMWH6hS4PW_5bHwecwY5Vz7=TnYAA@mail.gmail.com>

On Sat, Nov 10, 2012 at 10:55:13AM +0100, Angelo Borsotti wrote:
> 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.

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

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

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