Re: [PATCH] CodingGuidelines: document formatting required by generate-configlist.sh.

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 3, 2025, 14:54 UTC
Message-ID: <xmqqiklcri3o.fsf@gitster.g>
In-Reply-To: <45c586122afab8ae3624be6963d64e770b7396b2.1748911713.git.collin.funk1@gmail.com>

Collin Funk <collin.funk1@gmail.com> writes:

Show 5 quoted lines

> + When documenting multiple related `git config` variables, place them on
> + a separate line instead of separating them by commas. For example:
> +   core.var1::
> +   core.var2::
> +  	This is a description of 'core.var1' and 'core.var2'.

As `core.varN` in the above example are all what the end-user would give literally, just like `git config` command name in the first sentence, they should be marked up as literal strings, i.e.

    ... For example, do not write this:

    `core.var1`, `core.var2`::
	Description common to `core.var1` and `core.var2`.
	
    Instead write this:

    `core.var1`::
    `core.var2`::
	Description common to `core.var1` and `core.var2`.

> +This format is required for the `generate-configlist.sh` script to
> +properly generate "config-list.h".

It is not wrong per-se, but this tempts people to "fix" the generate-configlist.sh script so that it can grok the comma separated list "again". And when that fix is done and reviewed carelessly, we'd again break some implementations of sed the same way and we will come back full circle ;-)

When we standardized writing negatable options this way

    `--option`::
    `--no-option`::
	Description of `--option` that can be turned off with
	`--no-option`.

instead of

    `--[no-]option`::
	Description of `--option` that can be turned off with
	`--no-option`.

we explained that the reason why we want to do so is because it is easier to "grep". Does this "do not comma-list variables, but list them one per line" also give us better greppability, and if so we want to explain that way, perhaps?

    $ git grep '`core\.var1`::' Documentation/config/

Thanks.