From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 05 May 2011 19:22:15 GMT
Subject: Re: [PATCH v3 3/5] git-reset.txt: better docs for '--patch'
Message-ID: <7v7ha56jh4.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1304621328-17184-3-git-send-email-valentin.haenel@gmx.de>

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

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

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