Re: [PATCH v3 2/2] blame: document --color-* options
From: Eric Sunshine <hidden>
Date: 2021-10-01 19:10:30
On Fri, Oct 1, 2021 at 7:38 AM Bagas Sanjaya [off-list ref] wrote:
quoted hunk ↗ jump to hunk
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 [off-list ref] Signed-off-by: Dr. Matthias St. Pierre <redacted> Signed-off-by: Bagas Sanjaya <redacted> ---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.
quoted hunk ↗ jump to hunk
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...`).
quoted hunk ↗ jump to hunk
@@ -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...`).