{"thread":{"id":"56622","subject":"[PATCH v3 0/2] blame: documentation update","startedAt":"2021-10-01T11:38:04Z","lastAt":"2021-10-04T11:41:08Z","messageCount":7,"participants":["Bagas Sanjaya","Eric Sunshine","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":2},"messages":[{"id":"437680","messageId":"20211001113725.13354-1-bagasdotme@gmail.com","threadId":"56622","inReplyTo":null,"subject":"[PATCH v3 0/2] blame: documentation update","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-01T11:37:24Z","receivedAt":"2021-10-01T11:38:04Z","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\nChanges since v2 [1]:\n - describe that the default blame format has \"author ident\" (suggested\n by Junio)\n - s/they belong to/they come from/ (suggested by Junio)\n\nBagas Sanjaya (2):\n blame: Describe default output format\n blame: document --color-* options\n\n Documentation/blame-options.txt | 12 ++++++++++++\n Documentation/config/color.txt | 12 ++++++------\n Documentation/git-blame.txt | 17 +++++++++++++++--\n 3 files changed, 33 insertions(+), 8 deletions(-)\n\nRange-diff against v2 [1]:\n1: d6433fc682 ! 1: 2478909d67 blame: Describe default output format\n @@ Documentation/git-blame.txt: include::blame-options.txt[]\n +------------------\n +\n +When neither `--porcelain` nor `--incremental` option is specified,\n -+`git blame` will output inline annotation for each line with:\n ++`git blame` will output annotation for each line with:\n +\n -+- abbreviated SHA-1 of the commit the line is attributed to;\n -+- author name (or author email if `-e` or `--show-email` is specified);\n -+- author date; and\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 --------------------\n2: 5a5ca69012 ! 2: a6f75786ec blame: document --color-* options\n @@ Documentation/blame-options.txt: take effect.\n \tpreviously processed files.\n \n +--color-lines::\n -+\tColor lines differently, if they belong to the same commit as the preceding line.\n ++\tColor lines differently, if they come from the same commit as the preceding line.\n +\tThis facilitates distinguishing code blocks introduced by different commits.\n +\tThe color defaults to cyan and be adjusted using the `color.blame.repeatedLines`\n +\tconfig option. Only the line annotation (see \"The Default Format\" section)\n @@ Documentation/config/color.txt: before the given timestamp, overwriting older ti\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, if they belong to the\n ++\tUse the specified color to colorize line annotations, if they come from the\n +\tsame commit as the preceding line (`git blame --color-lines`). Defaults to\n +\tcyan.\n \n[1]:\nhttps://lore.kernel.org/git/20210929124935.41917-1-bagasdotme@gmail.com/T/#t\n\nbase-commit: cefe983a320c03d7843ac78e73bd513a27806845\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"437681","messageId":"20211001113725.13354-2-bagasdotme@gmail.com","threadId":"56622","inReplyTo":"20211001113725.13354-1-bagasdotme@gmail.com","subject":"[PATCH v3 1/2] blame: Describe default output format","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-01T11:37:25Z","receivedAt":"2021-10-01T11:38:08Z","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..683f8ab0b0 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":"437682","messageId":"20211001113725.13354-3-bagasdotme@gmail.com","threadId":"56622","inReplyTo":"20211001113725.13354-1-bagasdotme@gmail.com","subject":"[PATCH v3 2/2] blame: document --color-* options","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-01T11:37:26Z","receivedAt":"2021-10-01T11:38:10Z","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 | 12 ++++++++++++\n Documentation/config/color.txt | 12 ++++++------\n Documentation/git-blame.txt | 4 ++--\n 3 files changed, 20 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt\nindex 117f4cf806..9f82936bf1 100644\n--- a/Documentation/blame-options.txt\n+++ b/Documentation/blame-options.txt\n@@ -136,5 +136,17 @@ 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 lines differently, if they come from the same commit as the preceding line.\n+\tThis facilitates distinguishing code blocks introduced by different commits.\n+\tThe color defaults to cyan and be adjusted using the `color.blame.repeatedLines`\n+\tconfig option. Only the line annotation (see \"The Default Format\" section)\n+\tis colored.\n+\n+--color-by-age::\n+\tColor lines depending on the age of the line. The `color.blame.highlightRecent`\n+\tconfig option controls what color is used for which range of age. Only the\n+\tline annotation (see \"The Default Format\" section) is colored.\n+\n -h::\n \tShow help message.\ndiff --git a/Documentation/config/color.txt b/Documentation/config/color.txt\nindex e05d520a86..5634f5b800 100644\n--- a/Documentation/config/color.txt\n+++ b/Documentation/config/color.txt\n@@ -9,8 +9,8 @@ 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+\tUsed to color line annotations differently depending on the age of the commit\n+\t(`git blame --color-by-age`).\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@@ -20,15 +20,15 @@ before the given timestamp, overwriting older timestamped colors.\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 +\n-It defaults to 'blue,12 month ago,white,1 month ago,red', which colors\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 \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, if they come from the\n+\tsame commit as the preceding line (`git blame --color-lines`). Defaults to\n+\tcyan.\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 683f8ab0b0..9d7b6003cd 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":"437720","messageId":"CAPig+cSWutBRQK+Qy=nkaDZRvy4trVNPuo+cF-quC2rBwNe2fw@mail.gmail.com","threadId":"56622","inReplyTo":"20211001113725.13354-3-bagasdotme@gmail.com","subject":"Re: [PATCH v3 2/2] blame: document --color-* options","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-10-01T19:10:14Z","receivedAt":"2021-10-01T19:10:30Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Oct 1, 2021 at 7:38 AM Bagas Sanjaya wrote:\n> Commit cdc2d5f11f1a (builtin/blame: dim uninteresting metadata lines,\n> 2018-04-23) and 25d5f52901f0 (builtin/blame: highlight recently changed\n> lines, 2018-04-23) introduce --color-lines and --color-by-age options to\n> git blame, respectively. While both options are mentioned in usage help,\n> they aren't documented in git-blame(1). Document them.\n>\n> Co-authored-by: Dr. Matthias St. Pierre \n> Signed-off-by: Dr. Matthias St. Pierre \n> Signed-off-by: Bagas Sanjaya \n> ---\n> diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt\n> @@ -136,5 +136,17 @@ take effect.\n> +--color-lines::\n> + Color lines differently, if they come from the same commit as the preceding line.\n\nDrop the comma: s/differently,/differently/\n\n> + This facilitates distinguishing code blocks introduced by different commits.\n\nTaking non-native English speakers into account, perhaps:\ns/facilitates distinguishing/makes it easier to distinguish/\n\n> + The color defaults to cyan and be adjusted using the `color.blame.repeatedLines`\n\ns/and be/and can be/\n\n> + config option. Only the line annotation (see \"The Default Format\" section)\n> + is colored.\n\nYou can drop the last sentence entirely if you start the blurb like this:\n\n Color line annotations differently, if...\n\n> +--color-by-age::\n> + Color lines depending on the age of the line. The `color.blame.highlightRecent`\n> + config option controls what color is used for which range of age. Only the\n> + line annotation (see \"The Default Format\" section) is colored.\n\nDitto about dropping the last sentence.\n\n Color line annotations depending upon the age of the line.\n\n> diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt\n> @@ -9,8 +9,8 @@ color.advice.hint::\n> color.blame.highlightRecent::\n> - This can be used to color the metadata of a blame line depending\n> - on age of the line.\n> + Used to color line annotations differently depending on the age of the commit\n> + (`git blame --color-by-age`).\n\nThis can be tightened up:\n\n Specify the line annotation color depending upon the age\n of the commit (`git blame...`).\n\n> @@ -20,15 +20,15 @@ before the given timestamp, overwriting older timestamped colors.\n> color.blame.repeatedLines::\n> - Use the customized color for the part of git-blame output that\n> - is repeated meta information per line (such as commit id,\n> - author name, date and timezone). Defaults to cyan.\n> + Use the specified color to colorize line annotations, if they come from the\n> + same commit as the preceding line (`git blame --color-lines`). Defaults to\n> + cyan.\n\nLikewise:\n\n Specify the line annotation color for lines which\n originate with the same commit (`git blame...`).\n"},{"id":"437743","messageId":"xmqqfstk2woo.fsf@gitster.g","threadId":"56622","inReplyTo":"20211001113725.13354-2-bagasdotme@gmail.com","subject":"Re: [PATCH v3 1/2] blame: Describe default output format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-01T22:43:19Z","receivedAt":"2021-10-01T22:43:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> While there is descriptions for porcelain and incremental output\n> formats, the default format isn't described. Describe that format for\n> the sake of completeness.\n>\n> Signed-off-by: Bagas Sanjaya \n> ---\n> Documentation/git-blame.txt | 13 +++++++++++++\n> 1 file changed, 13 insertions(+)\n>\n> diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\n> index 3bf5d5d8b4..683f8ab0b0 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\nIt probably would become easier to read with a comma before\n\"unless\".\n\nOther than that (and the downcasing of Describe in the title), looks\ngood to me.\n\nThanks.\n\n> +- line number\n> +\n> +before the line contents.\n> +\n> THE PORCELAIN FORMAT\n> --------------------\n"},{"id":"437749","messageId":"e70942cd-8362-b8d0-f168-01f6c190fb0b@gmail.com","threadId":"56622","inReplyTo":"CAPig+cSWutBRQK+Qy=nkaDZRvy4trVNPuo+cF-quC2rBwNe2fw@mail.gmail.com","subject":"Re: [PATCH v3 2/2] blame: document --color-* options","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-02T02:35:12Z","receivedAt":"2021-10-02T02:35:19Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 02/10/21 02.10, Eric Sunshine wrote:\n>> + config option. Only the line annotation (see \"The Default Format\" section)\n>> + is colored.\n> \n> You can drop the last sentence entirely if you start the blurb like this:\n> \n> Color line annotations differently, if...\n> \n>> +--color-by-age::\n>> + Color lines depending on the age of the line. The `color.blame.highlightRecent`\n>> + config option controls what color is used for which range of age. Only the\n>> + line annotation (see \"The Default Format\" section) is colored.\n> \n> Ditto about dropping the last sentence.\n> \n> Color line annotations depending upon the age of the line.\n> \n\nI observed that both --color-lines and --color-by-age only apply to \ndefault blame format, so the wording can be `Color line annotations ... \nif neither --porcelain nor --incremental option is specified ...`\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"437877","messageId":"xmqqk0itxbjn.fsf@gitster.g","threadId":"56622","inReplyTo":"e70942cd-8362-b8d0-f168-01f6c190fb0b@gmail.com","subject":"Re: [PATCH v3 2/2] blame: document --color-* options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-04T11:41:00Z","receivedAt":"2021-10-04T11:41:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> On 02/10/21 02.10, Eric Sunshine wrote:\n>>> + config option. Only the line annotation (see \"The Default Format\" section)\n>>> + is colored.\n>> You can drop the last sentence entirely if you start the blurb like\n>> this:\n>> Color line annotations differently, if...\n>> \n>>> +--color-by-age::\n>>> + Color lines depending on the age of the line. The `color.blame.highlightRecent`\n>>> + config option controls what color is used for which range of age. Only the\n>>> + line annotation (see \"The Default Format\" section) is colored.\n>> Ditto about dropping the last sentence.\n>> Color line annotations depending upon the age of the line.\n>> \n>\n> I observed that both --color-lines and --color-by-age only apply to\n> default blame format, ...\n\nTechnically, it is sufficient to say \"color line annotations\"\nbecause the default format is the only one that is described to give\n\"line annotations\". I do not think it would hurt too much to be a\nbit more explicit, perhaps like:\n\n Color line annotations, depending upon the age of the line, in\n the default output format.\n\nI personally feel \"(see section X)\" is being a bit more ditracting\nthan being helpful to readers.\n\nThanks.\n\n\n"}]}