{"thread":{"id":"56664","subject":"[PATCH v5 0/2] blame: documentation update","startedAt":"2021-10-08T09:16:32Z","lastAt":"2021-10-20T15:35:10Z","messageCount":7,"participants":["Bagas Sanjaya","Junio C Hamano","Ævar Arnfjörð Bjarmason","Jeff King"],"isPatch":true,"patchVersion":5,"patchTotal":2},"messages":[{"id":"438285","messageId":"20211008091614.732584-1-bagasdotme@gmail.com","threadId":"56664","inReplyTo":null,"subject":"[PATCH v5 0/2] blame: documentation update","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-08T09:16:12Z","receivedAt":"2021-10-08T09:16:32Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Document the default output format for git-blame(1), as well as the\n--color-* options which are currently undocumented but mentioned in\nusage help.\n\nBagas Sanjaya (2):\n blame: describe default output format\n blame: document --color-* options\n\n Documentation/blame-options.txt | 11 +++++++++++\n Documentation/config/color.txt | 33 ++++++++++++++++++---------------\n Documentation/git-blame.txt | 17 +++++++++++++++--\n 3 files changed, 44 insertions(+), 17 deletions(-)\n\n(NOTE: This is resend of\nhttps://lore.kernel.org/git/20211008043343.189651-1-bagasdotme@gmail.com/T/#t,\ndue to forgetting to mark the linked patchset as v5. Sorry for that).\n\nbase-commit: 106298f7f9cca4158a980de149ef217751e1f943\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438286","messageId":"20211008091614.732584-2-bagasdotme@gmail.com","threadId":"56664","inReplyTo":"20211008091614.732584-1-bagasdotme@gmail.com","subject":"[PATCH v5 1/2] blame: describe default output format","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-08T09:16:13Z","receivedAt":"2021-10-08T09:16:34Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"While there is descriptions for porcelain and incremental output\nformats, the default format isn't described. Describe that format for\nthe sake of completeness.\n\nSigned-off-by: Bagas Sanjaya \n---\n Documentation/git-blame.txt | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex 3bf5d5d8b4..08008f4a60 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -93,6 +93,19 @@ include::blame-options.txt[]\n \tis used for a caret to mark the boundary commit.\n \n \n+THE DEFAULT FORMAT\n+------------------\n+\n+When neither `--porcelain` nor `--incremental` option is specified,\n+`git blame` will output annotation for each line with:\n+\n+- abbreviated object name for the commit the line came from;\n+- author ident (by default author name and date, unless `-s` or `-e` is\n+specified); and\n+- line number\n+\n+before the line contents.\n+\n THE PORCELAIN FORMAT\n --------------------\n \n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438287","messageId":"20211008091614.732584-3-bagasdotme@gmail.com","threadId":"56664","inReplyTo":"20211008091614.732584-1-bagasdotme@gmail.com","subject":"[PATCH v5 2/2] blame: document --color-* options","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-08T09:16:14Z","receivedAt":"2021-10-08T09:16:38Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Commit cdc2d5f11f1a (builtin/blame: dim uninteresting metadata lines,\n2018-04-23) and 25d5f52901f0 (builtin/blame: highlight recently changed\nlines, 2018-04-23) introduce --color-lines and --color-by-age options to\ngit blame, respectively. While both options are mentioned in usage help,\nthey aren't documented in git-blame(1). Document them.\n\nCo-authored-by: Dr. Matthias St. Pierre \nSigned-off-by: Dr. Matthias St. Pierre \nSigned-off-by: Bagas Sanjaya \n---\n Documentation/blame-options.txt | 11 +++++++++++\n Documentation/config/color.txt | 33 ++++++++++++++++++---------------\n Documentation/git-blame.txt | 4 ++--\n 3 files changed, 31 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt\nindex 117f4cf806..fa3104d954 100644\n--- a/Documentation/blame-options.txt\n+++ b/Documentation/blame-options.txt\n@@ -136,5 +136,16 @@ take effect.\n \toption. An empty file name, `\"\"`, will clear the list of revs from\n \tpreviously processed files.\n \n+--color-lines::\n+\tColor line annotations, in the default format, differently if they come from\n+\tthe same commit as the preceding line. This makes it easier to distinguish\n+\tcode blocks introduced by different commits. The color defaults to cyan and\n+\tcan be adjusted using the `color.blame.repeatedLines` config option.\n+\n+--color-by-age::\n+\tColor line annotations depending on the age of the line, in the default format.\n+\tThe `color.blame.highlightRecent` config option controls what color is used for\n+\teach range of age.\n+\n -h::\n \tShow help message.\ndiff --git a/Documentation/config/color.txt b/Documentation/config/color.txt\nindex e05d520a86..dd2d2e0d84 100644\n--- a/Documentation/config/color.txt\n+++ b/Documentation/config/color.txt\n@@ -9,26 +9,29 @@ color.advice.hint::\n \tUse customized color for hints.\n \n color.blame.highlightRecent::\n-\tThis can be used to color the metadata of a blame line depending\n-\ton age of the line.\n+\tSpecify the line annotation color for `git blame --color-by-age`\n+\tdepending upon the age of the line.\n +\n-This setting should be set to a comma-separated list of color and date settings,\n-starting and ending with a color, the dates should be set from oldest to newest.\n-The metadata will be colored given the colors if the line was introduced\n-before the given timestamp, overwriting older timestamped colors.\n+This setting should be set to a comma-separated list of color and\n+date settings, starting and ending with a color, the dates should be\n+set from oldest to newest. The metadata will be colored with the\n+specified colors if the line was introduced before the given\n+timestamp, overwriting older timestamped colors.\n+\n +\n-Instead of an absolute timestamp relative timestamps work as well, e.g.\n-2.weeks.ago is valid to address anything older than 2 weeks.\n+Instead of an absolute timestamp relative timestamps work as well,\n+e.g. `2.weeks.ago` is valid to address anything older than 2 weeks.\n+\n +\n-It defaults to 'blue,12 month ago,white,1 month ago,red', which colors\n-everything older than one year blue, recent changes between one month and\n-one year old are kept white, and lines introduced within the last month are\n-colored red.\n+It defaults to `blue,12 month ago,white,1 month ago,red`, which\n+colors everything older than one year blue, recent changes between\n+one month and one year old are kept white, and lines introduced\n+within the last month are colored red.\n \n color.blame.repeatedLines::\n-\tUse the customized color for the part of git-blame output that\n-\tis repeated meta information per line (such as commit id,\n-\tauthor name, date and timezone). Defaults to cyan.\n+\tUse the specified color to colorize line annotations for\n+\t`git blame --color-lines`, if they come from the same commit as the\n+\tpreceding line. Defaults to cyan.\n \n color.branch::\n \tA boolean to enable/disable color in the output of\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex 08008f4a60..e03029fb99 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -11,8 +11,8 @@ SYNOPSIS\n 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]\n \t [-L ] [-S ] [-M] [-C] [-C] [-C] [--since=]\n \t [--ignore-rev ] [--ignore-revs-file ]\n-\t [--progress] [--abbrev=] [ | --contents | --reverse ..]\n-\t [--] \n+\t [--color-lines] [--color-by-age] [--progress] [--abbrev=]\n+\t [ | --contents | --reverse ..] [--] \n \n DESCRIPTION\n -----------\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438359","messageId":"xmqq7denjkb3.fsf@gitster.g","threadId":"56664","inReplyTo":"20211008091614.732584-1-bagasdotme@gmail.com","subject":"Re: [PATCH v5 0/2] blame: documentation update","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-08T21:09:04Z","receivedAt":"2021-10-08T21:09:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> Document the default output format for git-blame(1), as well as the\n> --color-* options which are currently undocumented but mentioned in\n> usage help.\n\nWill queue. I think we can move this down to 'next'.\n\nThanks.\n"},{"id":"439033","messageId":"patch-1.1-36700e581d2-20211019T123057Z-avarab@gmail.com","threadId":"56664","inReplyTo":"20211008091614.732584-3-bagasdotme@gmail.com","subject":"[PATCH] git config doc: fix recent ASCIIDOC formatting regresison","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-10-19T12:31:34Z","receivedAt":"2021-10-19T12:31:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a regression in 8c328561332 (blame: document --color-* options,\n2021-10-08), which added an extra newline before the \"+\" syntax.\n\nThe \"Documentation/doc-diff HEAD~ HEAD\" output with this applied is:\n\n [...]\n @@ -1815,13 +1815,13 @@ CONFIGURATION FILE\n specified colors if the line was introduced before the given\n timestamp, overwriting older timestamped colors.\n\n - + Instead of an absolute timestamp relative timestamps work as well,\n - e.g. 2.weeks.ago is valid to address anything older than 2 weeks.\n + Instead of an absolute timestamp relative timestamps work as well,\n + e.g. 2.weeks.ago is valid to address anything older than 2 weeks.\n\n - + It defaults to blue,12 month ago,white,1 month ago,red, which colors\n - everything older than one year blue, recent changes between one month\n - and one year old are kept white, and lines introduced within the last\n - month are colored red.\n + It defaults to blue,12 month ago,white,1 month ago,red, which\n + colors everything older than one year blue, recent changes between\n + one month and one year old are kept white, and lines introduced\n + within the last month are colored red.\n\n color.blame.repeatedLines\n Use the specified color to colorize line annotations for git blame\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/color.txt | 2 --\n 1 file changed, 2 deletions(-)\n\ndiff --git a/Documentation/config/color.txt b/Documentation/config/color.txt\nindex dd2d2e0d84e..6e817f60476 100644\n--- a/Documentation/config/color.txt\n+++ b/Documentation/config/color.txt\n@@ -17,11 +17,9 @@ date settings, starting and ending with a color, the dates should be\n set from oldest to newest. The metadata will be colored with the\n specified colors if the line was introduced before the given\n timestamp, overwriting older timestamped colors.\n-\n +\n Instead of an absolute timestamp relative timestamps work as well,\n e.g. `2.weeks.ago` is valid to address anything older than 2 weeks.\n-\n +\n It defaults to `blue,12 month ago,white,1 month ago,red`, which\n colors everything older than one year blue, recent changes between\n-- \n2.33.1.1338.g20da966911a\n\n"},{"id":"439042","messageId":"YW80k4kCPG6VJfW/@coredump.intra.peff.net","threadId":"56664","inReplyTo":"patch-1.1-36700e581d2-20211019T123057Z-avarab@gmail.com","subject":"Re: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-10-19T21:11:47Z","receivedAt":"2021-10-19T21:11:51Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Oct 19, 2021 at 02:31:34PM +0200, Ævar Arnfjörð Bjarmason wrote:\n\n> Fix a regression in 8c328561332 (blame: document --color-* options,\n> 2021-10-08), which added an extra newline before the \"+\" syntax.\n\nThanks, this looks like an obviously correct fix. I think asciidoc's\npickiness around \"+\" has bitten us before. Asciidoctor is more lenient\nhere, and the rendered result looks the same before and after your\npatch, but we should definitely make it look good in both.\n\n> The \"Documentation/doc-diff HEAD~ HEAD\" output with this applied is:\n\nI just want to call this out not only as a good way to review this\npatch, but a great way in general to review any patches which touch\ndocumentation. Running:\n\n doc-diff 8c328561332^ 8c328561332\n\nshows the original problem pretty clearly.\n\n> Documentation/config/color.txt | 2 --\n> 1 file changed, 2 deletions(-)\n\nPatch looks good. There's a small typo in the subject:\n\n> Subject: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison\n\ns/regresison/regression/\n\n-Peff\n"},{"id":"439115","messageId":"xmqq7de7r9p2.fsf@gitster.g","threadId":"56664","inReplyTo":"YW80k4kCPG6VJfW/@coredump.intra.peff.net","subject":"Re: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-20T15:35:05Z","receivedAt":"2021-10-20T15:35:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I just want to call this out not only as a good way to review this\n> patch, but a great way in general to review any patches which touch\n> documentation. Running:\n>\n> doc-diff 8c328561332^ 8c328561332\n>\n> shows the original problem pretty clearly.\n\nI actually was somewhat miffed to see that this did not help an\nupdate being discussed on MyFirstContribution X-<. It could have\nbeen a driver error, though.\n\n>> Documentation/config/color.txt | 2 --\n>> 1 file changed, 2 deletions(-)\n>\n> Patch looks good. There's a small typo in the subject:\n>\n>> Subject: [PATCH] git config doc: fix recent ASCIIDOC formatting regresison\n>\n> s/regresison/regression/\n\nThanks.\n"}]}