On Fri, Oct 1, 2021 at 7:38 AM Bagas Sanjaya <bagasdotme@xxxxxxxxx> 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@xxxxxxxxx>
> Signed-off-by: Dr. Matthias St. Pierre <m.st.pierre@xxxxxxxxx>
> Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
> ---
> 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...`).
