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

From: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
Date: Mar 18, 2025, 11:43 UTC
Message-ID: <Z9lcXR6sL3UWlL33@ugly>
In-Reply-To: <Z9iVVD988M4XUyYO@nand.local>

On Mon, Mar 17, 2025 at 01:17:54PM -0700, Junio C Hamano wrote:

Show 9 quoted lines

>Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes:
>
>> -If set to "auto", `git-commit` would select a character that is not
>> -the beginning character of any line in existing commit messages.
>
>This is so far in the past but I suspect this was deliberately left
>vague so that we can add (or subtract) the set of possible letters
>to use.
>

no such consideration was voiced at any point. https://lore.kernel.org/git/CALy3b+m7YkYB+mPEnAQnjKFAwUS_PqCUFtuxzN7hwhmNfMrw3Q@mail.gmail.com/T/#u

On Mon, Mar 17, 2025 at 05:34:12PM -0400, Taylor Blau wrote:

Show 8 quoted lines

>I had a similar thought while reading. The vague wording of the
>existing
>text gives us freedom to change that set of characters in the code
>without the possibility of the documentation becoming stale.
>
>That's pretty academic, though, so I don't have a strong feeling against
>this portion of the patch, but I do vaguely prefer the existing wording.
>

apart from changing it being academic, the feature is also formally useless without documenting the candidate comment characters. formally, because in practice the user would just guess, but that doesn't make the omission a good thing.

On Mon, Mar 17, 2025 at 01:17:54PM -0700, Junio C Hamano wrote:

Show 19 quoted lines

>> +Note that this makes it impossible to include comments in the
>> +prepare-commit-msg hook's output or the commit message template.
>
>Care to rephrase?  There are degrees of possibilities and "makes it
>impossible" is being overly broad.
>
>I suspect you are saying that it is not nice to make it the
>responsibility of the end-user who chooses "auto" to ensure that
>they adjust the default '#' comments injected from the template or
>hook output when
>
> - they have a line that begins with '#' in their message;
> - the "auto" mechanism chooses to use ';' as the comment character;
> - the template is written assuming '#' as the comment character and
>   has comments.
>
>before making a commit.  But "this makes it impossible" does not
>quite convey that to casual readers.
>

no, i meant what i wrote: it makes it _literally_ impossible. it follows from the preceding sentence that _whatever_ is in the template will NOT be the comment char. the commit that introduced that feature (84c9dc2c5) already mentioned that limitation.

reading through the thread of the original submission, the feature is a workaround for `commit -m` and `commit --amend` being inconsistent wrt. message washing. i find it surprising that this patch didn't get any push-back, even though the thread mentioned the correct way to enforce consistency (use --amend with --no-edit), and the fact that the user should have set the commentChar to non-'#' even if his primary method to create commit messages was with -m. i don't see how (or why) anyone would integrate this option into any practical workflow, and therefore consider it a mis-feature that should be done away with. but knowing how people here react to such proposals, it seems most practical to document the feature sufficiently well to enable users to easily draw the conclusion that it is, in fact, nonsense.