Re: [PATCH v3 2/2] blame: document --color-* options

From: Eric Sunshine <sunshine@sunshineco.com>
To: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Git List <git@vger.kernel.org>,
	Junio C Hamano <gitster@pobox.com>,
	Stefan Beller <stefanbeller@gmail.com>,
	"Dr . Matthias St . Pierre" <m.st.pierre@ncp-e.com>
Subject: Re: [PATCH v3 2/2] blame: document --color-* options
Date: Fri, 1 Oct 2021 15:10:14 -0400	[thread overview]
Message-ID: <CAPig+cSWutBRQK+Qy=nkaDZRvy4trVNPuo+cF-quC2rBwNe2fw@mail.gmail.com> (raw)
In-Reply-To: <20211001113725.13354-3-bagasdotme@gmail.com>

On Fri, Oct 1, 2021 at 7:38 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> Commit cdc2d5f11f1a (builtin/blame: dim uninteresting metadata lines,
> 2018-04-23) and 25d5f52901f0 (builtin/blame: highlight recently changed
> lines, 2018-04-23) introduce --color-lines and --color-by-age options to
> git blame, respectively. While both options are mentioned in usage help,
> they aren't documented in git-blame(1). Document them.
>
> Co-authored-by: Dr. Matthias St. Pierre <m.st.pierre@ncp-e.com>
> Signed-off-by: Dr. Matthias St. Pierre <m.st.pierre@ncp-e.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
> diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
> @@ -136,5 +136,17 @@ take effect.
> +--color-lines::
> +       Color lines differently, if they come from the same commit as the preceding line.

Drop the comma: s/differently,/differently/

> +       This facilitates distinguishing code blocks introduced by different commits.

Taking non-native English speakers into account, perhaps:
s/facilitates distinguishing/makes it easier to distinguish/

> +       The color defaults to cyan and be adjusted using the `color.blame.repeatedLines`

s/and be/and can be/

> +       config option. Only the line annotation (see "The Default Format" section)
> +       is colored.

You can drop the last sentence entirely if you start the blurb like this:

    Color line annotations differently, if...

> +--color-by-age::
> +       Color lines depending on the age of the line. The `color.blame.highlightRecent`
> +       config option controls what color is used for which range of age. Only the
> +       line annotation (see "The Default Format" section) is colored.

Ditto about dropping the last sentence.

    Color line annotations depending upon the age of the line.

> diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
> @@ -9,8 +9,8 @@ color.advice.hint::
>  color.blame.highlightRecent::
> -       This can be used to color the metadata of a blame line depending
> -       on age of the line.
> +       Used to color line annotations differently depending on the age of the commit
> +       (`git blame --color-by-age`).

This can be tightened up:

    Specify the line annotation color depending upon the age
    of the commit (`git blame...`).

> @@ -20,15 +20,15 @@ before the given timestamp, overwriting older timestamped colors.
>  color.blame.repeatedLines::
> -       Use the customized color for the part of git-blame output that
> -       is repeated meta information per line (such as commit id,
> -       author name, date and timezone). Defaults to cyan.
> +       Use the specified color to colorize line annotations, if they come from the
> +       same commit as the preceding line (`git blame --color-lines`). Defaults to
> +       cyan.

Likewise:

    Specify the line annotation color for lines which
    originate with the same commit (`git blame...`).