| Message ID | 20230809171531.2564807-2-oswald.buddenhagen@gmx.de (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] sequencer: beautify subject of reverts of reverts | expand |
Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes: > while thinking about what to write, i came up with an idea for another > improvement: with (implicit) --edit, the template message would end up > being: > > This reverts commit <sha1>, > because <PUT REASON HERE>. This sounds great to me. Nit: the "doc: revert: add discussion" subject line should probably be more like "revert doc: suggest adding the 'why' behind reverts". > --- > Documentation/git-revert.txt | 10 ++++++++++ > 1 file changed, 10 insertions(+) > > diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt > index d2e10d3dce..2b52dc89a8 100644 > --- a/Documentation/git-revert.txt > +++ b/Documentation/git-revert.txt > @@ -142,6 +142,16 @@ EXAMPLES > changes. The revert only modifies the working tree and the > index. > > +DISCUSSION > +---------- > + > +While git creates a basic commit message automatically, you really > +should not leave it at that. In particular, it is _strongly_ > +recommended to explain why the original commit is being reverted. > +Repeatedly reverting reversions yields increasingly unwieldy > +commit subjects; latest when you arrive at 'Reapply "Reapply > +"<original subject>""' you should get creative. The word "latest" here sounds odd. Ditto for "get creative". How about the following rewording? While git creates a basic commit message automatically, it is _strongly_ recommended to explain why the original commit is being reverted. In addition, repeatedly reverting the same commit will result in increasingly unwieldy subject lines, for example 'Reapply "Reapply "<original subject>""'. Please consider rewording such subject lines to reflect the reason why the original commit is being reapplied again.
Linus Arver <linusa@google.com> writes: > How about > the following rewording? > > While git creates a basic commit message automatically, it is > _strongly_ recommended to explain why the original commit is being > reverted. In addition, repeatedly reverting the same commit will Hmph, "repeatedly reverting the same commit" sounds wrong because strictly speaking there is only 1 "same commit" (the original commit). Perhaps In addition, repeatedly reverting the same progression of reverts will or even In addition, repeatedly reverting the same revert chain will is better here?
On 10/08/2023 22:50, Linus Arver wrote: > Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes: >> +DISCUSSION >> +---------- >> + >> +While git creates a basic commit message automatically, you really >> +should not leave it at that. In particular, it is _strongly_ >> +recommended to explain why the original commit is being reverted. >> +Repeatedly reverting reversions yields increasingly unwieldy >> +commit subjects; latest when you arrive at 'Reapply "Reapply >> +"<original subject>""' you should get creative. > > The word "latest" here sounds odd. Ditto for "get creative". How about > the following rewording? > > While git creates a basic commit message automatically, it is > _strongly_ recommended to explain why the original commit is being > reverted. In addition, repeatedly reverting the same commit will > result in increasingly unwieldy subject lines, for example 'Reapply > "Reapply "<original subject>""'. Please consider rewording such > subject lines to reflect the reason why the original commit is being > reapplied again. That's a good suggestion, I think having the example will help readers understand the issue being described. Best Wishes Phillip
On 10/08/2023 23:00, Linus Arver wrote: > Linus Arver <linusa@google.com> writes: > >> How about >> the following rewording? >> >> While git creates a basic commit message automatically, it is >> _strongly_ recommended to explain why the original commit is being >> reverted. In addition, repeatedly reverting the same commit will > > Hmph, "repeatedly reverting the same commit" sounds wrong because > strictly speaking there is only 1 "same commit" (the original commit). While it isn't strictly accurate I think that wording is easy enough to understand. I think it is hard to find a more accurate wording that isn't too verbose or cumbersome. Best Wishes Phillip > Perhaps > > In addition, repeatedly reverting the same progression of reverts will > > or even > > In addition, repeatedly reverting the same revert chain will > > is better here?
Linus Arver <linusa@google.com> writes: > Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes: > >> while thinking about what to write, i came up with an idea for another >> improvement: with (implicit) --edit, the template message would end up >> being: >> >> This reverts commit <sha1>, >> because <PUT REASON HERE>. > > This sounds great to me. Oh, absolutely. I rarely do a revert myself (other than reverting a premature merge out of 'next'), but giving a better instruction in the commit log editor buffer as template is a very good idea. > Nit: the "doc: revert: add discussion" subject line should probably be more > like "revert doc: suggest adding the 'why' behind reverts". Good suggestion. > The word "latest" here sounds odd. Ditto for "get creative". How about > the following rewording? > > While git creates a basic commit message automatically, it is > _strongly_ recommended to explain why the original commit is being > reverted. In addition, repeatedly reverting the same commit will > result in increasingly unwieldy subject lines, for example 'Reapply > "Reapply "<original subject>""'. Please consider rewording such > subject lines to reflect the reason why the original commit is being > reapplied again. Sounds better, but let me read the remaining discussion first ;-) Thanks.
Phillip Wood <phillip.wood123@gmail.com> writes: > On 10/08/2023 22:50, Linus Arver wrote: >> Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes: >>> +DISCUSSION >>> +---------- >>> + >>> +While git creates a basic commit message automatically, you really >>> +should not leave it at that. In particular, it is _strongly_ >>> +recommended to explain why the original commit is being reverted. >>> +Repeatedly reverting reversions yields increasingly unwieldy >>> +commit subjects; latest when you arrive at 'Reapply "Reapply >>> +"<original subject>""' you should get creative. >> The word "latest" here sounds odd. Ditto for "get creative". How >> about >> the following rewording? >> While git creates a basic commit message automatically, it is >> _strongly_ recommended to explain why the original commit is being >> reverted. In addition, repeatedly reverting the same commit will >> result in increasingly unwieldy subject lines, for example 'Reapply >> "Reapply "<original subject>""'. Please consider rewording such >> subject lines to reflect the reason why the original commit is being >> reapplied again. > > That's a good suggestion, I think having the example will help readers > understand the issue being described. Sounds very good.
On Fri, Aug 11, 2023 at 04:10:55PM +0100, Phillip Wood wrote: >On 10/08/2023 23:00, Linus Arver wrote: >> Linus Arver <linusa@google.com> writes: >> >>> How about >>> the following rewording? >>> >>> While git creates a basic commit message automatically, it is >>> _strongly_ recommended to explain why the original commit is being >>> reverted. In addition, repeatedly reverting the same commit will >> >> Hmph, "repeatedly reverting the same commit" sounds wrong because >> strictly speaking there is only 1 "same commit" (the original commit). > >While it isn't strictly accurate I think that wording is easy enough to >understand. > yes, but why would that be _better_ than saying "repeatedly reverting reversions" like i did? regards
Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes: > On Fri, Aug 11, 2023 at 04:10:55PM +0100, Phillip Wood wrote: >>On 10/08/2023 23:00, Linus Arver wrote: >>> Hmph, "repeatedly reverting the same commit" sounds wrong because >>> strictly speaking there is only 1 "same commit" (the original commit). >> >> While it isn't strictly accurate I think that wording is easy enough >> to understand. >> > yes, but why would that be _better_ than saying "repeatedly reverting > reversions" like i did? To me at least, "repeatedly reverting reversions" sounds more like a riddle, compared to "repeatedly reverting the same commit", whose intent sounds fairly obvious. An explicit mention of "commit", which is a more familiar noun to folks than "reversion", does contribute to it, I suspect. That would be how I explain why one is _better_ over the other, but of course these things are subjective, so I'd rather see us not asking such questions too often: which is more familiar, "commit" vs "reversion", especially to new folks who are starting to use "git" and reading the manual page for "git revert"?
On Sun, Aug 13, 2023 at 03:09:02PM -0700, Junio C Hamano wrote: >Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes: > >> On Fri, Aug 11, 2023 at 04:10:55PM +0100, Phillip Wood wrote: >>>On 10/08/2023 23:00, Linus Arver wrote: >>>> Hmph, "repeatedly reverting the same commit" sounds wrong because >>>> strictly speaking there is only 1 "same commit" (the original commit). >>> >>> While it isn't strictly accurate I think that wording is easy enough >>> to understand. >>> >> yes, but why would that be _better_ than saying "repeatedly reverting >> reversions" like i did? > >To me at least, "repeatedly reverting reversions" sounds more like a >riddle, compared to "repeatedly reverting the same commit", whose >intent sounds fairly obvious. > a more natural way for git users to say it would be "reverting reverts", which i think everyone in the target audience would understand, but it seems linguistically questionable to me. native speakers may want to opine ... >An explicit mention of "commit", which >is a more familiar noun to folks than "reversion", does contribute to >it, I suspect. > yes, but "commit" may be misunderstood, as linus pointed out in his reply to himself. phillip dismissed the concern, but i don't think ambiguity is a good idea in the authoritative documentation. unfortunately, linus' proposed alternatives seem even more like "riddles" to me than what i am proposing. regards
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index d2e10d3dce..2b52dc89a8 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -142,6 +142,16 @@ EXAMPLES changes. The revert only modifies the working tree and the index. +DISCUSSION +---------- + +While git creates a basic commit message automatically, you really +should not leave it at that. In particular, it is _strongly_ +recommended to explain why the original commit is being reverted. +Repeatedly reverting reversions yields increasingly unwieldy +commit subjects; latest when you arrive at 'Reapply "Reapply +"<original subject>""' you should get creative. + CONFIGURATION -------------
The section is inspired by git-commit.txt. Signed-off-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de> --- Cc: Junio C Hamano <gitster@pobox.com> --- while thinking about what to write, i came up with an idea for another improvement: with (implicit) --edit, the template message would end up being: This reverts commit <sha1>, because <PUT REASON HERE>. --- Documentation/git-revert.txt | 10 ++++++++++ 1 file changed, 10 insertions(+)