[PATCH] config.txt: interactive.singlekey is used by...

[PATCH] config.txt: interactive.singlekey is used by...

[Valentin Haenel]

The config variable 'interactive.singlekey' influences also '--patch' mode of
git-stash and git-reset.

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
---

Perhaps this incredibly useful setting should also be mentioned in manpages of
git-{add,reset.stash}?

Are git-{add,reset.stash} the only commands that the setting influences?

---
 Documentation/config.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 480dd0a..7dd9b01 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1297,7 +1297,8 @@ interactive.singlekey::
 	In interactive commands, allow the user to provide one-letter
 	input with a single key (i.e., without hitting enter).
 	Currently this is used only by the `\--patch` mode of
-	linkgit:git-add[1].  Note that this setting is silently
+	linkgit:git-add[1], linkgit:git-reset[1] and linkgit:git-stash[1].
+	Note that this setting is silently
 	ignored if portable keystroke input is not available.
 
 log.date::
-- 
1.7.1

Re: [PATCH] config.txt: interactive.singlekey is used by...

[Jeff King]

On Sat, Apr 30, 2011 at 04:54:01PM +0200, Valentin Haenel wrote:

> Perhaps this incredibly useful setting should also be mentioned in manpages of
> git-{add,reset.stash}?

Yeah, that would probably make sense.

> Are git-{add,reset.stash} the only commands that the setting influences?

git-checkout also has a "-p" mode.

-Peff

[PATCH v2 0/5] better document 'interactive.singlekey'

[Valentin Haenel]

The configuration 'interactive.singlekey' is incredibly useful but
underdocumentated. Bring the documentation in config.txt up-to-date and
document it in individual commands.

Thanks to Jeff King for advice.

Valentin Haenel (5):
  config.txt: 'interactive.singlekey; is used by...
  git-add.txt: document 'interactive.singlekey'
  git-reset.txt: document 'interactive.singlekey'
  git-stash.txt: document 'interactive.singlekey'
  git-checkout.txt: document 'interactive.singlekey'

 Documentation/config.txt       |    5 +++--
 Documentation/git-add.txt      |    3 +++
 Documentation/git-checkout.txt |    3 +++
 Documentation/git-reset.txt    |    3 +++
 Documentation/git-stash.txt    |    3 +++
 5 files changed, 15 insertions(+), 2 deletions(-)

[PATCH v2 1/5] config.txt: 'interactive.singlekey; is used by...

[Valentin Haenel]

The config variable 'interactive.singlekey' influences also '--patch' mode of
git-add, git-reset, and git-checkout.

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Helped-by: Jeff King <peff@peff.net>
---
 Documentation/config.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 480dd0a..77e4f30 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1296,8 +1296,9 @@ instaweb.port::
 interactive.singlekey::
 	In interactive commands, allow the user to provide one-letter
 	input with a single key (i.e., without hitting enter).
-	Currently this is used only by the `\--patch` mode of
-	linkgit:git-add[1].  Note that this setting is silently
+	Currently this is used by the `\--patch` mode of
+	linkgit:git-add[1], linkgit:git-reset[1], linkgit:git-stash[1] and
+	linkgit:git-checkout[1]. Note that this setting is silently
 	ignored if portable keystroke input is not available.
 
 log.date::
-- 
1.7.1

[PATCH v2 2/5] git-add.txt: document 'interactive.singlekey'

[Valentin Haenel]

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Helped-by: Jeff King <peff@peff.net>
---
 Documentation/git-add.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 7eebbef..c172989 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -86,6 +86,9 @@ OPTIONS
 This effectively runs `add --interactive`, but bypasses the
 initial command menu and directly jumps to the `patch` subcommand.
 See ``Interactive mode'' for details.
++
+The configuration `interactive.singlekey` allows the user to provide
+one-letter input with a single key in this mode (i.e., without hitting enter).
 
 -e, \--edit::
 	Open the diff vs. the index in an editor and let the user
-- 
1.7.1

Re: [PATCH v2 2/5] git-add.txt: document 'interactive.singlekey'

[Junio C Hamano]

Valentin Haenel <valentin.haenel@gmx.de> writes:

> Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
> Helped-by: Jeff King <peff@peff.net>
> ---
>  Documentation/git-add.txt |    3 +++
>  1 files changed, 3 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index 7eebbef..c172989 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -86,6 +86,9 @@ OPTIONS
>  This effectively runs `add --interactive`, but bypasses the
>  initial command menu and directly jumps to the `patch` subcommand.
>  See ``Interactive mode'' for details.
> ++
> +The configuration `interactive.singlekey` allows the user to provide
> +one-letter input with a single key in this mode (i.e., without hitting enter).

I do not think this belongs here.  For one thing, as the text in the
pre-context in your patch says, this also applies to "-i".  Since they
both refer to the "Interactive mode" section for further details, I think
that would be more appropriate place to mention the variable, which after
all is a tiny part of the detail (think: if somebody does not know how to
operate the interactive mode, "singlekey does not require enter" is not
very helpful).

Not all the configuration variables "git-add" pays attention to are
mentioned in this manual page (e.g. color.interactive.<slot> and
add.ignoreerrors are not mentioned).  I also do not think duplicating
everything "git add" pays attention to in this manual page is necessarily
a good thing.  I'd prefer to mention only the important ones (e.g. the
ones that give default values for their corresponding command line
options) in the main part of the documentation.

For the other commands that internally invoke "add -p", the text before
your patch is unhelpful to people who have not seen "git add -p" in
action.  Some of them do not even mention where the interactive mode is
explained.  The result of your patch does not help the situation, and
abruptly start talking about interactive.singlekey, still without teaching
how to operate the interactive mode at all.

I think the end result of the series should look something like this patch,
after applying your [PATCH 1/5], but discarding 2 thru 5.


 Documentation/git-add.txt      |    5 ++++-
 Documentation/git-checkout.txt |    4 +++-
 Documentation/git-reset.txt    |    4 +++-
 Documentation/git-stash.txt    |    4 +++-
 4 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 7eebbef..27e0160 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -134,6 +134,8 @@ subdirectories.
 	If some files could not be added because of errors indexing
 	them, do not abort the operation, but continue adding the
 	others. The command shall still exit with non-zero status.
+	The configuration variable `add.ignoreErrors` can be set to
+	true to make this the default behaviour.
 
 --ignore-missing::
 	This option can only be used together with --dry-run. By using
@@ -189,7 +191,8 @@ interactive command loop.
 The command loop shows the list of subcommands available, and
 gives a prompt "What now> ".  In general, when the prompt ends
 with a single '>', you can pick only one of the choices given
-and type return, like this:
+and type return (the configuration variable `interactive.singlekey`
+can be set to true to omit hitting return, by the way), like this:
 
 ------------
     *** Commands ***
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 1063f69..7c58028 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -179,7 +179,9 @@ the conflicted merge in the specified paths.
 --patch::
 	Interactively select hunks in the difference between the
 	<tree-ish> (or the index, if unspecified) and the working
-	tree.  The chosen hunks are then applied in reverse to the
+	tree (see the ``Interactive Mode`` section of gitlink:git-add[1]
+	to learn how to operate the interactive mode).  The chosen
+	hunks are then applied in reverse to the
 	working tree (and if a <tree-ish> was specified, the index).
 +
 This means that you can use `git checkout -p` to selectively discard
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 8481f9d..37f487e 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -36,7 +36,9 @@ working tree in one go.
 
 'git reset' --patch|-p [<commit>] [--] [<paths>...]::
 	Interactively select hunks in the difference between the index
-	and <commit> (defaults to HEAD).  The chosen hunks are applied
+	and <commit> (see the ``Interactive Mode``
+	section of gitlink:git-add[1] to learn how to operate the interactive
+	mode).  Missing <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
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 79abc38..281bd35 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -55,7 +55,9 @@ If the `--keep-index` option is used, all changes already added to the
 index are left intact.
 +
 With `--patch`, you can interactively select hunks from in the diff
-between HEAD and the working tree to be stashed.  The stash entry is
+between HEAD and the working tree to be stashed (see the ``Interactive Mode``
+section of gitlink:git-add[1] to learn how to operate the interactive
+mode).  The stash entry is
 constructed such that its index state is the same as the index state
 of your repository, and its worktree contains only the changes you
 selected interactively.  The selected changes are then rolled back

Re: [PATCH v2 2/5] git-add.txt: document 'interactive.singlekey'

[Valentin Haenel]

Hi,

thanks for the feedback. I have some remaining questions, see below.

* Junio C Hamano <gitster@pobox.com> [110502]:
> Valentin Haenel <valentin.haenel@gmx.de> writes:
> 
> > Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
> > Helped-by: Jeff King <peff@peff.net>
> > ---
> >  Documentation/git-add.txt |    3 +++
> >  1 files changed, 3 insertions(+), 0 deletions(-)
> >
> > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> > index 7eebbef..c172989 100644
> > --- a/Documentation/git-add.txt
> > +++ b/Documentation/git-add.txt
> > @@ -86,6 +86,9 @@ OPTIONS
> >  This effectively runs `add --interactive`, but bypasses the
> >  initial command menu and directly jumps to the `patch` subcommand.
> >  See ``Interactive mode'' for details.
> > ++
> > +The configuration `interactive.singlekey` allows the user to provide
> > +one-letter input with a single key in this mode (i.e., without hitting enter).
> 
> I do not think this belongs here.  For one thing, as the text in the
> pre-context in your patch says, this also applies to "-i".  Since they
> both refer to the "Interactive mode" section for further details, I think
> that would be more appropriate place to mention the variable, which after
> all is a tiny part of the detail (think: if somebody does not know how to
> operate the interactive mode, "singlekey does not require enter" is not
> very helpful).

I agree that details should go into the section "Interactive Mode". 

However, it would seem that the configuration influences only the
patch mode of the interactive mode (unless i am missing something).
I just tried to naviagte the menu i get with 'git add -i' and typing the
enter was required. (Using 1.7.5) This would affect the positioning of
the addition, see below.

> Not all the configuration variables "git-add" pays attention to are
> mentioned in this manual page (e.g. color.interactive.<slot> and
> add.ignoreerrors are not mentioned).  I also do not think duplicating
> everything "git add" pays attention to in this manual page is necessarily
> a good thing.  I'd prefer to mention only the important ones (e.g. the
> ones that give default values for their corresponding command line
> options) in the main part of the documentation.
> 
> For the other commands that internally invoke "add -p", the text before
> your patch is unhelpful to people who have not seen "git add -p" in
> action.  Some of them do not even mention where the interactive mode is
> explained.  The result of your patch does not help the situation, and
> abruptly start talking about interactive.singlekey, still without teaching
> how to operate the interactive mode at all.

Yeah, I agree.

> I think the end result of the series should look something like this patch,
> after applying your [PATCH 1/5], but discarding 2 thru 5.
> 
> 
>  Documentation/git-add.txt      |    5 ++++-
>  Documentation/git-checkout.txt |    4 +++-
>  Documentation/git-reset.txt    |    4 +++-
>  Documentation/git-stash.txt    |    4 +++-
>  4 files changed, 13 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index 7eebbef..27e0160 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -134,6 +134,8 @@ subdirectories.
>  	If some files could not be added because of errors indexing
>  	them, do not abort the operation, but continue adding the
>  	others. The command shall still exit with non-zero status.
> +	The configuration variable `add.ignoreErrors` can be set to
> +	true to make this the default behaviour.

Its unrelated to 'interactive.singlekey', can i 'stuff' it into the
series too, or better make a seperate one?

>  
>  --ignore-missing::
>  	This option can only be used together with --dry-run. By using
> @@ -189,7 +191,8 @@ interactive command loop.
>  The command loop shows the list of subcommands available, and
>  gives a prompt "What now> ".  In general, when the prompt ends
>  with a single '>', you can pick only one of the choices given
> -and type return, like this:
> +and type return (the configuration variable `interactive.singlekey`
> +can be set to true to omit hitting return, by the way), like this:

If what i wrote above is correct, this should go into the section about
the patch mode, rather than here?

>  ------------
>      *** Commands ***
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index 1063f69..7c58028 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -179,7 +179,9 @@ the conflicted merge in the specified paths.
>  --patch::
>  	Interactively select hunks in the difference between the
>  	<tree-ish> (or the index, if unspecified) and the working
> -	tree.  The chosen hunks are then applied in reverse to the
> +	tree (see the ``Interactive Mode`` section of gitlink:git-add[1]
> +	to learn how to operate the interactive mode).  The chosen
> +	hunks are then applied in reverse to the
>  	working tree (and if a <tree-ish> was specified, the index).
>  +
>  This means that you can use `git checkout -p` to selectively discard
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index 8481f9d..37f487e 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -36,7 +36,9 @@ working tree in one go.
>  
>  'git reset' --patch|-p [<commit>] [--] [<paths>...]::
>  	Interactively select hunks in the difference between the index
> -	and <commit> (defaults to HEAD).  The chosen hunks are applied
> +	and <commit> (see the ``Interactive Mode``
> +	section of gitlink:git-add[1] to learn how to operate the interactive
> +	mode).  Missing <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
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 79abc38..281bd35 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -55,7 +55,9 @@ If the `--keep-index` option is used, all changes already added to the
>  index are left intact.
>  +
>  With `--patch`, you can interactively select hunks from in the diff
> -between HEAD and the working tree to be stashed.  The stash entry is
> +between HEAD and the working tree to be stashed (see the ``Interactive Mode``
> +section of gitlink:git-add[1] to learn how to operate the interactive
> +mode).  The stash entry is
>  constructed such that its index state is the same as the index state
>  of your repository, and its worktree contains only the changes you
>  selected interactively.  The selected changes are then rolled back

Re: [PATCH v2 2/5] git-add.txt: document 'interactive.singlekey'

[Junio C Hamano]

Valentin Haenel <valentin.haenel@gmx.de> writes:

>>  	If some files could not be added because of errors indexing
>>  	them, do not abort the operation, but continue adding the
>>  	others. The command shall still exit with non-zero status.
>> +	The configuration variable `add.ignoreErrors` can be set to
>> +	true to make this the default behaviour.
>
> Its unrelated to 'interactive.singlekey', can i 'stuff' it into the
> series too, or better make a seperate one?

Yes, this is totally unrelated; I just wanted to write it down so somebody
remembers.  Please make it a separate patch that comes before anything
else.

>> @@ -189,7 +191,8 @@ interactive command loop.
>>  The command loop shows the list of subcommands available, and
>>  gives a prompt "What now> ".  In general, when the prompt ends
>>  with a single '>', you can pick only one of the choices given
>> -and type return, like this:
>> +and type return (the configuration variable `interactive.singlekey`
>> +can be set to true to omit hitting return, by the way), like this:
>
> If what i wrote above is correct, this should go into the section about
> the patch mode, rather than here?

Yes, please move find a more appropriate home for that description.

Thanks.

[PATCH] git-add.txt: document 'add.ignoreErrors'

[Valentin Haenel]

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Noticed-by: Junio C Hamano <gitster@pobox.com>
---

* Junio C Hamano <gitster@pobox.com> [110503]:
> Valentin Haenel <valentin.haenel@gmx.de> writes:
> >>  	If some files could not be added because of errors indexing
> >>  	them, do not abort the operation, but continue adding the
> >>  	others. The command shall still exit with non-zero status.
> >> +	The configuration variable `add.ignoreErrors` can be set to
> >> +	true to make this the default behaviour.
> >
> > Its unrelated to 'interactive.singlekey', can i 'stuff' it into the
> > series too, or better make a seperate one?
> 
> Yes, this is totally unrelated; I just wanted to write it down so somebody
> remembers.  Please make it a separate patch that comes before anything
> else.

here you go.

 Documentation/git-add.txt |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 7eebbef..35cb5d3 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -134,6 +134,8 @@ subdirectories.
 	If some files could not be added because of errors indexing
 	them, do not abort the operation, but continue adding the
 	others. The command shall still exit with non-zero status.
+	The configuration variable `add.ignoreErrors` can be set to
+	true to make this the default behaviour.
 
 --ignore-missing::
 	This option can only be used together with --dry-run. By using
-- 
1.7.1

[PATCH v3 0/5] better document 'interactive.singlekey' and '--patch'

[Valentin Haenel]

This is round 3 of this series. Now improves the documentation of
'--patch' in various manpages in addition to better documenting
'interactive.singlekey' in config.txt and git-add.txt.

First patch brings the documentation in config.txt up-to-date. The
second patch documents the configuration in git-add manpage. The last
three patches improve the documentation for '--patch' in manpages of
git-checkout, git-reset and git-stash. Updating the synopsis in each
one, adding a link to the git-add manpage where the interactive
'--patch'-mode & 'interactive.singlekey' are described, and improving
the description for that option.

Note that the first patch is already included in pu (93556471), but I
included it here again since its part of the series. Is that the right
thing to do, or could I have dropped it?

Thanks to Peff and Junio for comments and advice.

V-

Valentin Haenel (5):
  config.txt: 'interactive.singlekey; is used by...
  git-add.txt: document 'interactive.singlekey'
  git-reset.txt: better docs for '--patch'
  git-stash.txt: better docs for '--patch'
  git-checkout.txt: better docs for '--patch'

 Documentation/config.txt       |    5 +++--
 Documentation/git-add.txt      |    6 +++++-
 Documentation/git-checkout.txt |    7 ++++---
 Documentation/git-reset.txt    |    7 ++++---
 Documentation/git-stash.txt    |    9 +++++----
 5 files changed, 21 insertions(+), 13 deletions(-)

[PATCH v3 1/5] config.txt: 'interactive.singlekey; is used by...

[Valentin Haenel]

The config variable 'interactive.singlekey' influences also '--patch' mode of
git-add, git-reset, and git-checkout.

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Helped-by: Jeff King <peff@peff.net>
---
 Documentation/config.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 480dd0a..77e4f30 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1296,8 +1296,9 @@ instaweb.port::
 interactive.singlekey::
 	In interactive commands, allow the user to provide one-letter
 	input with a single key (i.e., without hitting enter).
-	Currently this is used only by the `\--patch` mode of
-	linkgit:git-add[1].  Note that this setting is silently
+	Currently this is used by the `\--patch` mode of
+	linkgit:git-add[1], linkgit:git-reset[1], linkgit:git-stash[1] and
+	linkgit:git-checkout[1]. Note that this setting is silently
 	ignored if portable keystroke input is not available.
 
 log.date::
-- 
1.7.1

[PATCH v3 2/5] git-add.txt: document 'interactive.singlekey'

[Valentin Haenel]

This is documented in the section about the 'Interactive Mode', rather than for
the option '--patch', since this is the section is where people go to learn
about '--patch'.

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-add.txt |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 35cb5d3..9c1d395 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -274,7 +274,8 @@ patch::
   This lets you choose one path out of a 'status' like selection.
   After choosing the path, it presents the diff between the index
   and the working tree file and asks you if you want to stage
-  the change of each hunk.  You can say:
+  the change of each hunk.  You can select one of the following
+  options and type return:
 
        y - stage this hunk
        n - do not stage this hunk
@@ -293,6 +294,9 @@ patch::
 +
 After deciding the fate for all hunks, if there is any hunk
 that was chosen, the index is updated with the selected hunks.
++
+You can omit having to type return here, by setting the configuration
+variable `interactive.singlekey` to `true`.
 
 diff::
 
-- 
1.7.1

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

[Valentin Haenel]

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

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>...]
 '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 unstage 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

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

[Junio C Hamano]

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.

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

[Valentin Haenel]

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

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

[Valentin Haenel]

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 <peff@peff.net>
Mentored-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
---

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

[PATCH v3 4/5] git-stash.txt: better docs for '--patch'

[Valentin Haenel]

* Include '-p' in synopsis and options.
* Fix a typo.
* Include a link to the git-add manpage for a description of the patch-mode.

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-stash.txt |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 79abc38..15f051f 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 'git stash' drop [-q|--quiet] [<stash>]
 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
 'git stash' branch <branchname> [<stash>]
-'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] [<message>]]
+'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [<message>]]
 'git stash' clear
 'git stash' create
 
@@ -42,7 +42,7 @@ is also possible).
 OPTIONS
 -------
 
-save [--patch] [--[no-]keep-index] [-q|--quiet] [<message>]::
+save [-p|--patch] [--[no-]keep-index] [-q|--quiet] [<message>]::
 
 	Save your local modifications to a new 'stash', and run `git reset
 	--hard` to revert them.  The <message> part is optional and gives
@@ -54,12 +54,13 @@ save [--patch] [--[no-]keep-index] [-q|--quiet] [<message>]::
 If the `--keep-index` option is used, all changes already added to the
 index are left intact.
 +
-With `--patch`, you can interactively select hunks from in the diff
+With `--patch`, you can interactively select hunks from the diff
 between HEAD and the working tree to be stashed.  The stash entry is
 constructed such that its index state is the same as the index state
 of your repository, and its worktree contains only the changes you
 selected interactively.  The selected changes are then rolled back
-from your worktree.
+from your worktree. See the ``Interactive Mode'' section of
+linkgit:git-add[1] to learn how to operate the `\--patch` mode.
 +
 The `--patch` option implies `--keep-index`.  You can use
 `--no-keep-index` to override this.
-- 
1.7.1

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

[Valentin Haenel]

* Include '-p' in synopsis and options
* Include a link to the git-add manpage for a description of the patch-mode.

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-checkout.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 1063f69..9d53582 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
-'git checkout' --patch [<tree-ish>] [--] [<paths>...]
+'git checkout' -p|--patch [<tree-ish>] [--] [<paths>...]
 
 DESCRIPTION
 -----------
@@ -45,7 +45,7 @@ $ git checkout <branch>
 that is to say, the branch is not reset/created unless "git checkout" is
 successful.
 
-'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::
+'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 
 	When <paths> or `--patch` are given, 'git checkout' does *not*
 	switch branches.  It updates the named paths in the working tree
@@ -183,7 +183,8 @@ the conflicted merge in the specified paths.
 	working tree (and if a <tree-ish> was specified, the index).
 +
 This means that you can use `git checkout -p` to selectively discard
-edits from your current working tree.
+edits from your current working tree. See the ``Interactive Mode''
+section of linkgit:git-add[1] to learn how to operate the `\--patch` mode.
 
 <branch>::
 	Branch to checkout; if it refers to a branch (i.e., a name that,
-- 
1.7.1

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

[Junio C Hamano]

Valentin Haenel <valentin.haenel@gmx.de> writes:

> * Include '-p' in synopsis and options
> * Include a link to the git-add manpage for a description of the patch-mode.
>
> Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
> Helped-by: Jeff King <peff@peff.net>
> Mentored-by: Junio C Hamano <gitster@pobox.com>
> ---

The order of the sign-off chain is not right (I've fixed them up so this
is not a reason for resending).  After getting somebody's help, the final
version was made by you, so listing them this way

    Helped-by: Jeff King <peff@peff.net>
    Mentored-by: Junio C Hamano <gitster@pobox.com>
    Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>

would reflect the order of events better.

FYI, this patch has become like this:

    Author: Valentin Haenel <valentin.haenel@gmx.de>
    Date:   Thu May 5 20:48:48 2011 +0200

    git-checkout.txt: better docs for '--patch'
    
    Describe '-p' as a short form of '--patch' in synopsis and options.  Also
    refer the reader to the patch mode description of git-add documentation.
    
    Helped-by: Jeff King <peff@peff.net>
    Mentored-by: Junio C Hamano <gitster@pobox.com>
    Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Will queue 1, 2, 4, and 5 with similar fix-ups.

Thanks.

Re: [PATCH v3 0/5] better document 'interactive.singlekey' and '--patch'

[Junio C Hamano]

Valentin Haenel <valentin.haenel@gmx.de> writes:

> Note that the first patch is already included in pu (93556471), but I
> included it here again since its part of the series. Is that the right
> thing to do, or could I have dropped it?

To me it does not make much of a difference either way.

I usually try to apply a rerolled series at the same fork point as the
previous round, and discard the earlier ones after verifying if they are
identical between the two rounds (both trees and log message wording).  It
becomes irritating when the changes I find in this process only reverts
what I fixed-up when I queued the previous round, but on the other hand,
a complete re-send will give the patch a new chance to be reviewed by
different people, so...

[PATCH v2 3/5] git-reset.txt: document 'interactive.singlekey'

[Valentin Haenel]

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Helped-by: Jeff King <peff@peff.net>
---
 Documentation/git-reset.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 8481f9d..9f073d3 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -41,6 +41,9 @@ working tree in one go.
 +
 This means that `git reset -p` is the opposite of `git add -p` (see
 linkgit:git-add[1]).
++
+The configuration `interactive.singlekey` allows the user to provide
+one-letter input with a single key in this mode (i.e., without hitting enter).
 
 'git reset' [--<mode>] [<commit>]::
 	This form resets the current branch head to <commit> and
-- 
1.7.1

[PATCH v2 4/5] git-stash.txt: document 'interactive.singlekey'

[Valentin Haenel]

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Helped-by: Jeff King <peff@peff.net>
---
 Documentation/git-stash.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 79abc38..c8a349e 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -63,6 +63,9 @@ from your worktree.
 +
 The `--patch` option implies `--keep-index`.  You can use
 `--no-keep-index` to override this.
++
+The configuration `interactive.singlekey` allows the user to provide
+one-letter input with a single key when using `--patch` (i.e., without hitting enter).
 
 list [<options>]::
 
-- 
1.7.1

[PATCH v2 5/5] git-checkout.txt: document 'interactive.singlekey'

[Valentin Haenel]

Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Helped-by: Jeff King <peff@peff.net>
---
 Documentation/git-checkout.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 1063f69..556c82b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -63,6 +63,9 @@ Using `-f` will ignore these unmerged entries.  The contents from a
 specific side of the merge can be checked out of the index by
 using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
 file can be discarded to re-create the original conflicted merge result.
++
+The configuration `interactive.singlekey` allows the user to provide
+one-letter input with a single key when using `--patch` (i.e., without hitting enter).
 
 OPTIONS
 -------
-- 
1.7.1