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

Valentin Haenel [off-list ref] 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).

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

* Junio C Hamano [off-list ref] [110505]:

Valentin Haenel [off-list ref] writes:

quoted

* 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? :)

quoted

Signed-off-by: Valentin Haenel <redacted>
Helped-by: Jeff King [off-list ref]
Mentored-by: Junio C Hamano [off-list ref]
---
 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...

quoted

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

Describe '-p' as a short form of '--patch' in synopsis. Also include a better
explanation of this option and additionally refer the reader to the patch mode
description of git-add documentation.

Helped-by: Jeff King [off-list ref]
Mentored-by: Junio C Hamano [off-list ref]
Signed-off-by: Valentin Haenel <redacted>
---

Reworded the option description, turned the bullet points in the commit-message
into proper sentences, and fixed the sign-off-chain. Sending only patch 3/5 of
v4 since the others have already been queued.

 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..82001f2 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>...]
 'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>]
 
 DESCRIPTION

@@ -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 reset hunks. See the ``Interactive Mode''
+section of linkgit:git-add[1] to learn how to operate the `\--patch` mode.
 
 'git reset' [--<mode>] [<commit>]::
 	This form resets the current branch head to <commit> and

-- 
1.7.1