Re: [PATCH] blame: document --color-* options

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 28, 2021, 16:22 UTC
Message-ID: <xmqq4ka4n00h.fsf@gitster.g>
In-Reply-To: <fe78329d-07a7-bdf3-2bda-13def35f3de3@gmail.com>

Bagas Sanjaya <bagasdotme@gmail.com> writes:

Show 12 quoted lines

> On 28/09/21 02.44, Junio C Hamano wrote:
>> Nowhere in "git blame --help" output we mention anything about
>> "metadata", so the readers of this new description will be left
>> puzzled what the word means in the context of this command.
>> We would need to pick words or phrases that readers can link easily
>> with the description of "THE PORCELAIN FORMAT" section.
>
> In git-blame(1), we only describe output format for "THE PORCELAIN
> FORMAT" as well as "INCREMENTAL OUTPUT", but not default format.
>
> On the other hand, --color-* options only works on default format, not
> the others.

Sorry for skipping a level of logical progression in the suggestion.

While I do not think we want to add another section for the default format, if we were to add such a section, the new description should use phrases that would have been used, and such a section would not use a new and unclear "metadata" in the description. Instead it would use phrases that the users can look for elsewhere in the same documentation.

What is colored is the summary of the commit the line came from (abbreviated commit object name, plus the author name and time by default) plus the line number, I think.

Thanks.