* git-reset man page
@ 2012-11-10 9:55 Angelo Borsotti
2012-11-10 15:57 ` Krzysztof Mazur
0 siblings, 1 reply; 6+ messages in thread
From: Angelo Borsotti @ 2012-11-10 9:55 UTC (permalink / raw)
To: git
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
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: git-reset man page
2012-11-10 9:55 git-reset man page Angelo Borsotti
@ 2012-11-10 15:57 ` Krzysztof Mazur
2012-11-10 20:02 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Krzysztof Mazur @ 2012-11-10 15:57 UTC (permalink / raw)
To: Angelo Borsotti; +Cc: git, peff
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
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: git-reset man page
2012-11-10 15:57 ` Krzysztof Mazur
@ 2012-11-10 20:02 ` Junio C Hamano
2012-11-10 20:46 ` Krzysztof Mazur
0 siblings, 1 reply; 6+ messages in thread
From: Junio C Hamano @ 2012-11-10 20:02 UTC (permalink / raw)
To: Krzysztof Mazur; +Cc: Angelo Borsotti, git, peff
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: git-reset man page
2012-11-10 20:02 ` Junio C Hamano
@ 2012-11-10 20:46 ` Krzysztof Mazur
2012-11-18 16:55 ` Drew Northup
0 siblings, 1 reply; 6+ messages in thread
From: Krzysztof Mazur @ 2012-11-10 20:46 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Angelo Borsotti, git, peff
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: git-reset man page
2012-11-10 20:46 ` Krzysztof Mazur
@ 2012-11-18 16:55 ` Drew Northup
2012-11-18 17:48 ` Krzysztof Mazur
0 siblings, 1 reply; 6+ messages in thread
From: Drew Northup @ 2012-11-18 16:55 UTC (permalink / raw)
To: Krzysztof Mazur, Angelo Borsotti; +Cc: Junio C Hamano, git, peff
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: git-reset man page
2012-11-18 16:55 ` Drew Northup
@ 2012-11-18 17:48 ` Krzysztof Mazur
0 siblings, 0 replies; 6+ messages in thread
From: Krzysztof Mazur @ 2012-11-18 17:48 UTC (permalink / raw)
To: Drew Northup; +Cc: Angelo Borsotti, Junio C Hamano, git, peff
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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2012-11-18 17:49 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-11-10 9:55 git-reset man page Angelo Borsotti
2012-11-10 15:57 ` Krzysztof Mazur
2012-11-10 20:02 ` Junio C Hamano
2012-11-10 20:46 ` Krzysztof Mazur
2012-11-18 16:55 ` Drew Northup
2012-11-18 17:48 ` Krzysztof Mazur
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).