[PATCH v5 0/2] blame: documentation update

[PATCH v5 0/2] blame: documentation update

[Bagas Sanjaya]

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 | 11 +++++++++++
 Documentation/config/color.txt  | 33 ++++++++++++++++++---------------
 Documentation/git-blame.txt     | 17 +++++++++++++++--
 3 files changed, 44 insertions(+), 17 deletions(-)

(NOTE: This is resend of
https://lore.kernel.org/git/20211008043343.189651-1-bagasdotme@gmail.com/T/#t,
due to forgetting to mark the linked patchset as v5. Sorry for that).

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

[PATCH v5 1/2] blame: describe default output format

[Bagas Sanjaya]

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 <bagasdotme@gmail.com>
---
 Documentation/git-blame.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 3bf5d5d8b4..08008f4a60 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -93,6 +93,19 @@ 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 annotation for each line with:
+
+- abbreviated object name for the commit the line came from;
+- author ident (by default author name and date, unless `-s` or `-e` is
+specified); and
+- line number
+
+before the line contents.
+
 THE PORCELAIN FORMAT
 --------------------
 
-- 
An old man doll... just what I always wanted! - Clara

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

[Bagas Sanjaya]

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>
---
 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

[PATCH] git config doc: fix recent ASCIIDOC formatting regresison

[Ævar Arnfjörð Bjarmason]

Fix a regression in 8c328561332 (blame: document --color-* options,
2021-10-08), which added an extra newline before the "+" syntax.

The "Documentation/doc-diff HEAD~ HEAD" output with this applied is:

    [...]
    @@ -1815,13 +1815,13 @@ CONFIGURATION FILE
                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 specified color to colorize line annotations for git blame

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/config/color.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
index dd2d2e0d84e..6e817f60476 100644
--- a/Documentation/config/color.txt
+++ b/Documentation/config/color.txt
@@ -17,11 +17,9 @@ 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.
-
 +
 It defaults to `blue,12 month ago,white,1 month ago,red`, which
 colors everything older than one year blue, recent changes between
-- 
2.33.1.1338.g20da966911a

Re: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison

[Jeff King]

On Tue, Oct 19, 2021 at 02:31:34PM +0200, Ævar Arnfjörð Bjarmason wrote:

> Fix a regression in 8c328561332 (blame: document --color-* options,
> 2021-10-08), which added an extra newline before the "+" syntax.

Thanks, this looks like an obviously correct fix. I think asciidoc's
pickiness around "+" has bitten us before. Asciidoctor is more lenient
here, and the rendered result looks the same before and after your
patch, but we should definitely make it look good in both.

> The "Documentation/doc-diff HEAD~ HEAD" output with this applied is:

I just want to call this out not only as a good way to review this
patch, but a great way in general to review any patches which touch
documentation. Running:

  doc-diff 8c328561332^ 8c328561332

shows the original problem pretty clearly.

>  Documentation/config/color.txt | 2 --
>  1 file changed, 2 deletions(-)

Patch looks good. There's a small typo in the subject:

> Subject: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison

s/regresison/regression/

-Peff

Re: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I just want to call this out not only as a good way to review this
> patch, but a great way in general to review any patches which touch
> documentation. Running:
>
>   doc-diff 8c328561332^ 8c328561332
>
> shows the original problem pretty clearly.

I actually was somewhat miffed to see that this did not help an
update being discussed on MyFirstContribution X-<.  It could have
been a driver error, though.

>>  Documentation/config/color.txt | 2 --
>>  1 file changed, 2 deletions(-)
>
> Patch looks good. There's a small typo in the subject:
>
>> Subject: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison
>
> s/regresison/regression/

Thanks.

Re: [PATCH v5 0/2] blame: documentation update

[Junio C Hamano]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

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

Will queue.  I think we can move this down to 'next'.

Thanks.