revert: optionally refer to commit in the "reference" format
PATCH 1/1 revert: optionally refer to commit in the "reference" format
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.
This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
This reverts commit 8fa7f667 (do this and that, 2022-04-25)
so that the title does not have to be
Revert "do this and that"
We can instead use the title to describe "why" we are reverting the original commit.
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
--- Documentation/config/revert.txt | 3 +++ Documentation/git-revert.txt | 9 +++++++++ builtin/revert.c | 2 ++ sequencer.c | 32 +++++++++++++++++++++++++++----- sequencer.h | 1 + t/t3501-revert-cherry-pick.sh | 31 +++++++++++++++++++++++++++++++ 6 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 Documentation/config/revert.txt
Documentation/config/revert.txt new file +3 -0
@@ -0,0 +1,3 @@ +revert.reference:: + Setting this variable to true makes `git revert` to behave + as if the `--reference` option is given.
Documentation/git-revert.txt +9 -0
@@ -117,6 +117,15 @@ effect to your index in a row. Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. +--reference:: + Instead of starting the body of the log message with "This + reverts <full object name of the commit being reverted>.", + refer to the commit using "--pretty=reference" format + (cf. linkgit:git-log[1]). The `revert.reference` + configuration variable can be used to enable this option by + default. + + SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[]
builtin/revert.c +2 -0
@@ -116,6 +116,8 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;
sequencer.c +27 -5
@@ -221,6 +221,9 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } +if (!strcmp (k,"revert.reference" )) + opts->commit_use_reference =git_config_bool (k, v); + status =git_gpg_config (k, v,NULL );if (status)return status;
@@ -2059,6 +2062,20 @@ static int should_edit(struct replay_opts *opts) {return opts->edit; } +static void refer_to_commit (struct replay_opts *opts, +struct strbuf *msgbuf,struct commit *commit) +{ +if (opts->commit_use_reference) { +struct pretty_print_context ctx = { + .abbrev =DEFAULT_ABBREV , + .date_mode.type =DATE_SHORT , + }; +format_commit_message (commit,"%h (%s, %ad)" , msgbuf, &ctx); + }else { +strbuf_addstr (msgbuf,oid_to_hex (&commit->object.oid)); + } +} + static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,
@@ -2167,14 +2184,19 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -strbuf_addstr (&msgbuf,"Revert \"" ); -strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (!opts->commit_use_reference) { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject); +strbuf_addstr (&msgbuf,"\"" ); + }else { +strbuf_addstr (&msgbuf,"DESCRIBE WHY WE ARE REVERTING HERE" ); + } +strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +refer_to_commit (opts, &msgbuf, commit);if (commit->parents && commit->parents->next) {strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); +refer_to_commit (opts, &msgbuf, parent); }strbuf_addstr (&msgbuf,".\n" ); }else {
sequencer.h +1 -0
@@ -49,6 +49,7 @@ struct replay_opts {int reschedule_failed_exec;int committer_date_is_author_date;int ignore_date; +int commit_use_reference;int mainline;
t/t3501-revert-cherry-pick.sh +31 -0
@@ -159,6 +159,7 @@ test_expect_success 'cherry-pick works with dirty renamed file' ' ' test_expect_success 'advice from failed revert' ' + test_when_finished "git reset --hard" && test_commit --no-tag "add dream" dream dream && dream_oid=$(git rev-parse --short HEAD) && cat <<-EOF >expected &&
@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (vanilla)' ' + test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done
Signature · 1 line
2.36.1-298-g81715a4e6d
Hi Junio,
Quoted 11 lines · Junio C Hamano
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
Quoted 8 lines
This reverts commit 8fa7f667 (do this and that, 2022-04-25)so that the title does not have to be
Revert "do this and that"
We can instead use the title to describe "why" we are reverting the original commit.
Good idea, the reference text is so much more pleasant to read (and it also makes things somewhat proof against rebasing and transitioning to SHA-256).
Quoted 4 lines
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
At some stage, we may even default to revert.reference=true?
Quoted 7 lines
Documentation/git-revert.txt +0
-0@@ -117,6 +117,15 @@ effect to your index in a row. Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible.
Documentation/git-revert.txt effect to your index in a row. · line 128
Quoted 10 lines
Documentation/git-revert.txt +9
-0+--reference:: + Instead of starting the body of the log message with "This + reverts <full object name of the commit being reverted>.", + refer to the commit using "--pretty=reference" format + (cf. linkgit:git-log[1]). The `revert.reference` + configuration variable can be used to enable this option by + default. + +
Is that extra empty line intentional?
Quoted 33 lines
Documentation/git-revert.txt +0
-0SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[]builtin/revert.c +2
-0@@ -116,6 +116,8 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;sequencer.c +3
-0@@ -221,6 +221,9 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } +if (!strcmp (k,"revert.reference" )) + opts->commit_use_reference =git_config_bool (k, v); + status =git_gpg_config (k, v,NULL );if (status)return status;@@ -2059,6 +2062,20 @@ static int should_edit(struct replay_opts *opts) {return opts->edit; }
sequencer.c static int should_edit(struct replay_opts *opts) { · line 2073
Quoted 10 lines
sequencer.c +9
-0+static void refer_to_commit (struct replay_opts *opts, +struct strbuf *msgbuf,struct commit *commit) +{ +if (opts->commit_use_reference) { +struct pretty_print_context ctx = { + .abbrev =DEFAULT_ABBREV , + .date_mode.type =DATE_SHORT , + }; +format_commit_message (commit,"%h (%s, %ad)" , msgbuf, &ctx);
It is somewhat sad that we have to semi-duplicate [*1*] this format here and do not have something like an enum value we can use instead.
Quoted 13 lines
sequencer.c +5
-1+ }else { +strbuf_addstr (msgbuf,oid_to_hex (&commit->object.oid)); + } +} + static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,@@ -2167,14 +2184,19 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -strbuf_addstr (&msgbuf,"Revert \"" );
sequencer.c static int do_pick_commit(struct repository *r, · line 2193
Quoted 10 lines
sequencer.c +7
-3-strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (!opts->commit_use_reference) { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject); +strbuf_addstr (&msgbuf,"\"" ); + }else { +strbuf_addstr (&msgbuf,"DESCRIBE WHY WE ARE REVERTING HERE" ); + }
We often tell newcomers that we prefer the shorter conditional block to come first. Maybe you want to do that here, too? I don't mind the current form, though.
Quoted 35 lines
sequencer.c +3
-1+strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +refer_to_commit (opts, &msgbuf, commit);if (commit->parents && commit->parents->next) {strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); +refer_to_commit (opts, &msgbuf, parent); }strbuf_addstr (&msgbuf,".\n" ); }else {sequencer.h +1
-0@@ -49,6 +49,7 @@ struct replay_opts {int reschedule_failed_exec;int committer_date_is_author_date;int ignore_date; +int commit_use_reference;int mainline;t/t3501-revert-cherry-pick.sh +1
-0@@ -159,6 +159,7 @@ test_expect_success 'cherry-pick works with dirty renamed file' ' ' test_expect_success 'advice from failed revert' ' + test_when_finished "git reset --hard" && test_commit --no-tag "add dream" dream dream && dream_oid=$(git rev-parse --short HEAD) && cat <<-EOF >expected &&
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 179
Quoted 5 lines
t/t3501-revert-cherry-pick.sh +2
-0@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (vanilla)' '
It might make sense to replace "vanilla" by "default format".
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 186
Quoted 7 lines
t/t3501-revert-cherry-pick.sh +7
-0+ test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect &&
I was a bit puzzled about this dance, as I had expected this instead:
grep "^This reverts commit $(git rev-parse HEAD^)\\.$" actual.raw
but I guess you wanted to make sure that the file contents of actual are shown if no match was found?
If that was the intention, we may want to add a test helper that I know from other test frameworks, something like test_contains that takes a regex and a file and prints out the full contents if no match was found.
It's obviously not necessary to add this test helper in this patch series of a single patch ("separation of concerns"), just food for thought.
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 197
Quoted 11 lines
t/t3501-revert-cherry-pick.sh +11
-0+ test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +'
If it was up to me, I would combine these three test cases, if only to help the --run=<single-number> case (the latter two depend on the side effect of the first one to create a to-ident tag).
Quoted 12 lines
t/t3501-revert-cherry-pick.sh +10
-1+ +test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done --
Quoted 1 line
2.36.1-298-g81715a4e6d
Looks good, I have no objections against merging this as-is.
Ciao,
Dscho
Footnote *1*: https://github.com/git/git/blob/v2.36.1/pretty.c#L103-L104
also has the %C(auto) prefix, which we obviously do not need here.
Quoted 3 lines · Johannes Schindelin
Good idea, the
referencetext is so much more pleasant to read (and it also makes things somewhat proof against rebasing and transitioning to SHA-256).
Never thought of that myself. It does sound like another good reason to see if this is a good alternative format to use.
Quoted 1 line
At some stage, we may even default to
revert.reference=true?
Perhaps. Wasn't planning to propose that in any near future, either, though. I would prefer to never think about changing the default in the future when considering a new feature. It should be done as two separate steps (except that care must be taken so that the feature could become default if we choose to).
Quoted 7 lines
Review
Quoted 5 lines
+--reference::
...(quoted diff) +3
-0+ default. + +Is that extra empty line intentional?
It is very much so. A single blank between each items in the section, a larger blank between two sections, is what I aimed at here.
Quoted 11 lines
Review
Quoted 7 lines
(quoted diff) +7
-0+ if (!opts->commit_use_reference) { + strbuf_addstr(&msgbuf, "Revert \""); + strbuf_addstr(&msgbuf, msg.subject); + strbuf_addstr(&msgbuf, "\""); + } else { + strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE"); + }We often tell newcomers that we prefer the shorter conditional block to come first. Maybe you want to do that here, too? I don't mind the current form, though.
Good point, but that is more applicable to new code (and not limited to newcomers). We also tell that your new feature is often not any more important than the existing code, and think twice before prepending the new code to existing code (iow, by default new code should be appended, unless there is a good reason not to).
I kept the original behaviour first with optional new action as a follow-up. Besides, 3-line block is not all that larger than a single-line block, and this did not trigger my "that one is larger" sensor.
Let me try swapping the order.
Quoted 8 lines
Review test_expect_success 'advice from failed revert' ' · line 179
Quoted 6 lines
(quoted diff) +2
-0@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (vanilla)' 'It might make sense to replace "vanilla" by "default format".
Sounds very sensible; thanks.
Quoted 10 lines
Review test_expect_success 'advice from failed revert' ' · line 186
Quoted 7 lines
(quoted diff) +7
-0+ test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect &&I was a bit puzzled about this dance, as I had expected this instead:
Quoted 4 lines
grep "^This reverts commit $(git rev-parse HEAD^)\\.$" actual.rawbut I guess you wanted to make sure that the file contents of
actualare shown if no match was found?
My thought process was much simpler.
"^This reverts" is common in both formats, so grep would extract the commit reference(s) the command would have made to "actual".
What we need to make sure with the test_cmp are multifold. We want to make sure that the reference is made in the right format, refers to the right commit, and we show the reference exactly the expected number (i.e. one) of times. So it was simpler to do so in a step separate from the "extraction" step above. We could go looser and use test_contains but I usually try to avoid deliberately to be loose.
Quoted 4 lines
Quoted 4 lines
(quoted diff) +4
-0+test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw &&
Quoted 8 lines
Review test_expect_success 'advice from failed revert' ' · line 194
Quoted 4 lines
(quoted diff) +4
-0+ grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +'If it was up to me, I would combine these three test cases, if only to help the
--run=<single-number>case (the latter two depend on the side effect of the first one to create ato-identtag).
I wonder if our prereq infrastructure is lightweight and scalable enough so that we can easily add a support a pseudo-prerequisite PREVIOUS that lets us say
test_expect_success PREVIOUS "identification ..." ' ... '
to mean that this test requires the previous test has not been skipped.
Then we can organize them into four (one to create to-ident commit, one uses vanilla, one uses --reference and one uses revert.reference), and make the latter three depend on their previous step.
Quoted 10 lines
Review test_expect_success 'advice from failed revert' ' · line 204
Quoted 10 lines
(quoted diff) +9
-0+test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done
Thanks for taking a look.
--- >8 ---
Subject: [PATCH v2] revert: optionally refer to commit in the "reference" format
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.
This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
This reverts commit 8fa7f667 (do this and that, 2022-04-25)
so that the title does not have to be
Revert "do this and that"
We can instead use the title to describe "why" we are reverting the original commit.
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
---
Range-diff:
1: 26b60b56c0 ! 1: c5b11efe7d revert: optionally refer to commit in the "reference" format
@@ sequencer.c: static int do_pick_commit(struct repository *r,
- strbuf_addstr(&msgbuf, msg.subject);
- strbuf_addstr(&msgbuf, "\"\n\nThis reverts commit ");
- strbuf_addstr(&msgbuf, oid_to_hex(&commit->object.oid));
-+ if (!opts->commit_use_reference) {
++ if (opts->commit_use_reference) {
++ strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");
++ } else {
+ strbuf_addstr(&msgbuf, "Revert \"");
+ strbuf_addstr(&msgbuf, msg.subject);
+ strbuf_addstr(&msgbuf, "\"");
-+ } else {
-+ strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");
+ }
+ strbuf_addstr(&msgbuf, "\n\nThis reverts commit ");
+ refer_to_commit(opts, &msgbuf, commit);
@@ t/t3501-revert-cherry-pick.sh: test_expect_success 'advice from failed revert' '
test_cmp expected actual
'
+
-+test_expect_success 'identification of reverted commit (vanilla)' '
++test_expect_success 'identification of reverted commit (default)' '
+ test_commit to-ident &&
+ test_when_finished "git reset --hard to-ident" &&
+ git checkout --detach to-ident &&
@@ t/t3501-revert-cherry-pick.sh: test_expect_success 'advice from failed revert' '
+ test_cmp expect actual
+'
+
-+test_expect_success 'identification of reverted commit (reference)' '
++test_expect_success 'identification of reverted commit (--reference)' '
+ git checkout --detach to-ident &&
+ git revert --reference --no-edit HEAD &&
+ git cat-file commit HEAD >actual.raw &&
@@ t/t3501-revert-cherry-pick.sh: test_expect_success 'advice from failed revert' '
+ test_cmp expect actual
+'
+
-+test_expect_success 'identification of reverted commit (reference)' '
++test_expect_success 'identification of reverted commit (revert.reference)' '
+ git checkout --detach to-ident &&
+ git -c revert.reference=true revert --no-edit HEAD &&
+ git cat-file commit HEAD >actual.raw &&Documentation/config/revert.txt | 3 +++ Documentation/git-revert.txt | 9 +++++++++ builtin/revert.c | 2 ++ sequencer.c | 32 +++++++++++++++++++++++++++----- sequencer.h | 1 + t/t3501-revert-cherry-pick.sh | 31 +++++++++++++++++++++++++++++++ 6 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 Documentation/config/revert.txt
Documentation/config/revert.txt new file +3 -0
@@ -0,0 +1,3 @@ +revert.reference:: + Setting this variable to true makes `git revert` to behave + as if the `--reference` option is given.
Documentation/git-revert.txt +9 -0
@@ -117,6 +117,15 @@ effect to your index in a row. Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. +--reference:: + Instead of starting the body of the log message with "This + reverts <full object name of the commit being reverted>.", + refer to the commit using "--pretty=reference" format + (cf. linkgit:git-log[1]). The `revert.reference` + configuration variable can be used to enable this option by + default. + + SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[]
builtin/revert.c +2 -0
@@ -116,6 +116,8 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;
sequencer.c +27 -5
@@ -221,6 +221,9 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } +if (!strcmp (k,"revert.reference" )) + opts->commit_use_reference =git_config_bool (k, v); + status =git_gpg_config (k, v,NULL );if (status)return status;
@@ -2059,6 +2062,20 @@ static int should_edit(struct replay_opts *opts) {return opts->edit; } +static void refer_to_commit (struct replay_opts *opts, +struct strbuf *msgbuf,struct commit *commit) +{ +if (opts->commit_use_reference) { +struct pretty_print_context ctx = { + .abbrev =DEFAULT_ABBREV , + .date_mode.type =DATE_SHORT , + }; +format_commit_message (commit,"%h (%s, %ad)" , msgbuf, &ctx); + }else { +strbuf_addstr (msgbuf,oid_to_hex (&commit->object.oid)); + } +} + static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,
@@ -2167,14 +2184,19 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -strbuf_addstr (&msgbuf,"Revert \"" ); -strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (opts->commit_use_reference) { +strbuf_addstr (&msgbuf,"DESCRIBE WHY WE ARE REVERTING HERE" ); + }else { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject); +strbuf_addstr (&msgbuf,"\"" ); + } +strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +refer_to_commit (opts, &msgbuf, commit);if (commit->parents && commit->parents->next) {strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); +refer_to_commit (opts, &msgbuf, parent); }strbuf_addstr (&msgbuf,".\n" ); }else {
sequencer.h +1 -0
@@ -49,6 +49,7 @@ struct replay_opts {int reschedule_failed_exec;int committer_date_is_author_date;int ignore_date; +int commit_use_reference;int mainline;
t/t3501-revert-cherry-pick.sh +31 -0
@@ -159,6 +159,7 @@ test_expect_success 'cherry-pick works with dirty renamed file' ' ' test_expect_success 'advice from failed revert' ' + test_when_finished "git reset --hard" && test_commit --no-tag "add dream" dream dream && dream_oid=$(git rev-parse --short HEAD) && cat <<-EOF >expected &&
@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (default)' ' + test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (--reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (revert.reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done
Signature · 1 line
2.36.1-312-ge077cd1662
PATCH v3 1/1 revert: optionally refer to commit in the "reference" format
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.
This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
This reverts commit 8fa7f667 (do this and that, 2022-04-25)
so that the title does not have to be
Revert "do this and that"
We can instead use the title to describe "why" we are reverting the original commit.
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
When this option is in use, the first line of the pre-filled editor buffer becomes a comment line that tells the user to say _why_. If the user exits the editor without touching this line by mistake, what we prepare to become the first line of the body, i.e. "This reverts commit 8fa7f667 (do this and that, 2022-04-25)", ends up to be the title of the resulting commit. This behaviour is designed to help such a user to identify such a revert in "git log --oneline" easily so that it can be further reworded with "git rebase -i" later.
---
* The only difference since the second one is that the first line of the log message template is commented out and has asterisks to draw more attention. The last paragraph (new) in the proposed log message explains the rationale behind this design.
Third-time a charm, hopefully.
Range-diff against v2:
1: 4152fc2092 ! 1: f4325a503a revert: optionally refer to commit in the "reference" format
@@ Commit message
tweak the title and the first line of the draft commit message for when creating a "revert" commit.
+ When this option is in use, the first line of the pre-filled editor
+ buffer becomes a comment line that tells the user to say _why_. If
+ the user exits the editor without touching this line by mistake,
+ what we prepare to become the first line of the body, i.e. "This
+ reverts commit 8fa7f667 (do this and that, 2022-04-25)", ends up to
+ be the title of the resulting commit. This behaviour is designed to
+ help such a user to identify such a revert in "git log --oneline"
+ easily so that it can be further reworded with "git rebase -i" later.
+
## Documentation/config/revert.txt (new) ##
@@ sequencer.c: static int do_pick_commit(struct repository *r,
- strbuf_addstr(&msgbuf, "\"\n\nThis reverts commit ");
- strbuf_addstr(&msgbuf, oid_to_hex(&commit->object.oid));
+ if (opts->commit_use_reference) {
-+ strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");
++ strbuf_addstr(&msgbuf,
++ "# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***");
+ } else {
+ strbuf_addstr(&msgbuf, "Revert \"");
+ strbuf_addstr(&msgbuf, msg.subject);
Documentation/config/revert.txt | 3 +++ Documentation/git-revert.txt | 9 +++++++++ builtin/revert.c | 2 ++ sequencer.c | 33 ++++++++++++++++++++++++++++----- sequencer.h | 1 + t/t3501-revert-cherry-pick.sh | 31 +++++++++++++++++++++++++++++++ 6 files changed, 74 insertions(+), 5 deletions(-) create mode 100644 Documentation/config/revert.txt
Documentation/config/revert.txt new file +3 -0
@@ -0,0 +1,3 @@ +revert.reference:: + Setting this variable to true makes `git revert` to behave + as if the `--reference` option is given.
Documentation/git-revert.txt +9 -0
@@ -117,6 +117,15 @@ effect to your index in a row. Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. +--reference:: + Instead of starting the body of the log message with "This + reverts <full object name of the commit being reverted>.", + refer to the commit using "--pretty=reference" format + (cf. linkgit:git-log[1]). The `revert.reference` + configuration variable can be used to enable this option by + default. + + SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[]
builtin/revert.c +2 -0
@@ -116,6 +116,8 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;
sequencer.c +28 -5
@@ -221,6 +221,9 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } +if (!strcmp (k,"revert.reference" )) + opts->commit_use_reference =git_config_bool (k, v); + status =git_gpg_config (k, v,NULL );if (status)return status;
@@ -2059,6 +2062,20 @@ static int should_edit(struct replay_opts *opts) {return opts->edit; } +static void refer_to_commit (struct replay_opts *opts, +struct strbuf *msgbuf,struct commit *commit) +{ +if (opts->commit_use_reference) { +struct pretty_print_context ctx = { + .abbrev =DEFAULT_ABBREV , + .date_mode.type =DATE_SHORT , + }; +format_commit_message (commit,"%h (%s, %ad)" , msgbuf, &ctx); + }else { +strbuf_addstr (msgbuf,oid_to_hex (&commit->object.oid)); + } +} + static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,
@@ -2167,14 +2184,20 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -strbuf_addstr (&msgbuf,"Revert \"" ); -strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (opts->commit_use_reference) { +strbuf_addstr (&msgbuf, +"# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***" ); + }else { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject); +strbuf_addstr (&msgbuf,"\"" ); + } +strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +refer_to_commit (opts, &msgbuf, commit);if (commit->parents && commit->parents->next) {strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); +refer_to_commit (opts, &msgbuf, parent); }strbuf_addstr (&msgbuf,".\n" ); }else {
sequencer.h +1 -0
@@ -49,6 +49,7 @@ struct replay_opts {int reschedule_failed_exec;int committer_date_is_author_date;int ignore_date; +int commit_use_reference;int mainline;
t/t3501-revert-cherry-pick.sh +31 -0
@@ -159,6 +159,7 @@ test_expect_success 'cherry-pick works with dirty renamed file' ' ' test_expect_success 'advice from failed revert' ' + test_when_finished "git reset --hard" && test_commit --no-tag "add dream" dream dream && dream_oid=$(git rev-parse --short HEAD) && cat <<-EOF >expected &&
@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (default)' ' + test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (--reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (revert.reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done
Signature · 1 line
2.36.1-331-g1b5d92e060
Hi Junio,
Quoted 34 lines · Junio C Hamano
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
This reverts commit 8fa7f667 (do this and that, 2022-04-25)so that the title does not have to be
Revert "do this and that"
We can instead use the title to describe "why" we are reverting the original commit.
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
When this option is in use, the first line of the pre-filled editor buffer becomes a comment line that tells the user to say _why_. If the user exits the editor without touching this line by mistake, what we prepare to become the first line of the body, i.e. "This reverts commit
8fa7f667(do this and that, 2022-04-25)", ends up to be the title of the resulting commit. This behaviour is designed to help such a user to identify such a revert in "git log --oneline" easily so that it can be further reworded with "git rebase -i" later.
Quoted 7 lines
Signed-off-by Junio C Hamano <[email protected]>---
* The only difference since the second one is that the first line of the log message template is commented out and has asterisks to draw more attention. The last paragraph (new) in the proposed log message explains the rationale behind this design.
While it may be more purist to try to force the user to provide a description by having a non-comment placeholder there, from my experience with PullRequest/Issue templates convinces me that the comment is the more practical approach.
Looking good,
Dscho
Quoted 207 lines
Third-time a charm, hopefully.
Range-diff against v2:
1:4152fc2092! 1:f4325a503arevert: optionally refer to commit in the "reference" format
@@ Commit message
tweak the title and the first line of the draft commit message for when creating a "revert" commit.+ When this option is in use, the first line of the pre-filled editor
+ buffer becomes a comment line that tells the user to say _why_. If
+ the user exits the editor without touching this line by mistake,
+ what we prepare to become the first line of the body, i.e. "This
+ reverts commit8fa7f667(do this and that, 2022-04-25)", ends up to
+ be the title of the resulting commit. This behaviour is designed to
+ help such a user to identify such a revert in "git log --oneline"
+ easily so that it can be further reworded with "git rebase -i" later.
+Signed-off-by Junio C Hamano <[email protected]>##
Documentation/config/revert.txt(new) ##
@@sequencer.c: static int do_pick_commit(struct repository *r,
-strbuf_addstr(&msgbuf, "\"\n\nThis reverts commit ");
-strbuf_addstr(&msgbuf, oid_to_hex(&commit->object.oid));
+ if (opts->commit_use_reference) {
-+strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");
++ strbuf_addstr(&msgbuf,
++ "# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***");
+ } else {
+strbuf_addstr(&msgbuf, "Revert \"");
+strbuf_addstr(&msgbuf, msg.subject);Documentation/config/revert.txt | 3 +++ Documentation/git-revert.txt | 9 +++++++++ builtin/revert.c | 2 ++ sequencer.c | 33 ++++++++++++++++++++++++++++----- sequencer.h | 1 + t/t3501-revert-cherry-pick.sh | 31 +++++++++++++++++++++++++++++++ 6 files changed, 74 insertions(+), 5 deletions(-) create mode 100644 Documentation/config/revert.txtDocumentation/config/revert.txt new file +3
-0@@ -0,0 +1,3 @@ +revert.reference:: + Setting this variable to true makes `git revert` to behave + as if the `--reference` option is given.Documentation/git-revert.txt +9
-0@@ -117,6 +117,15 @@ effect to your index in a row. Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. +--reference:: + Instead of starting the body of the log message with "This + reverts <full object name of the commit being reverted>.", + refer to the commit using "--pretty=reference" format + (cf. linkgit:git-log[1]). The `revert.reference` + configuration variable can be used to enable this option by + default. + + SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[]builtin/revert.c +2
-0@@ -116,6 +116,8 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;sequencer.c +28
-5@@ -221,6 +221,9 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } +if (!strcmp (k,"revert.reference" )) + opts->commit_use_reference =git_config_bool (k, v); + status =git_gpg_config (k, v,NULL );if (status)return status;@@ -2059,6 +2062,20 @@ static int should_edit(struct replay_opts *opts) {return opts->edit; } +static void refer_to_commit (struct replay_opts *opts, +struct strbuf *msgbuf,struct commit *commit) +{ +if (opts->commit_use_reference) { +struct pretty_print_context ctx = { + .abbrev =DEFAULT_ABBREV , + .date_mode.type =DATE_SHORT , + }; +format_commit_message (commit,"%h (%s, %ad)" , msgbuf, &ctx); + }else { +strbuf_addstr (msgbuf,oid_to_hex (&commit->object.oid)); + } +} + static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,@@ -2167,14 +2184,20 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -strbuf_addstr (&msgbuf,"Revert \"" ); -strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (opts->commit_use_reference) { +strbuf_addstr (&msgbuf, +"# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***" ); + }else { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject); +strbuf_addstr (&msgbuf,"\"" ); + } +strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +refer_to_commit (opts, &msgbuf, commit);if (commit->parents && commit->parents->next) {strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); +refer_to_commit (opts, &msgbuf, parent); }strbuf_addstr (&msgbuf,".\n" ); }else {sequencer.h +1
-0@@ -49,6 +49,7 @@ struct replay_opts {int reschedule_failed_exec;int committer_date_is_author_date;int ignore_date; +int commit_use_reference;int mainline;t/t3501-revert-cherry-pick.sh +31
-1@@ -159,6 +159,7 @@ test_expect_success 'cherry-pick works with dirty renamed file' ' ' test_expect_success 'advice from failed revert' ' + test_when_finished "git reset --hard" && test_commit --no-tag "add dream" dream dream && dream_oid=$(git rev-parse --short HEAD) && cat <<-EOF >expected &&@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (default)' ' + test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (--reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (revert.reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done --2.36.1-331-g1b5d92e060
Hi Junio
Quoted 35 lines · Junio C Hamano
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
This reverts commit 8fa7f667 (do this and that, 2022-04-25)so that the title does not have to be
Revert "do this and that"
We can instead use the title to describe "why" we are reverting the original commit.
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
When this option is in use, the first line of the pre-filled editor buffer becomes a comment line that tells the user to say _why_. If the user exits the editor without touching this line by mistake, what we prepare to become the first line of the body, i.e. "This reverts commit
8fa7f667(do this and that, 2022-04-25)", ends up to be the title of the resulting commit. This behaviour is designed to help such a user to identify such a revert in "git log --oneline" easily so that it can be further reworded with "git rebase -i" later.Signed-off-by Junio C Hamano <[email protected]>
Quoted 8 lines
---
* The only difference since the second one is that the first line of the log message template is commented out and has asterisks to draw more attention. The last paragraph (new) in the proposed log message explains the rationale behind this design.
Third-time a charm, hopefully.
I think the changes to the template message are good. We're still adding "--reference" as a valid option to cherry-pick though which I don't think is a good idea (though in the future we may want to allow "cherry-pick -x --reference")
Best Wishes
Phillip
Quoted 200 lines
Range-diff against v2:
1:4152fc2092! 1:f4325a503arevert: optionally refer to commit in the "reference" format
@@ Commit message
tweak the title and the first line of the draft commit message for when creating a "revert" commit.+ When this option is in use, the first line of the pre-filled editor
+ buffer becomes a comment line that tells the user to say _why_. If
+ the user exits the editor without touching this line by mistake,
+ what we prepare to become the first line of the body, i.e. "This
+ reverts commit8fa7f667(do this and that, 2022-04-25)", ends up to
+ be the title of the resulting commit. This behaviour is designed to
+ help such a user to identify such a revert in "git log --oneline"
+ easily so that it can be further reworded with "git rebase -i" later.
+Signed-off-by Junio C Hamano <[email protected]>##
Documentation/config/revert.txt(new) ##
@@sequencer.c: static int do_pick_commit(struct repository *r,
-strbuf_addstr(&msgbuf, "\"\n\nThis reverts commit ");
-strbuf_addstr(&msgbuf, oid_to_hex(&commit->object.oid));
+ if (opts->commit_use_reference) {
-+strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");
++ strbuf_addstr(&msgbuf,
++ "# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***");
+ } else {
+strbuf_addstr(&msgbuf, "Revert \"");
+strbuf_addstr(&msgbuf, msg.subject);Documentation/config/revert.txt | 3 +++ Documentation/git-revert.txt | 9 +++++++++ builtin/revert.c | 2 ++ sequencer.c | 33 ++++++++++++++++++++++++++++----- sequencer.h | 1 + t/t3501-revert-cherry-pick.sh | 31 +++++++++++++++++++++++++++++++ 6 files changed, 74 insertions(+), 5 deletions(-)create mode 100644
Documentation/config/revert.txtDocumentation/config/revert.txt new file +3
-0@@ -0,0 +1,3 @@ +revert.reference:: + Setting this variable to true makes `git revert` to behave + as if the `--reference` option is given.Documentation/git-revert.txt +9
-0@@ -117,6 +117,15 @@ effect to your index in a row. Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. +--reference:: + Instead of starting the body of the log message with "This + reverts <full object name of the commit being reverted>.", + refer to the commit using "--pretty=reference" format + (cf. linkgit:git-log[1]). The `revert.reference` + configuration variable can be used to enable this option by + default. + + SEQUENCER SUBCOMMANDS --------------------- include::sequencer.txt[]builtin/revert.c +2
-0@@ -116,6 +116,8 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;sequencer.c +28
-5@@ -221,6 +221,9 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } +if (!strcmp (k,"revert.reference" )) + opts->commit_use_reference =git_config_bool (k, v); + status =git_gpg_config (k, v,NULL );if (status)return status;@@ -2059,6 +2062,20 @@ static int should_edit(struct replay_opts *opts) {return opts->edit; } +static void refer_to_commit (struct replay_opts *opts, +struct strbuf *msgbuf,struct commit *commit) +{ +if (opts->commit_use_reference) { +struct pretty_print_context ctx = { + .abbrev =DEFAULT_ABBREV , + .date_mode.type =DATE_SHORT , + }; +format_commit_message (commit,"%h (%s, %ad)" , msgbuf, &ctx); + }else { +strbuf_addstr (msgbuf,oid_to_hex (&commit->object.oid)); + } +} + static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,@@ -2167,14 +2184,20 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -strbuf_addstr (&msgbuf,"Revert \"" ); -strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (opts->commit_use_reference) { +strbuf_addstr (&msgbuf, +"# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***" ); + }else { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject); +strbuf_addstr (&msgbuf,"\"" ); + } +strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +refer_to_commit (opts, &msgbuf, commit);if (commit->parents && commit->parents->next) {strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); +refer_to_commit (opts, &msgbuf, parent); }strbuf_addstr (&msgbuf,".\n" ); }else {sequencer.h +1
-0@@ -49,6 +49,7 @@ struct replay_opts {int reschedule_failed_exec;int committer_date_is_author_date;int ignore_date; +int commit_use_reference;int mainline;t/t3501-revert-cherry-pick.sh +31
-0@@ -159,6 +159,7 @@ test_expect_success 'cherry-pick works with dirty renamed file' ' ' test_expect_success 'advice from failed revert' ' + test_when_finished "git reset --hard" && test_commit --no-tag "add dream" dream dream && dream_oid=$(git rev-parse --short HEAD) && cat <<-EOF >expected &&@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (default)' ' + test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (--reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (revert.reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done
Quoted 4 lines · Phillip Wood
I think the changes to the template message are good. We're still adding "--reference" as a valid option to cherry-pick though which I don't think is a good idea (though in the future we may want to allow "cherry-pick -x --reference")
I love when people notice mistakes that the original author and other people missed, many eyes making all bugs shallow.
I am inclined to apply the following on top. How does it look?
Thanks.
----- >8 --------- >8 --------- >8 --------- >8 -----
Subject: [PATCH] revert: --reference should apply only to 'revert', not 'cherry-pick'
As 'revert' and 'cherry-pick' share a lot of code, it is easy to modify the behaviour of one command and inadvertently affect the other. An earlier change to teach the '--reference' option and the 'revert.reference' configuration variable to the former was not careful enough and 'cherry-pick --reference' wasn't rejected as an error.
It is possible to think 'cherry-pick -x' might benefit from the '--reference' option, but it is fundamentally different from 'revert' in at least two ways to make it questionable:
- 'revert' names a commit that is ancestor of the resulting commit, so an abbreviated object name with human readable title is sufficient to identify the named commit uniquely without using the full object name. On the other hand, 'cherry-pick' usually [*] picks a commit that is not an ancestor. It might be even picking a private commit that never becomes part of the public history.
- The whole commit message of 'cherry-pick' is a copy of the original commit, and there is nothing gained to repeat only the title part on 'cherry-picked from' message.
[*] well, you could revert and then you can pick the original that
was reverted to get back to where you were, but then you can revert the revert to do the same thing.
--- builtin/revert.c | 9 +++++++-- sequencer.c | 2 +- t/t3501-revert-cherry-pick.sh | 6 ++++++ 3 files changed, 14 insertions(+), 3 deletions(-)
builtin/revert.c +7 -2
@@ -116,8 +116,6 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, -OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, -N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;
@@ -132,6 +130,13 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts)OPT_END (), }; options =parse_options_concat (options, cp_extra); + }else if (opts->action ==REPLAY_REVERT ) { +struct option cp_extra[] = { +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )), +OPT_END (), + }; + options =parse_options_concat (options, cp_extra); } argc = parse_options(argc, argv, NULL, options, usage_str,
sequencer.c +1 -1
@@ -221,7 +221,7 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } -if (!strcmp (k,"revert.reference" )) +if (opts->action ==REPLAY_REVERT && !strcmp (k,"revert.reference" )) opts->commit_use_reference =git_config_bool (k, v); status =git_gpg_config (k, v,NULL );
t/t3501-revert-cherry-pick.sh +6 -0
@@ -205,4 +205,10 @@ test_expect_success 'identification of reverted commit (revert.reference)' ' test_cmp expect actual ' +test_expect_success 'cherry-pick is unaware of --reference (for now)' ' + test_when_finished "git reset --hard" && + test_must_fail git cherry-pick --reference HEAD 2>actual && + grep "^usage: git cherry-pick" actual +' + test_done
Signature · 1 line
2.36.1-393-g8f55ede6c2
Hi Junio
Quoted 11 lines · Junio C Hamano
Quoted 4 lines · Phillip Wood
I think the changes to the template message are good. We're still adding "--reference" as a valid option to cherry-pick though which I don't think is a good idea (though in the future we may want to allow "cherry-pick -x --reference")
I love when people notice mistakes that the original author and other people missed, many eyes making all bugs shallow.
I am inclined to apply the following on top. How does it look?
It looks good to me.
Best Wishes
Phillip
Quoted 95 lines
Thanks.
----- >8 --------- >8 --------- >8 --------- >8 -----
Subject: [PATCH] revert: --reference should apply only to 'revert', not 'cherry-pick'As 'revert' and 'cherry-pick' share a lot of code, it is easy to modify the behaviour of one command and inadvertently affect the other. An earlier change to teach the '--reference' option and the 'revert.reference' configuration variable to the former was not careful enough and 'cherry-pick --reference' wasn't rejected as an error.
It is possible to think 'cherry-pick -x' might benefit from the '--reference' option, but it is fundamentally different from 'revert' in at least two ways to make it questionable:
- 'revert' names a commit that is ancestor of the resulting commit, so an abbreviated object name with human readable title is sufficient to identify the named commit uniquely without using the full object name. On the other hand, 'cherry-pick' usually [*] picks a commit that is not an ancestor. It might be even picking a private commit that never becomes part of the public history.
- The whole commit message of 'cherry-pick' is a copy of the original commit, and there is nothing gained to repeat only the title part on 'cherry-picked from' message.
[*] well, you could revert and then you can pick the original that
was reverted to get back to where you were, but then you can revert the revert to do the same thing.Helped-by Phillip Wood <[email protected]>Signed-off-by Junio C Hamano <[email protected]>--- builtin/revert.c | 9 +++++++-- sequencer.c | 2 +- t/t3501-revert-cherry-pick.sh | 6 ++++++ 3 files changed, 14 insertions(+), 3 deletions(-)builtin/revert.c +7
-2@@ -116,8 +116,6 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, -OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, -N_ ("use the 'reference' format to refer to commits" )),OPT_END () };struct option *options = base_options;@@ -132,6 +130,13 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts)OPT_END (), }; options =parse_options_concat (options, cp_extra); + }else if (opts->action ==REPLAY_REVERT ) { +struct option cp_extra[] = { +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, +N_ ("use the 'reference' format to refer to commits" )), +OPT_END (), + }; + options =parse_options_concat (options, cp_extra); } argc = parse_options(argc, argv, NULL, options, usage_str,sequencer.c +1
-1@@ -221,7 +221,7 @@ static int git_sequencer_config(const char *k, const char *v, void *cb)return ret; } -if (!strcmp (k,"revert.reference" )) +if (opts->action ==REPLAY_REVERT && !strcmp (k,"revert.reference" )) opts->commit_use_reference =git_config_bool (k, v); status =git_gpg_config (k, v,NULL );t/t3501-revert-cherry-pick.sh +6
-0@@ -205,4 +205,10 @@ test_expect_success 'identification of reverted commit (revert.reference)' ' test_cmp expect actual ' +test_expect_success 'cherry-pick is unaware of --reference (for now)' ' + test_when_finished "git reset --hard" && + test_must_fail git cherry-pick --reference HEAD 2>actual && + grep "^usage: git cherry-pick" actual +' + test_done
Quoted 8 lines · Junio C Hamano
When this option is in use, the first line of the pre-filled editor buffer becomes a comment line that tells the user to say _why_. If the user exits the editor without touching this line by mistake, what we prepare to become the first line of the body, i.e. "This reverts commit
8fa7f667(do this and that, 2022-04-25)", ends up to be the title of the resulting commit. This behaviour is designed to help such a user to identify such a revert in "git log --oneline" easily so that it can be further reworded with "git rebase -i" later.
This is a good trade-off, and means that the --no-edit case is also preserved. However...
Quoted 14 lines
sequencer.c +6
-4@@ -2167,14 +2184,20 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -strbuf_addstr (&msgbuf,"Revert \"" ); -strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (opts->commit_use_reference) { +strbuf_addstr (&msgbuf, +"# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***" ); + }else { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject);
sequencer.c static int do_pick_commit(struct repository *r, · line 2201
Quoted 10 lines
sequencer.c +5
-1+strbuf_addstr (&msgbuf,"\"" ); + } +strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +refer_to_commit (opts, &msgbuf, commit);if (commit->parents && commit->parents->next) {strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); +refer_to_commit (opts, &msgbuf, parent); }
...the way this is implemented means that we end up with a much more verbose subject line in the case of reverts, which doesn't seem to be intended (or at least not called out in the commit message).
I think a good solution to that would be to e.g. emit:
# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***
Reverts commit <git reference>
This revert of a merge reverts changes made to <git reference 2>.
Instead of what you have, which is:
# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***
This reverts commit <git reference>, reversing changes made to <git reference 2>.
It's sharing a bit less code between the two, but I think the message is suffering for it now.
I.e. the "Revert <reference>" change to "This reverts commit <reference>" doesn't per-se seem intentional, but just a side-effect of the optional "reference" revert's default "subject" line piggy-backing on the non-"reference" body.
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 186
Quoted 8 lines
t/t3501-revert-cherry-pick.sh +8
-0+test_expect_success 'identification of reverted commit (default)' ' + test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git rev-parse HEAD^)." >expect &&
This pattern hides git exit codes & segfaults (I don't remember if I mentioned that in a previous round, I think so...).
Quoted 6 lines
t/t3501-revert-cherry-pick.sh +6
-0+test_expect_success 'identification of reverted commit (--reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect &&
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 205
Quoted 10 lines
t/t3501-revert-cherry-pick.sh +10
-0+ test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (revert.reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual
Also (probably mentioned) I'd find this much easier to read/review if it was using test_cmp, now you need to carefully parse the code to see what the outputs are like exactly, but if we compared the full output...
Quoted 10 lines · Ævar Arnfjörð Bjarmason
I think a good solution to that would be to e.g. emit:
# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***
Reverts commit <git reference>
This revert of a merge reverts changes made to <git reference 2>.
Instead of what you have, which is:
Quoted 7 lines
# *** SAY WHY WE ARE REVERTING ON THE TITLE LINE ***
This reverts commit <git reference>, reversing changes made to <git reference 2>.
It's sharing a bit less code between the two, but I think the message is suffering for it now.
We shouldn't be making it inconvenient for our primary intended audience.
The real first line is designed to be usable without editing for them. Those who forgets to write the title and ends up with "This reverts ..." as the title can still identify such a commit for the purpose of "rebase -i" and "commit --fixup", and that is good enough for them.
But your version will force the intended audience to remove the "Reverts ..." line, that strikes the balance at the wrong place.
Quoted 11 lines
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 205
Quoted 7 lines
t/t3501-revert-cherry-pick.sh +7
-0+test_expect_success 'identification of reverted commit (revert.reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actualAlso (probably mentioned) I'd find this much easier to read/review if it was using
test_cmp, now you need to carefully parse the code to see what the outputs are like exactly, but if we compared the full output...
We are using test_cmp. 'actual' has what we care about (i.e. what does the line that begin with "This reverts " say?) and compares it with what we expect to see in 'expect'.
Side effects in Git's test suite, was Re: [PATCH] revert: optionally refer to commit in the "reference" format
In reply to Junio C HamanoHi Junio,
Quoted 19 lines · Junio C Hamano
Quoted 4 lines · Johannes Schindelin
Quoted 4 lines
t/t3501-revert-cherry-pick.sh +4
-0+test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw &&Quoted 8 lines
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 197
Quoted 4 lines
t/t3501-revert-cherry-pick.sh +4
-0+ grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +'If it was up to me, I would combine these three test cases, if only to help the
--run=<single-number>case (the latter two depend on the side effect of the first one to create ato-identtag).I wonder if our prereq infrastructure is lightweight and scalable enough so that we can easily add a support a pseudo-prerequisite PREVIOUS that lets us say
Quoted 6 lines
test_expect_success PREVIOUS "identification ..." ' ... 'to mean that this test requires the previous test has not been skipped.
In theory, this sounds good to me.
In practice, however, side effects are awful and make everything harder, from developing code to debugging to helping new contributors. I wish we would do away with them altogether and have something more akin to the before/after constructs known from e.g. TestNG (think @BeforeTest and @BeforeClass).
One option would be to mark setup steps completely differently, sort of imitating the prereq infrastructure instead of using test_expect_success. Kind of prereqs, but required to pass.
This could potentially allow us to randomize the order in which the test cases are run, to identify and fix (unintended) side effects.
A complication is that we have nothing in the way of @AfterClass, i.e. we do not have a way to, say, run an Apache instance for the lifecycle of a given test script _and tear it down at the end_.
Another, rather obvious complication is that we have 17 years of commit history introducing side effects left and right :laughing:
Ciao,
Dscho
Re: Side effects in Git's test suite, was Re: [PATCH] revert: optionally refer to commit in the "reference" format
Quoted 38 lines · Johannes Schindelin
Hi Junio,
Quoted 19 lines · Junio C Hamano
Quoted 4 lines · Johannes Schindelin
Quoted 4 lines
t/t3501-revert-cherry-pick.sh +4
-0+test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw &&Quoted 8 lines
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 197
Quoted 4 lines
t/t3501-revert-cherry-pick.sh +4
-0+ grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +'If it was up to me, I would combine these three test cases, if only to help the
--run=<single-number>case (the latter two depend on the side effect of the first one to create ato-identtag).I wonder if our prereq infrastructure is lightweight and scalable enough so that we can easily add a support a pseudo-prerequisite PREVIOUS that lets us say
Quoted 6 lines
test_expect_success PREVIOUS "identification ..." ' ... 'to mean that this test requires the previous test has not been skipped.
In theory, this sounds good to me.
In practice, however, side effects are awful and make everything harder, from developing code to debugging to helping new contributors. I wish we would do away with them altogether and have something more akin to the before/after constructs known from e.g. TestNG (think
@BeforeTestand@BeforeClass).
Quoted 3 lines
One option would be to mark
setupsteps completely differently, sort of imitating the prereq infrastructure instead of usingtest_expect_success. Kind of prereqs, but required to pass.
I've suggested a test_expect_setup before:
https://lore.kernel.org/git/[email protected]/;
basically a test_expect_success that ignores GIT_SKIP_TESTS and --run.
I think that even if we could imagine much more complex relationships (up to and including writing these tests as Makefiles instead) it's better to just have the simpler "this is a setup".
Then for everything more complex be more eager to split up tests.
Quoted 2 lines
This could potentially allow us to randomize the order in which the test cases are run, to identify and fix (unintended) side effects.
Yes, a "chaos monkey" mode similar to --stress would be nice.
Quoted 3 lines
A complication is that we have nothing in the way of
@AfterClass, i.e. we do not have a way to, say, run an Apache instance for the lifecycle of a given test script_andtear it down at theend_.
I think this is generally a feature in that if you find yourself needing this you should split the test up so that the Apache setup is in only one file.
E.g. in the case of some http tests we have a prereq on something forgit:// and a different thing (apache) for http:// tests, so that depending on what combination you have we might end up needlessly skipping tests.
Quoted 2 lines
Another, rather obvious complication is that we have 17 years of commit history introducing side effects left and right :laughing:
Quoted 17 lines · Junio C Hamano
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
This reverts commit 8fa7f667 (do this and that, 2022-04-25)so that the title does not have to be
Revert "do this and that"
Quoted 7 lines
We can instead use the title to describe "why" we are reverting the original commit.
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
This is fantastic, I've wanted to fix this particular nit for a long time.
Quoted 21 lines
(quoted diff) +14
-0+static void refer_to_commit(struct replay_opts *opts, + struct strbuf *msgbuf, struct commit *commit) +{ + if (opts->commit_use_reference) { + struct pretty_print_context ctx = { + .abbrev = DEFAULT_ABBREV, + .date_mode.type = DATE_SHORT, + }; + format_commit_message(commit, "%h (%s, %ad)", msgbuf, &ctx); + } else { + strbuf_addstr(msgbuf, oid_to_hex(&commit->object.oid)); + } +} + static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,@@ -2167,14 +2184,19 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label;
Review static int do_pick_commit(struct repository *r, · line 2192
Quoted 10 lines
(quoted diff) +6
-4- strbuf_addstr(&msgbuf, "Revert \""); - strbuf_addstr(&msgbuf, msg.subject); - strbuf_addstr(&msgbuf, "\"\n\nThis reverts commit "); - strbuf_addstr(&msgbuf, oid_to_hex(&commit->object.oid)); + if (!opts->commit_use_reference) { + strbuf_addstr(&msgbuf, "Revert \""); + strbuf_addstr(&msgbuf, msg.subject); + strbuf_addstr(&msgbuf, "\""); + } else { + strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");
Having seen how people use git in the wild, this *WILL* result in a bunch of history where people don't edit that at all.
If we want them to edit something we should come up with a buffer that's empty except for suggested #-commented parts, and suggest that they uncomment/edit some of it.
I also use "git revert --no-edit" in my own workflow, e.g. when reverting back and forth in WIP code, having the OID is useful, having this new "reference" would be even better, but having that just in the body and "DESCRIBE WHY..." in the %s would be much less useful.
Review static int do_pick_commit(struct repository *r, · line 2202
Quoted 11 lines
(quoted diff) +4
-1+ } + strbuf_addstr(&msgbuf, "\n\nThis reverts commit "); + refer_to_commit(opts, &msgbuf, commit); if (commit->parents && commit->parents->next) { strbuf_addstr(&msgbuf, ", reversing\nchanges made to "); - strbuf_addstr(&msgbuf, oid_to_hex(&parent->object.oid)); + refer_to_commit(opts, &msgbuf, parent); } strbuf_addstr(&msgbuf, ".\n"); } else {
This is very POC, but I wish we had something like the WIP diff at the end of this E-Mail (which is a mess, I was experimenting). I.e. we'd always emit (when this setting is enabled)
Revert %h (%s, %ad)
Except that the %s and the rest of the line would use the truncation feature of "git log" formats, and would make sure the line isn't longer than so-and-so, e.g. 72 or 50 characters.
Then only if we truncated things there, or we have parents to mention would we add a body like:
This reverts commit %h (%s, %ad)
Followed by "reversing changes..."
All of which would be much easier than the below monstrosity I came up with if:
1. You could ask "git log" formats to not whitespace pad the truncation, I couldn't find a way to do that (but it's the first time I use it).
2. We just had some generic "wrap this buffer" function, maybe we do, I didn't look much.
Quoted 36 lines
sequencer.h +1
-0@@ -49,6 +49,7 @@ struct replay_opts {int reschedule_failed_exec;int committer_date_is_author_date;int ignore_date; +int commit_use_reference;int mainline;t/t3501-revert-cherry-pick.sh +9
-0@@ -159,6 +159,7 @@ test_expect_success 'cherry-pick works with dirty renamed file' ' ' test_expect_success 'advice from failed revert' ' + test_when_finished "git reset --hard" && test_commit --no-tag "add dream" dream dream && dream_oid=$(git rev-parse --short HEAD) && cat <<-EOF >expected &&@@ -174,4 +175,34 @@ test_expect_success 'advice from failed revert' ' test_must_fail git revert HEAD^ 2>actual && test_cmp expected actual ' + +test_expect_success 'identification of reverted commit (vanilla)' ' + test_commit to-ident && + test_when_finished "git reset --hard to-ident" && + git checkout --detach to-ident && + git revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual &&
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 195
Quoted 10 lines
t/t3501-revert-cherry-pick.sh +10
-0+ echo "This reverts commit $(git rev-parse HEAD^)." >expect && + test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git revert --reference --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect &&
This hides the exit code of the embedded $() git command.
Re the suggested changes below: let's just test_cmp the whole thing, subject+body instead?
t/t3501-revert-cherry-pick.sh test_expect_success 'advice from failed revert' ' · line 208
Quoted 13 lines
t/t3501-revert-cherry-pick.sh +12
-0+ test_cmp expect actual +' + +test_expect_success 'identification of reverted commit (reference)' ' + git checkout --detach to-ident && + git -c revert.reference=true revert --no-edit HEAD && + git cat-file commit HEAD >actual.raw && + grep "^This reverts " actual.raw >actual && + echo "This reverts commit $(git show -s --pretty=reference HEAD^)." >expect && + test_cmp expect actual +' + test_done
sequencer.c +61 -21
@@ -2061,18 +2061,14 @@ static int should_edit(struct replay_opts *opts) {return opts->edit; } -static void refer_to_commit (struct replay_opts *opts, -struct strbuf *msgbuf,struct commit *commit) -{ -if (opts->commit_use_reference) { -struct pretty_print_context ctx = { - .abbrev =DEFAULT_ABBREV , - .date_mode.type =DATE_SHORT , - }; -format_commit_message (commit,"%h (%s, %ad)" , msgbuf, &ctx); - }else { -strbuf_addstr (msgbuf,oid_to_hex (&commit->object.oid)); - } +static void refer_to_commit (struct strbuf *sb,struct commit *commit, +const char *const fmt) +{ +struct pretty_print_context ctx = { + .abbrev =DEFAULT_ABBREV , + .date_mode.type =DATE_SHORT , + }; +format_commit_message (commit, fmt, sb, &ctx); } static int do_pick_commit(struct repository *r,
@@ -2183,19 +2179,63 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label; -if (!opts->commit_use_reference) { +if (opts->commit_use_reference) { +struct strbuf sb_b =STRBUF_INIT ; +struct strbuf sb_h =STRBUF_INIT ; +struct strbuf sb_ad =STRBUF_INIT ; +struct strbuf sb_s =STRBUF_INIT ; +struct strbuf sb_s_t =STRBUF_INIT ; +const size_t wraplen =72 ; +char *fmt; +size_t len = wraplen; +int truncated; + +refer_to_commit (&sb_h, commit,"Revert %h (" ); + len -= sb_h.len; +refer_to_commit (&sb_ad, commit,"%ad)" ); + len -= sb_ad.len; + len -=2 ;/* The ", " in: Revert %h (%s, %ad) */ +/* vanilla %h (%s, %ad) */ +refer_to_commit (&sb_s, commit,"%s" ); + +/* truncated %h (%s, %ad) */ + fmt =xstrfmt ("%%<(%d,trunc)%%s" , (int )len); +refer_to_commit (&sb_s_t, commit, fmt); +free (fmt); +strbuf_rtrim (&sb_s_t); + + truncated =strcmp (sb_s.buf, sb_s_t.buf); + +strbuf_addbuf (&msgbuf, &sb_h); +strbuf_addbuf (&msgbuf, &sb_s_t); +strbuf_addbuf (&msgbuf, &sb_ad); +strbuf_addstr (&msgbuf,"\n\n" ); + +if (truncated) { +const char *pfx ="This reverts commit " ; +size_t len = wraplen -strlen (pfx);/* TODO: Consider %h etc. */ +char *fmt; + + fmt =xstrfmt ("%s%%h (%%w(%d,0,0)%%s, %%ad)" , + pfx, (int )len); +refer_to_commit (&sb_b, commit, fmt); +free (fmt); +strbuf_addbuf (&msgbuf, &sb_b); + }else { +/* TODO: The not-truncated version ... */ + } + }else {strbuf_addstr (&msgbuf,"Revert \"" );strbuf_addstr (&msgbuf, msg.subject);strbuf_addstr (&msgbuf,"\"" ); - }else { -strbuf_addstr (&msgbuf,"DESCRIBE WHY WE ARE REVERTING HERE" ); - } -strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); -refer_to_commit (opts, &msgbuf, commit); +strbuf_addstr (&msgbuf,"\n\nThis reverts commit " ); +strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); -if (commit->parents && commit->parents->next) { -strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); -refer_to_commit (opts, &msgbuf, parent); +if (commit->parents && commit->parents->next) { +/* TODO: Handle the wrapping of this too... */ +strbuf_addstr (&msgbuf,", reversing\nchanges made to " ); +strbuf_addstr (&msgbuf,oid_to_hex (&parent->object.oid)); + } }strbuf_addstr (&msgbuf,".\n" ); }else {
Quoted 9 lines · Ævar Arnfjörð Bjarmason
Review
Quoted 6 lines
(quoted diff) +6
-0+ if (!opts->commit_use_reference) { + strbuf_addstr(&msgbuf, "Revert \""); + strbuf_addstr(&msgbuf, msg.subject); + strbuf_addstr(&msgbuf, "\""); + } else { + strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");Having seen how people use git in the wild, this *WILL* result in a bunch of history where people don't edit that at all.
It was done very much on purpose. A pressure from other project participants against the ugly all caps content-free message will help instill better behaviour. A solo developer also will learn after making reverts with content-free titles (and if they do not find it inconvenient for their development purpose that their history is full of content-free titles shouting in all caps, then more power to them---if they are happy, we are happy, too).
If we leave something like
# Add one line above and explain not *what* this revert did, # but *why* you decided to revert in 50-70 chars. Did it # break something? Was it premature?
This reverts commit 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21)
presumably, stripspace will make the "This reverts commit ..." the title of the reverted commit. It would invite people not to edit it out out of laziness. Since the whole point of this change is to encourage people to describe the reason behind the revert on the subject line, such an invitation is counter-productive.
Doing the first two lines like so:
Revert 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21) # Edit the above line to explain not *what* this revert did,
would have pretty much the same effect, I am afraid.
So...
Quoted 12 lines · Junio C Hamano
Quoted 9 lines · Ævar Arnfjörð Bjarmason
Review
Quoted 6 lines
(quoted diff) +6
-0+ if (!opts->commit_use_reference) { + strbuf_addstr(&msgbuf, "Revert \""); + strbuf_addstr(&msgbuf, msg.subject); + strbuf_addstr(&msgbuf, "\""); + } else { + strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");Having seen how people use git in the wild, this *WILL* result in a bunch of history where people don't edit that at all.
Quoted 3 lines
It was done very much on purpose. A pressure from other project participants against the ugly all caps content-free message will help instill better behaviour.
In some cases that will happen, but from experience of working with a bunch of novice git users some people won't edit these at all, particularly when they're in a rush (e.g. reverting something because a thing broke production).
So making the default subject less useful is something that will be seen by others, and thus result in worse UX.
AFAICT all of the goals you're suggesting here will be even better if it's commented out, then you will need to edit it, and we'll error out by default if you don't. Why not use that?
Quoted 5 lines
A solo developer also will learn
after making reverts with content-free titles (and if they do not find it inconvenient for their development purpose that their history is full of content-free titles shouting in all caps, then more power to them---if they are happy, we are happy, too).
The subject you're replacing isn't content-free, it at least includes the OID, this one doesn't, so you won't see it in --oneline. That's less useful.
Quoted 6 lines
If we leave something like
# Add one line above and explain not *what* this revert did, # but *why* you decided to revert in 50-70 chars. Did it # break something? Was it premature?
Quoted 7 lines
This reverts commit
8aa3f0dc(CI: set CC in MAKEFLAGS directly, 2022-04-21)presumably, stripspace will make the "This reverts commit ..." the title of the reverted commit. It would invite people not to edit it out out of laziness. Since the whole point of this change is to encourage people to describe the reason behind the revert on the subject line, such an invitation is counter-productive.
If that's the concern we could also comment the "This reverts" line.
Quoted 8 lines
Doing the first two lines like so:
Revert 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21) # Edit the above line to explain not *what* this revert did,would have pretty much the same effect, I am afraid.
So...
Ditto, so just present a buffer like:
# Revert 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21)
#
# This reverts commit 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21)Along with some advice that the user can uncomment those template lines & adjust them.
Quoted 3 lines · Ævar Arnfjörð Bjarmason
AFAICT all of the goals you're suggesting here will be even better if it's commented out, then you will need to edit it, and we'll error out by default if you don't. Why not use that?
Simply because I doubt that would work. Doesn't the stripspace on the log message with unedited comments simply discard the commented out part and results in a title that is taken from the line that happens to end up being the first non-blank-non-commented-out line?
Quoted 3 lines
The subject you're replacing isn't content-free, it at least includes the OID, this one doesn't, so you won't see it in --oneline. That's less useful.
I know. That is the point; those who choose to use --reference want to make sure they want to edit out the line that tell them to edit.
Quoted 9 lines
Quoted 9 lines
If we leave something like
# Add one line above and explain not *what* this revert did, # but *why* you decided to revert in 50-70 chars. Did it # break something? Was it premature?
This reverts commit
8aa3f0dc(CI: set CC in MAKEFLAGS directly, 2022-04-21)
Quoted 7 lines
Quoted 5 lines
presumably, stripspace will make the "This reverts commit ..." the title of the reverted commit. It would invite people not to edit it out out of laziness. Since the whole point of this change is to encourage people to describe the reason behind the revert on the subject line, such an invitation is counter-productive.
If that's the concern we could also comment the "This reverts" line.
That punishes the normal use case where the title is edited and the body is used to start the message as-is.
Hi Junio
Quoted 17 lines · Junio C Hamano
A typical "git revert" commit uses the full title of the original commit in its title, and starts its body of the message with:
This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.This does not encourage the best practice of describing not just "what" (i.e. "Revert X" on the title says what we did) but "why" (i.e. and it does not say why X was undesirable).
We can instead phrase this first line of the body to be more like
This reverts commit 8fa7f667 (do this and that, 2022-04-25)so that the title does not have to be
Revert "do this and that"
Quoted 7 lines
We can instead use the title to describe "why" we are reverting the original commit.
Introduce the "--reference" option to "git revert", and also the revert.reference configuration variable, which defaults to false, to tweak the title and the first line of the draft commit message for when creating a "revert" commit.
I think this is a good idea which will hopefully improve project histories.
builtin/revert.c static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) · line 120
Quoted 10 lines
builtin/revert.c +2
-0@@ -116,6 +116,8 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts) N_("option for merge strategy"), option_parse_x), {OPTION_STRING ,'S' ,"gpg-sign" , &opts->gpg_sign,N_ ("key-id" ), N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, +OPT_BOOL (0 ,"reference" , &opts->commit_use_reference, + N_("use the 'reference' format to refer to commits")),
This option is being added to base_options which applies to cherry-pick as well as revert. There is a "if" statement just below this hunk which adds cherry-pick specific options, I think we want to add this new option in an else block added to that "if" statement.
Quoted 7 lines
builtin/revert.c +0
-0static int do_pick_commit(struct repository *r, struct todo_item *item, struct replay_opts *opts,@@ -2167,14 +2184,19 @@ static int do_pick_commit(struct repository *r, base_label = msg.label; next = parent; next_label = msg.parent_label;
builtin/revert.c static int do_pick_commit(struct repository *r, · line 2192
Quoted 10 lines
builtin/revert.c +6
-4-strbuf_addstr (&msgbuf,"Revert \"" ); -strbuf_addstr (&msgbuf, msg.subject); -strbuf_addstr (&msgbuf,"\"\n\nThis reverts commit " ); -strbuf_addstr (&msgbuf,oid_to_hex (&commit->object.oid)); +if (!opts->commit_use_reference) { +strbuf_addstr (&msgbuf,"Revert \"" ); +strbuf_addstr (&msgbuf, msg.subject); +strbuf_addstr (&msgbuf,"\"" ); + }else { +strbuf_addstr (&msgbuf,"DESCRIBE WHY WE ARE REVERTING HERE" );
In format-patch we add three asterisks to the beginning and end of the dummy subject and body lines to encourage the user to edit them - is that worth doing here as well?
Best Wishes
Phillip
Quoted 3 lines · Phillip Wood
In format-patch we add three asterisks to the beginning and end of the dummy subject and body lines to encourage the user to edit them - is that worth doing here as well?
Yeah, that would make things consistent.
I am still mulling over Ævar's idea of preparing the messsage in such a way that, if committed without editing, the title becomes identifiable but too ugly to force users consider rewording (and the "identifiable" part helps the "rebase -i" process), while making it easy to discard the instruction for the user who do want to edit. I think that is the right approach, if we can find one. What has been floated on the list during the discussion is not there yet, but I think the approach is a good one.
Thanks.
Am 22.05.22 um 06:32 schrieb Junio C Hamano:
Quoted 16 lines
--- Documentation/config/revert.txt | 3 +++ Documentation/git-revert.txt | 9 +++++++++ builtin/revert.c | 2 ++ sequencer.c | 32 +++++++++++++++++++++++++++----- sequencer.h | 1 + t/t3501-revert-cherry-pick.sh | 31 +++++++++++++++++++++++++++++++ 6 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 Documentation/config/revert.txtDocumentation/config/revert.txt new file +0
-0
Documentation/config/revert.txt line 3
Quoted 3 lines
Documentation/config/revert.txt new file +3
-0@@ -0,0 +1,3 @@ +revert.reference:: + Setting this variable to true makes `git revert` to behave + as if the `--reference` option is given.
Shouldn't this be "were" instead of "is"? Not fully sure. Anyway:
--- >8 ---
Subject: [PATCH] revert: config documentation fixes
43966ab315 (revert: optionally refer to commit in the "reference" format, 2022-05-26) added the documentation file config/revert.txt. Actually include it in config.txt.
Make is used with a bare infinitive after the object; remove the "to".
--- Documentation/config.txt | 2 ++ Documentation/config/revert.txt | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-)
Documentation/config.txt +2 -0
@@ -495,6 +495,8 @@ include::config/repack.txt[] include::config/rerere.txt[] +include::config/revert.txt[] + include::config/safe.txt[] include::config/sendemail.txt[]
Documentation/config/revert.txt +1 -1
@@ -1,3 +1,3 @@ revert.reference:: - Setting this variable to true makes `git revert` to behave + Setting this variable to true makes `git revert` behave as if the `--reference` option is given.
--
2.36.1
Quoted 3 lines · René Scharfe
Actually include it in config.txt.
Make is used with a bare infinitive after the object; remove the "to".
Thanks.