[PATCH] git-cherry-pick: improve description of -x.

Reword the first sentence of the description of -x, in order to
make it easier to read and understand.

Signed-off-by: Ralf Wildenhues <redacted>
---

I have two issues with "git-cherry-pick -x": When reading its manpage
description for the first time, I completely failed to understand the
first sentence, and had to try it out in order to understand.

Further, I am surprised that -x seems to be nonfunctional when the
cherry pick introduces a conflict.  Example:
  git init
  echo >dummy
  git add dummy
  git commit -m dummy
  git checkout -b br
  echo one >file
  git add file
  git commit -m one
  echo two >>file
  git commit -a -m two
  git checkout master
  git cherry-pick -x br         # conflict, tells me "-c ..." arg to use
                                # for the commit later
  echo '1d
  w' | ed file                  # resolve conflict
  git add file
  git commit -c ...

The prototype commit message now does not contain the
| (cherry picked from commit ...).

Is that by design (because there were conflicts) or an omission?
In case of the former, maybe the description of -x should mention this.

Thanks,
Ralf

 Documentation/git-cherry-pick.txt |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 47b1e8c..c7d83ce 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt

@@ -27,10 +27,10 @@ OPTIONS
 	message prior committing.
 
 -x::
-	Cause the command to append which commit was
-	cherry-picked after the original commit message when
-	making a commit.  Do not use this option if you are
-	cherry-picking from your private branch because the
+	When recording the commit, the original commit message will
+	be appended with a note that indicates which commit this
+	change was cherry-picked from.  Do not use this option if
+	you are cherry-picking from your private branch because the
 	information is useless to the recipient.  If on the
 	other hand you are cherry-picking between two publicly
 	visible branches (e.g. backporting a fix to a

-- 
1.5.3.1.153.g89df5

On Fri, Oct 19, 2007 at 07:41:34PM +0200, Ralf Wildenhues wrote:

Further, I am surprised that -x seems to be nonfunctional when the
cherry pick introduces a conflict.  Example:

[...]

The prototype commit message now does not contain the
| (cherry picked from commit ...).

Is that by design (because there were conflicts) or an omission?
In case of the former, maybe the description of -x should mention this.

git commit currently doesn't know that you commit a cherry-pick. The -c
only says to use the commit message of the original commit. So this is
currently by design.

Is "will be appended with" correct English? Sounds odd to me (but I'm no
native speaker, so it might be perfectly fine).

Gruesse,
-- 
Frank Lichtenheld [off-list ref]
www: http://www.djpig.de/

Frank Lichtenheld [off-list ref] wrote:

On Fri, Oct 19, 2007 at 07:41:34PM +0200, Ralf Wildenhues wrote:

quoted

Further, I am surprised that -x seems to be nonfunctional when the
cherry pick introduces a conflict.  Example:

[...]

quoted

The prototype commit message now does not contain the
| (cherry picked from commit ...).

Is that by design (because there were conflicts) or an omission?
In case of the former, maybe the description of -x should mention this.

git commit currently doesn't know that you commit a cherry-pick. The -c
only says to use the commit message of the original commit. So this is
currently by design.

Ralf, can you submit an updated version of this patch that describes
the current behavior better, given the "by design" remark above
from Frank?
 
-- 
Shawn.

Reword the first sentence of the description of -x, in order to
make it easier to read and understand.

Signed-off-by: Ralf Wildenhues <redacted>
---

* Shawn O. Pearce wrote on Sat, Oct 20, 2007 at 05:19:17AM CEST:

Frank Lichtenheld [off-list ref] wrote:

quoted

On Fri, Oct 19, 2007 at 07:41:34PM +0200, Ralf Wildenhues wrote:

quoted

Is that by design (because there were conflicts) or an omission?
In case of the former, maybe the description of -x should mention this.

git commit currently doesn't know that you commit a cherry-pick. The -c
only says to use the commit message of the original commit. So this is
currently by design.

Ralf, can you submit an updated version of this patch that describes
the current behavior better, given the "by design" remark above
from Frank?

Here it goes.  Still makes me wonder whether that is the ideal mode of
operation or not.

FWIW, I think the previous passive voice wording was correct English,
but here's a rewrite using mostly active voice (sound nicer anyway).

Cheers,
Ralf

 Documentation/git-cherry-pick.txt |   11 ++++++-----
 1 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 47b1e8c..76a2edf 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt

@@ -27,11 +27,12 @@ OPTIONS
 	message prior committing.
 
 -x::
-	Cause the command to append which commit was
-	cherry-picked after the original commit message when
-	making a commit.  Do not use this option if you are
-	cherry-picking from your private branch because the
-	information is useless to the recipient.  If on the
+	When recording the commit, append to the original commit
+	message a note that indicates which commit this change
+	was cherry-picked from.  Append the note only for cherry
+	picks without conflicts.  Do not use this option if
+	you are cherry-picking from your private branch because
+	the information is useless to the recipient.  If on the
 	other hand you are cherry-picking between two publicly
 	visible branches (e.g. backporting a fix to a
 	maintenance branch for an older release from a

-- 
1.5.3.1.153.g89df5

Ralf Wildenhues [off-list ref] wrote:

* Shawn O. Pearce wrote on Sat, Oct 20, 2007 at 05:19:17AM CEST:

quoted

Frank Lichtenheld [off-list ref] wrote:

quoted

On Fri, Oct 19, 2007 at 07:41:34PM +0200, Ralf Wildenhues wrote:

quoted

Is that by design (because there were conflicts) or an omission?
In case of the former, maybe the description of -x should mention this.

git commit currently doesn't know that you commit a cherry-pick. The -c
only says to use the commit message of the original commit. So this is
currently by design.

Ralf, can you submit an updated version of this patch that describes
the current behavior better, given the "by design" remark above
from Frank?

Here it goes.  Still makes me wonder whether that is the ideal mode of
operation or not.

Thanks.

I think you are right that the current behavior of -x *not*
including the prior commit SHA-1 in the case of a conflict is wrong.
The problem however is that git-commit.sh doesn't get the data
necessary to preseve the original author name/email/date/tz unless
you use the "-c $id" option.  There's some work here to store the
necessary information into a file that git-commit.sh could pickup,
and then making sure stale versions of those files get cleaned up
properly, etc.

At least the current behavior is now documented.  Maybe someone
will be bothered enough by it to try and submit a patch that changes
the behavior.
 
-- 
Shawn.

* Shawn O. Pearce wrote on Mon, Oct 22, 2007 at 07:14:53AM CEST:

I think you are right that the current behavior of -x *not*
including the prior commit SHA-1 in the case of a conflict is wrong.
The problem however is that git-commit.sh doesn't get the data
necessary to preseve the original author name/email/date/tz unless
you use the "-c $id" option.

But the note added by -x is even missing when I add "-c $id" to
the git-commit command!  That's the point I was trying to make,
and really the only thing that seemed weird to me.

Cheers,
Ralf