doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes"
PATCH 1/1 doc: 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".
--- Documentation/git-cherry-pick.txt | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-)
Documentation/git-cherry-pick.txt +2 -2
@@ -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
Signature · 1 line
1.7.3.2.msysgit.11
Quoted 4 lines · 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".
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.
Documentation/git-cherry-pick.txt OPTIONS · line 57
Quoted 11 lines
Documentation/git-cherry-pick.txt +2
-0@@ -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?
PATCH v2 1/1 doc: Clarify that "cherry-pick -x" does not use "git notes"
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.
--- Documentation/git-cherry-pick.txt | 7 ++++--- 1 files changed, 4 insertions(+), 3 deletions(-)
Documentation/git-cherry-pick.txt +4 -3
@@ -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
Signature · 1 line
1.7.3.2.msysgit.11
Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"
Quoted 15 lines · 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 <[email protected]>---
Documentation/git-cherry-pick.txt | 7 ++++---1 files changed, 4 insertions(+), 3 deletions(-)Documentation/git-cherry-pick.txt +0
-0@@ -51,9 +51,10 @@ OPTIONSmessage prior to committing.
Quoted 11 lines
-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"
Quoted 12 lines · Jay Soffian
Quoted 11 lines
-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
Quoted 2 lines
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.
Signature · 1 line
Sebastian Schuberth
Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"
Quoted 4 lines · Sebastian Schuberth
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"
Quoted 2 lines · Junio C Hamano
I suspect Jay had the recent
CHERRY_PICK_HEADseries that lets you omit saying "-c <picked>" in mind.
Correct.
Quoted 2 lines
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"
Quoted 6 lines · Jay Soffian
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"
Quoted 4 lines · Junio C Hamano
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,...
Quoted 4 lines
Quoted 4 lines
+ 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"
Quoted 11 lines · Junio C Hamano
So to conclude,...
Quoted 4 lines
Quoted 4 lines
+ 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.
Signature · 1 line
Sebastian Schuberth
Re: [PATCHv2] doc: Clarify that "cherry-pick -x" does not use "git notes"
In reply to Junio C HamanoQuoted 8 lines · Junio C Hamano
Quoted 4 lines
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_HEADseries 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.
Signature · 1 line
Sebastian Schuberth