Re: [PATCH v3 3/5] git-reset.txt: better docs for '--patch'

[Valentin Haenel <valentin.haenel@gmx.de>]

* Junio C Hamano <gitster@pobox.com> [110505]:
> Valentin Haenel <valentin.haenel@gmx.de> writes:
> 
> > * Include '-p' in the synopsis.
> > * Include a better wording for what 'git reset -p' does.
> >   (interactively unstage hunks)
> > * Include a link to the git-add manpage for a description of the patch-mode.
> 
> Yuck (just a style).

Don't like the bullets? Full sentences are preferable, eh? :)

> 
> > Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
> > Helped-by: Jeff King <peff@peff.net>
> > Mentored-by: Junio C Hamano <gitster@pobox.com>
> > ---
> >  Documentation/git-reset.txt |    7 ++++---
> >  1 files changed, 4 insertions(+), 3 deletions(-)
> >
> > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> > index 8481f9d..b6ed0c7 100644
> > --- a/Documentation/git-reset.txt
> > +++ b/Documentation/git-reset.txt
> > @@ -9,7 +9,7 @@ SYNOPSIS
> >  --------
> >  [verse]
> >  'git reset' [-q] [<commit>] [--] <paths>...
> > -'git reset' --patch [<commit>] [--] [<paths>...]
> > +'git reset' --patch|-p [<commit>] [--] [<paths>...]
> 
> We don't say [--quiet|-q], so I am not sure if we care.  If we do, these
> alternative spellings of the same thing should be marked as alternatives.

I see, git-add and git-stash have them, git-checkout and git-reset
don't...

> > @@ -39,8 +39,9 @@ working tree in one go.
> >  	and <commit> (defaults to HEAD).  The chosen hunks are applied
> >  	in reverse to the index.
> >  +
> > -This means that `git reset -p` is the opposite of `git add -p` (see
> > -linkgit:git-add[1]).
> > +This means that `git reset -p` is the opposite of `git add -p`, i.e.
> > +you can use it to selectively unstage hunks. See the ``Interactive Mode''
> > +section of linkgit:git-add[1] to learn how to operate the `\--patch` mode.
> 
> I would rather say "selectively reset hunks".  The reader should not have
> to learn an alternative terminology to understand what it does, and in
> this particular sentence, "reset a hunk" is just as understandable and
> correct.  After all, you are resetting some hunks but not others to the
> original state specified by the <commit>.  If <commit> happens to be HEAD,
> that may be equivalent to "unstage", but otherwise it is not even a
> correct description.

Will fix and resend.

V-