# git-reset man page

6 messages from 2012-11-10 to 2012-11-18. Participants: Angelo Borsotti, Krzysztof Mazur, Junio C Hamano, Drew Northup.
Thread: https://gitlist.dev/t/32052

## Angelo Borsotti, 2012-11-10 09:55

Subject: git-reset man page
Message-ID: <CAB9Jk9AdTBJotrB0fndZawMWH6hS4PW_5bHwecwY5Vz7=TnYAA@mail.gmail.com>
URL: https://gitlist.dev/e/CAB9Jk9AdTBJotrB0fndZawMWH6hS4PW_5bHwecwY5Vz7%3DTnYAA%40mail.gmail.com

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

```

## Krzysztof Mazur, 2012-11-10 15:57

Subject: Re: git-reset man page
Message-ID: <20121110155718.GA29321@shrek.podlesie.net>
URL: https://gitlist.dev/e/20121110155718.GA29321%40shrek.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

```

## Junio C Hamano, 2012-11-10 20:02

Subject: Re: git-reset man page
Message-ID: <7v8va9p6pn.fsf@alter.siamese.dyndns.org>
URL: https://gitlist.dev/e/7v8va9p6pn.fsf%40alter.siamese.dyndns.org
In-Reply-To: <20121110155718.GA29321@shrek.podlesie.net>

```
Krzysztof Mazur <krzysiek@podlesie.net> writes:

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

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.

```

## Krzysztof Mazur, 2012-11-10 20:46

Subject: Re: git-reset man page
Message-ID: <20121110204633.GA29363@shrek.podlesie.net>
URL: https://gitlist.dev/e/20121110204633.GA29363%40shrek.podlesie.net
In-Reply-To: <7v8va9p6pn.fsf@alter.siamese.dyndns.org>

```
On Sat, Nov 10, 2012 at 12:02:12PM -0800, Junio C Hamano wrote:
> Krzysztof Mazur <krzysiek@podlesie.net> writes:
> 
> > 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>.
> 
> We should unify uses of <paths> and <path> (the former should be
> <path>... or something).

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

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

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

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

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

```

## Drew Northup, 2012-11-18 16:55

Subject: Re: git-reset man page
Message-ID: <CAM9Z-nkon5ZtPuqxL0HZPr1es9DSpLA+70++hYpTR4D7WTxbUA@mail.gmail.com>
URL: https://gitlist.dev/e/CAM9Z-nkon5ZtPuqxL0HZPr1es9DSpLA%2B70%2B%2BhYpTR4D7WTxbUA%40mail.gmail.com
In-Reply-To: <20121110204633.GA29363@shrek.podlesie.net>

```
On Sat, Nov 10, 2012 at 3:46 PM, Krzysztof Mazur <krzysiek@podlesie.net> wrote:
> On Sat, Nov 10, 2012 at 12:02:12PM -0800, Junio C Hamano wrote:
>> Krzysztof Mazur <krzysiek@podlesie.net> writes:
>>
>> > 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>.
>>
>> We should unify uses of <paths> and <path> (the former should be
>> <path>... or something).
>
> Currently in most cases "<paths>..." is used ;)

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

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

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

```

## Krzysztof Mazur, 2012-11-18 17:48

Subject: Re: git-reset man page
Message-ID: <20121118174859.GA29052@shrek.podlesie.net>
URL: https://gitlist.dev/e/20121118174859.GA29052%40shrek.podlesie.net
In-Reply-To: <CAM9Z-nkon5ZtPuqxL0HZPr1es9DSpLA+70++hYpTR4D7WTxbUA@mail.gmail.com>

```
On Sun, Nov 18, 2012 at 11:55:09AM -0500, Drew Northup wrote:
> 
> > 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>..."
> 
> 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

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

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

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

```