patchdoc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes"

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(-)

Sebastian Schuberth <sschuberth@gmail.com> writes:

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.

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?

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(-)

On Fri, Apr 15, 2011 at 1:53 PM, Sebastian Schuberth <sschuberth@gmail.com> wrote:

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

j.

On Sat, Apr 16, 2011 at 00:22, Jay Soffian <jaysoffian@gmail.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.

Sebastian Schuberth <sschuberth@gmail.com> writes:

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.

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

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

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

Correct.

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.

Jay Soffian <jaysoffian@gmail.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.

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.

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

So to conclude,...

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

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

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