Re: [PATCH] docs: clarify meaning of core.commentString=auto

[Phillip Wood <phillip.wood123@gmail.com>]

On 19/03/2025 18:20, Oswald Buddenhagen wrote:
> On Tue, Mar 18, 2025 at 10:15:15AM -0700, Junio C Hamano wrote:
>>> reading through the thread of the original submission, the feature is a
>>> workaround for `commit -m` and `commit --amend` being inconsistent wrt.
>>> message washing.
>>
>> Perhaps somebody can be talked into fixing it ;-)
>>
>> With a clear explanation, I am OK if somebody wants to advocate to
>> deprecate (and remove at Git 3.0 boundary) the "auto" support ;-)

I think that may be best. Looking at the sequencer I don't think 
append_conflicts_hint(), the "fixup" or "squash" commands of "rebase 
-i", or the "--reference" option of "git revert" are compatible with 
core.commentStr=auto. For rebase making it work would mean scanning the 
messages of all the commits to be squash before picking the first one 
which is a pain.

> how would we go about this in practice? just a notice in the docu, or
> some mechanism which would complain at runtime? under what circumstances
> (i.e., how to enable/squelch it)?

I think we'd want to start printing some advice when 
core.commentStr=auto explaining why it has been deprecated and that it 
will be removed when Git 3.0 is released. We should allow that advice to 
be suppressed setting advice.autoCommentStr (other name suggestions 
welcome). We would also want to add an item to BreakingChanges.adoc 
explaining why it is being removed and add "#ifndef 
WITH_BREAKING_CHANGES" around the code that handles core.commentStr=auto 
in builtin/commit.c and guard the documentation with 
"ifdef::with_breaking_changes[]". We may want to make 
core.commentStr=auto an error when breaking changes are enabled as well.

Best Wishes

Phillip