Re: [PATCH v2] Revamp git-cherry(1)

[Junio C Hamano <gitster@pobox.com>]

Thomas Rast <tr@thomasrast.ch> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> We are listing those that need to be added to the upstream with "+",
>> while listing those that can be dropped from yours if you rebase
>> with "-".  Hinting the rationale behind the choice of "+/-"
>> somewhere may help as a mnemonic to the readers (see below).
> [...]
>> And the earlier "why +/-" could be done after this picture,
>> perhaps like:
>>
>> 	Here, we see that the commits A and C (marked with `-`) can
>> 	be dropped from your `topic` branch when you rebase it on
>> 	top of `origin/master`, while the commit B (marked with `+`)
>> 	still needs to be kept so that it will be sent to be applied
>> 	to `origin/master`.
>>
>> or somesuch?
>
> Good idea, thanks.  Will integrate this more "what still needs to be
> integrated"-minded wording into a v3.

Just to possibly save one round-trip, here is what I tentatively
queued on top of yours.

 Documentation/git-cherry.txt | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt
index 6d14b3e..0ea921a 100644
--- a/Documentation/git-cherry.txt
+++ b/Documentation/git-cherry.txt
@@ -3,7 +3,7 @@ git-cherry(1)
 
 NAME
 ----
-git-cherry - Find commits not applied in upstream
+git-cherry - Find commits yet to be applied to upstream
 
 SYNOPSIS
 --------
@@ -56,6 +56,7 @@ $ git checkout -b topic origin/master
 $ git format-patch origin/master
 $ git send-email ... 00*
 ------------
+
 Later, you can see whether your changes have been applied by saying
 (still on `topic`):
 
@@ -84,8 +85,8 @@ $ git log --graph --oneline --decorate --boundary origin/master...topic
 o 1234567 branch point
 ------------
 
-In such cases, git-cherry shows a concise summary of what has been
-applied:
+In such cases, git-cherry shows a concise summary of what has yet to
+be applied:
 
 ------------
 $ git cherry origin/master topic
@@ -94,6 +95,12 @@ $ git cherry origin/master topic
 - aaaa000... commit A
 ------------
 
+Here, we see that the commits A and C (marked with `-`) can be
+dropped from your `topic` branch when you rebase it on top of
+`origin/master`, while the commit B (marked with `+`) still needs to
+be kept so that it will be sent to be applied to `origin/master`.
+
+
 Using a limit
 ~~~~~~~~~~~~~
 
-- 
1.8.5-rc3-362-gdf10213