[PATCH v2 0/2] blame: documentation update

From: Bagas Sanjaya <hidden>
Date: 2021-09-29 12:49:52

Document the default output format for git-blame(1), as well as the
--color-* options which are currently undocumented but mentioned in
usage help.

Bagas Sanjaya (2):
  blame: Describe default output format
  blame: document --color-* options

 Documentation/blame-options.txt | 12 ++++++++++++
 Documentation/config/color.txt  | 12 ++++++------
 Documentation/git-blame.txt     | 16 ++++++++++++++--
 3 files changed, 32 insertions(+), 8 deletions(-)


base-commit: cefe983a320c03d7843ac78e73bd513a27806845
-- 
An old man doll... just what I always wanted! - Clara

[PATCH v2 1/2] blame: Describe default output format

From: Bagas Sanjaya <hidden>
Date: 2021-09-29 12:49:53

While there is descriptions for porcelain and incremental output
formats, the default format isn't described. Describe that format for
the sake of completeness.

Signed-off-by: Bagas Sanjaya <redacted>
---
 Documentation/git-blame.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 3bf5d5d8b4..284aa99942 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt

@@ -93,6 +93,18 @@ include::blame-options.txt[]
 	is used for a caret to mark the boundary commit.
 
 
+THE DEFAULT FORMAT
+------------------
+
+When neither `--porcelain` nor `--incremental` option is specified,
+`git blame` will output inline annotation for each line with:
+
+- abbreviated SHA-1 of the commit the line is attributed to;
+- author name (or author email if `-e` or `--show-email` is specified);
+- author date; and
+- line number
+
+
 THE PORCELAIN FORMAT
 --------------------

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

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

From: Bagas Sanjaya <hidden>
Date: 2021-09-29 12:49:54

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 | 12 ++++++++++++
 Documentation/config/color.txt  | 12 ++++++------
 Documentation/git-blame.txt     |  4 ++--
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index 117f4cf806..791214a3b1 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt

@@ -136,5 +136,17 @@ take effect.
 	option.  An empty file name, `""`, will clear the list of revs from
 	previously processed files.
 
+--color-lines::
+	Color lines differently, if they belong to the same commit as the preceding line.
+	This facilitates distinguishing code blocks introduced by different commits.
+	The color defaults to cyan and be adjusted using the `color.blame.repeatedLines`
+	config option. Only the line annotation (see "The Default Format" section)
+	is colored.
+
+--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.
+
 -h::
 	Show help message.

diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
index e05d520a86..b4c120d737 100644
--- a/Documentation/config/color.txt
+++ b/Documentation/config/color.txt

@@ -9,8 +9,8 @@ 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.
+	Used to color line annotations differently depending on the age of the commit
+	(`git blame --color-by-age`).
 +
 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.

@@ -20,15 +20,15 @@ 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.
 +
-It defaults to 'blue,12 month ago,white,1 month ago,red', which colors
+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, if they belong to the
+	same commit as the preceding line (`git blame --color-lines`). 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 284aa99942..2dafeb7710 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

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help