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

Bagas Sanjaya [off-list ref] writes:

On 28/09/21 02.44, Junio C Hamano wrote:

quoted

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.

On 28/09/21 23.22, Junio C Hamano wrote:

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.

Stefan mentioned "metadata" term to describe the line annotation, from 
commit cdc2d5f11f1a:

    When using git-blame lots of lines contain redundant information, for
    example in hunks that consist of multiple lines, the metadata (commit
    name, author, date) are repeated. A reader may not be interested in those,
    so offer an option to color the information that is repeated from the
    previous line differently. Traditionally, we use CYAN for lines that
    are less interesting than others (e.g. hunk header), so go with that.

-- 
An old man doll... just what I always wanted! - Clara