[PATCH v5 2/2] blame: document --color-* options
flat view
STALE1813d
From: Bagas Sanjaya <hidden>
Date: 2021-10-08 09:16:38
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Revision v5 of 5 in this series.
Revisions (5)
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> --- Documentation/blame-options.txt | 11 +++++++++++ Documentation/config/color.txt | 33 ++++++++++++++++++--------------- Documentation/git-blame.txt | 4 ++-- 3 files changed, 31 insertions(+), 17 deletions(-)
diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index 117f4cf806..fa3104d954 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt@@ -136,5 +136,16 @@ take effect. option. An empty file name, `""`, will clear the list of revs from previously processed files. +--color-lines:: + Color line annotations, in the default format, differently if they come from + the same commit as the preceding line. This makes it easier to distinguish + code blocks introduced by different commits. The color defaults to cyan and + can be adjusted using the `color.blame.repeatedLines` config option. + +--color-by-age:: + Color line annotations depending on the age of the line, in the default format. + The `color.blame.highlightRecent` config option controls what color is used for + each range of age. + -h:: Show help message.
diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
index e05d520a86..dd2d2e0d84 100644
--- a/Documentation/config/color.txt
+++ b/Documentation/config/color.txt@@ -9,26 +9,29 @@ color.advice.hint:: Use customized color for hints. color.blame.highlightRecent:: - This can be used to color the metadata of a blame line depending - on age of the line. + Specify the line annotation color for `git blame --color-by-age` + depending upon the age of the line. + -This setting should be set to a comma-separated list of color and date settings, -starting and ending with a color, the dates should be set from oldest to newest. -The metadata will be colored given the colors if the line was introduced -before the given timestamp, overwriting older timestamped colors. +This setting should be set to a comma-separated list of color and +date settings, starting and ending with a color, the dates should be +set from oldest to newest. The metadata will be colored with the +specified colors if the line was introduced before the given +timestamp, overwriting older timestamped colors. + + -Instead of an absolute timestamp relative timestamps work as well, e.g. -2.weeks.ago is valid to address anything older than 2 weeks. +Instead of an absolute timestamp relative timestamps work as well, +e.g. `2.weeks.ago` is valid to address anything older than 2 weeks. + + -It defaults to 'blue,12 month ago,white,1 month ago,red', which colors -everything older than one year blue, recent changes between one month and -one year old are kept white, and lines introduced within the last month are -colored red. +It defaults to `blue,12 month ago,white,1 month ago,red`, which +colors everything older than one year blue, recent changes between +one month and one year old are kept white, and lines introduced +within the last month are colored red. 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 for + `git blame --color-lines`, if they come from the same commit as the + preceding line. Defaults to cyan. color.branch:: A boolean to enable/disable color in the output of
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 08008f4a60..e03029fb99 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt@@ -11,8 +11,8 @@ SYNOPSIS 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--ignore-rev <rev>] [--ignore-revs-file <file>] - [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>] - [--] <file> + [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>] + [<rev> | --contents <file> | --reverse <rev>..<rev>] [--] <file> DESCRIPTION -----------
--
An old man doll... just what I always wanted! - Clara