# [PATCH] doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes" 11 messages from 2011-04-15 to 2011-04-17. Participants: Sebastian Schuberth, Junio C Hamano, Jay Soffian. Thread: https://gitlist.dev/t/27103 ## Sebastian Schuberth, 2011-04-15 07:43 Subject: [PATCH] doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes" Message-ID: <4DA7F73B.9050007@gmail.com> URL: https://gitlist.dev/e/4DA7F73B.9050007%40gmail.com ``` 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 --- 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 ``` ## Junio C Hamano, 2011-04-15 17:12 Subject: Re: [PATCH] doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes" Message-ID: <7v7have8wo.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v7have8wo.fsf%40alter.siamese.dyndns.org In-Reply-To: <4DA7F73B.9050007@gmail.com> ``` Sebastian Schuberth 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? ``` ## Sebastian Schuberth, 2011-04-15 17:53 Subject: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: <4DA8862F.5070102@gmail.com> URL: https://gitlist.dev/e/4DA8862F.5070102%40gmail.com In-Reply-To: <7v7have8wo.fsf@alter.siamese.dyndns.org> ``` 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 --- 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 ``` ## Jay Soffian, 2011-04-15 22:22 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: URL: https://gitlist.dev/e/BANLkTi%3DHecmdGbEX5inqUi4FZ5Ty%2BL1Ybg%40mail.gmail.com In-Reply-To: <4DA8862F.5070102@gmail.com> ``` On Fri, Apr 15, 2011 at 1:53 PM, Sebastian Schuberth 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 > --- >  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. ``` ## Sebastian Schuberth, 2011-04-16 07:19 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: URL: https://gitlist.dev/e/BANLkTi%3Djr0hkmBUGj7tHURSj5XiJkyyQqg%40mail.gmail.com In-Reply-To: ``` On Sat, Apr 16, 2011 at 00:22, Jay Soffian 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 ". Doing so will *not* give you the mentioned "(cherry picked from commit ...)" line. -- Sebastian Schuberth ``` ## Junio C Hamano, 2011-04-16 16:33 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: <7vk4eub1g9.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vk4eub1g9.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Sebastian Schuberth 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 ". 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 " in mind. We should not leave the cherry-picked from in such a case, I think, but the new code may be buggy. ``` ## Sebastian Schuberth, 2011-04-16 16:55 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: URL: https://gitlist.dev/e/BANLkTimX6QQB8uASjNw4azG4Gdchc-S%3DrQ%40mail.gmail.com In-Reply-To: <7vk4eub1g9.fsf@alter.siamese.dyndns.org> ``` On Sat, Apr 16, 2011 at 18:33, Junio C Hamano 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 ". 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 " 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 ``` ## Jay Soffian, 2011-04-16 17:11 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: URL: https://gitlist.dev/e/BANLkTim2%3DJg4QcgKwO%3DJ6343zWAoCkyXZQ%40mail.gmail.com In-Reply-To: <7vk4eub1g9.fsf@alter.siamese.dyndns.org> ``` On Sat, Apr 16, 2011 at 12:33 PM, Junio C Hamano wrote: > I suspect Jay had the recent CHERRY_PICK_HEAD series that lets you omit > saying "-c " 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. ``` ## Junio C Hamano, 2011-04-16 17:42 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: <7vaafqay9f.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vaafqay9f.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Jay Soffian 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. ``` ## Junio C Hamano, 2011-04-17 02:39 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: <7v39lhbnzj.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v39lhbnzj.fsf%40alter.siamese.dyndns.org In-Reply-To: <7vaafqay9f.fsf@alter.siamese.dyndns.org> ``` Junio C Hamano 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. ``` ## Sebastian Schuberth, 2011-04-17 07:20 Subject: Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes" Message-ID: URL: https://gitlist.dev/e/BANLkTink3uzx3xz5_pG6FmFctD_2W6HiCg%40mail.gmail.com In-Reply-To: <7v39lhbnzj.fsf@alter.siamese.dyndns.org> ``` On Sun, Apr 17, 2011 at 04:39, Junio C Hamano 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 ```