[PATCH] doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes"

[PATCH] doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes"

[Sebastian Schuberth]

The documentation for "cherry-pick -x" can be misread in the way that a
"git notes" object is attached to the new commit, which is not the case.
Instead, just some text is appended to the original commit message. Make this
more clear by simply using the term "remark" instead of "note".

Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>
---
 Documentation/git-cherry-pick.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 01db830..5afc2b0 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -52,8 +52,8 @@ OPTIONS
 
 -x::
 	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
+	message a remark that indicates which commit this change
+	was cherry-picked from.  Append the remark 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
-- 
1.7.3.2.msysgit.11

Re: [PATCH] doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes"

[Junio C Hamano]

Sebastian Schuberth <sschuberth@gmail.com> writes:

> The documentation for "cherry-pick -x" can be misread in the way that a
> "git notes" object is attached to the new commit, which is not the case.
> Instead, just some text is appended to the original commit message. Make this
> more clear by simply using the term "remark" instead of "note".

A sensible concern, I guess, even though "_append_ to the original _commit
message_" should signal that this sentence cannot be referring to a note
object separate from the commit.

> diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
> index 01db830..5afc2b0 100644
> --- a/Documentation/git-cherry-pick.txt
> +++ b/Documentation/git-cherry-pick.txt
> @@ -52,8 +52,8 @@ OPTIONS
>  
>  -x::
>  	When recording the commit, append to the original commit
> +	message a remark that indicates which commit this change
> +	was cherry-picked from.  Append the remark only for cherry
>  	picks without conflicts.  ...

I wonder if it is better to be even more explicit and say:

	... append a line that says "(cherry picked from commit ...)" to
        the original commit message in order to indicate which commit this
        change was cherry-picked from.  This is done only for ...

so that we don't have to worry about having to change this in 10 years
when we notice that description can easily be misread that it is done
using the remark feature introduced a few years back?

[PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Sebastian Schuberth]

The documentation for "cherry-pick -x" could be misread in the way that a
"git notes" object is attached to the new commit, which is not the case.

Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>
---
 Documentation/git-cherry-pick.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 01db830..9d8fe0d 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -51,9 +51,10 @@ OPTIONS
 	message prior to committing.
 
 -x::
-	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
+	When recording the commit, append a line that says
+	"(cherry picked from commit ...)" to the original commit
+	message in order to indicate which commit this change was
+	cherry-picked from.  This is done 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
-- 
1.7.3.2.msysgit.11

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Jay Soffian]

On Fri, Apr 15, 2011 at 1:53 PM, Sebastian Schuberth
<sschuberth@gmail.com> wrote:
> The documentation for "cherry-pick -x" could be misread in the way that a
> "git notes" object is attached to the new commit, which is not the case.
>
> Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>
> ---
>  Documentation/git-cherry-pick.txt |    7 ++++---
>  1 files changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
> index 01db830..9d8fe0d 100644
> --- a/Documentation/git-cherry-pick.txt
> +++ b/Documentation/git-cherry-pick.txt
> @@ -51,9 +51,10 @@ OPTIONS
>        message prior to committing.
>
>  -x::
> -       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
> +       When recording the commit, append a line that says
> +       "(cherry picked from commit ...)" to the original commit
> +       message in order to indicate which commit this change was
> +       cherry-picked from.  This is done 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

As long as you're nearby, "This is done only for cherry picks without
conflicts." can be dropped. It's no longer true.

j.

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Sebastian Schuberth]

On Sat, Apr 16, 2011 at 00:22, Jay Soffian <jaysoffian@gmail.com> wrote:

>>  -x::
>> -       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
>> +       When recording the commit, append a line that says
>> +       "(cherry picked from commit ...)" to the original commit
>> +       message in order to indicate which commit this change was
>> +       cherry-picked from.  This is done 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
>
> As long as you're nearby, "This is done only for cherry picks without
> conflicts." can be dropped. It's no longer true.

How can this be not true anymore? If you get a conflict while picking,
you're asked to resolve the conflict and then commit via "git commit
-c <picked_sha1>". Doing so will *not* give you the mentioned "(cherry
picked from commit ...)" line.

-- 
Sebastian Schuberth

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Junio C Hamano]

Sebastian Schuberth <sschuberth@gmail.com> writes:

> How can this be not true anymore? If you get a conflict while picking,
> you're asked to resolve the conflict and then commit via "git commit
> -c <picked_sha1>". Doing so will *not* give you the mentioned "(cherry
> picked from commit ...)" line.

I suspect Jay had the recent CHERRY_PICK_HEAD series that lets you omit
saying "-c <picked>" in mind.  We should not leave the cherry-picked from
in such a case, I think, but the new code may be buggy.

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Sebastian Schuberth]

On Sat, Apr 16, 2011 at 18:33, Junio C Hamano <gitster@pobox.com> wrote:

>> How can this be not true anymore? If you get a conflict while picking,
>> you're asked to resolve the conflict and then commit via "git commit
>> -c <picked_sha1>". Doing so will *not* give you the mentioned "(cherry
>> picked from commit ...)" line.
>
> I suspect Jay had the recent CHERRY_PICK_HEAD series that lets you omit
> saying "-c <picked>" in mind.  We should not leave the cherry-picked from
> in such a case, I think, but the new code may be buggy.

Thanks for explaining. I keep my patchv2 as-is in this case.

-- 
Sebastian Schuberth

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Jay Soffian]

On Sat, Apr 16, 2011 at 12:33 PM, Junio C Hamano <gitster@pobox.com> wrote:
> I suspect Jay had the recent CHERRY_PICK_HEAD series that lets you omit
> saying "-c <picked>" in mind.

Correct.

>  We should not leave the cherry-picked from
> in such a case, I think, but the new code may be buggy.

Disagree. Here was my thought process (it was a conscious decision):
after conflict, when the user runs "git commit", the message is
brought up in the editor, leaving it up to the user to decide whether
it is appropriate to remove the "cherry-picked from" message. I
personally think it is correct to keept it, along with the list of
"Conflicts:". I understand some users think it's not appropriate to
keep the "cherry-picked from" message, but git should not force the
decision.

j.

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Junio C Hamano]

Jay Soffian <jaysoffian@gmail.com> writes:

> Disagree. Here was my thought process (it was a conscious decision):
> after conflict, when the user runs "git commit", the message is
> brought up in the editor, leaving it up to the user to decide whether
> it is appropriate to remove the "cherry-picked from" message. I
> personally think it is correct to keept it, along with the list of
> "Conflicts:".

I agree that the user can decide to remove that line in the editor when
the necessary conflict resolution was so extensive that the most part of
the original change became irrelevant.

It requires extra work that was unnecessary to the end user before the
series, and the series is a regression in that sense. But removing a
single extra line is much easier to do than adding the line from scratch,
so this particular potential regression is not really a big deal.

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> I agree that the user can decide to remove that line in the editor when
> the necessary conflict resolution was so extensive that the most part of
> the original change became irrelevant.
> ...

So to conclude,...

>> +       cherry-picked from.  This is done 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

... we could just remove the "This is done only for cherry picks without
conflicts."  We could explain that the user may want to remove the line
depending on the nature of the conflict resolution, but I guess it can
be left without saying.

Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"

[Sebastian Schuberth]

On Sun, Apr 17, 2011 at 04:39, Junio C Hamano <gitster@pobox.com> wrote:

> So to conclude,...
>
>>> +       cherry-picked from.  This is done 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
>
> ... we could just remove the "This is done only for cherry picks without
> conflicts."  We could explain that the user may want to remove the line
> depending on the nature of the conflict resolution, but I guess it can
> be left without saying.

Still, I believe it would be more consistent to do this change as part
of the CHERRY_PICK_HEAD series itself, then.

-- 
Sebastian Schuberth