{"thread":{"id":"56610","subject":"[PATCH v2 0/2] blame: documentation update","startedAt":"2021-09-29T12:49:52Z","lastAt":"2021-09-29T19:15:35Z","messageCount":5,"participants":["Bagas Sanjaya","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":2},"messages":[{"id":"437456","messageId":"20210929124935.41917-1-bagasdotme@gmail.com","threadId":"56610","inReplyTo":null,"subject":"[PATCH v2 0/2] blame: documentation update","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-29T12:49:33Z","receivedAt":"2021-09-29T12:49:52Z","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 | 12 ++++++++++++\n Documentation/config/color.txt | 12 ++++++------\n Documentation/git-blame.txt | 16 ++++++++++++++--\n 3 files changed, 32 insertions(+), 8 deletions(-)\n\n\nbase-commit: cefe983a320c03d7843ac78e73bd513a27806845\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"437457","messageId":"20210929124935.41917-2-bagasdotme@gmail.com","threadId":"56610","inReplyTo":"20210929124935.41917-1-bagasdotme@gmail.com","subject":"[PATCH v2 1/2] blame: Describe default output format","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-29T12:49:34Z","receivedAt":"2021-09-29T12:49:53Z","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 | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex 3bf5d5d8b4..284aa99942 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -93,6 +93,18 @@ 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 inline 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+- line number\n+\n+\n THE PORCELAIN FORMAT\n --------------------\n \n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"437458","messageId":"20210929124935.41917-3-bagasdotme@gmail.com","threadId":"56610","inReplyTo":"20210929124935.41917-1-bagasdotme@gmail.com","subject":"[PATCH v2 2/2] blame: document --color-* options","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-29T12:49:35Z","receivedAt":"2021-09-29T12:49:54Z","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..791214a3b1 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 belong to 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..b4c120d737 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 belong to 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 284aa99942..2dafeb7710 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":"437476","messageId":"xmqq8rzfdwo1.fsf@gitster.g","threadId":"56610","inReplyTo":"20210929124935.41917-2-bagasdotme@gmail.com","subject":"Re: [PATCH v2 1/2] blame: Describe default output format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-29T19:11:26Z","receivedAt":"2021-09-29T19:11:31Z","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\nSounds quite sensible. It also is sensible to have it before other\nformats, as this is what the users will see most often.\n\n> +THE DEFAULT FORMAT\n> +------------------\n> +\n> +When neither `--porcelain` nor `--incremental` option is specified,\n> +`git blame` will output inline 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> +- line number\n> +\n\nWe probably would want to conclude the sentence and tell the readers\nthat they get the contents of the file as well ;-) Perhaps like...\n\n `git blame` will output annotation for each line with:\n\n <<>>\n\n before the contents of the line.\n\nThe second and third items may want to see a bit more careful\nthought, though. I think three presentations are possible for them,\ni.e. you can:\n\n . use -s to suppress the author ident part altogether;\n . accept the default to use the name and date as the author ident; or\n . use -e to replace name with email in the author ident.\n\nGiven that, it would be easier to explain if you did not split the\nauthor ident as if they are two independent items. The most concice\ndescription would be:\n\n - abbreviated object name for the commit the line came from,\n\n - author ident (usually the name and the date, but see '-e' \n and '-s' for how these options may affect it),\n\n - line number\n\nI also thought we might need to also update description for \"-s\" and\n\"-e\" to clarify what they affect is \"author ident\" while trying to\ncome up with the above suggestion, but after re-reading them, I\nthink the current text we use to describe them is understandable\nenough.\n\nThanks.\n"},{"id":"437477","messageId":"xmqq35pndwha.fsf@gitster.g","threadId":"56610","inReplyTo":"20210929124935.41917-3-bagasdotme@gmail.com","subject":"Re: [PATCH v2 2/2] blame: document --color-* options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-29T19:15:29Z","receivedAt":"2021-09-29T19:15:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\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> 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\nNicely written.\n\n> +--color-lines::\n> +\tColor lines differently, if they belong to the same commit as the preceding line.\n\nIs \"belong\" the right verb? I view these lines \"come from\" their\noriginating commits, so \"they belong to\" -> \"they come from\",\nperhaps.\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 belong to the\n\nDitto.\n\nThanks.\n"}]}