{"thread":{"id":"56662","subject":"[PATCH 0/2] blame: documentation update","startedAt":"2021-10-08T04:33:58Z","lastAt":"2021-10-08T04:34:05Z","messageCount":3,"participants":["Bagas Sanjaya"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"438268","messageId":"20211008043343.189651-1-bagasdotme@gmail.com","threadId":"56662","inReplyTo":null,"subject":"[PATCH 0/2] blame: documentation update","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-08T04:33:41Z","receivedAt":"2021-10-08T04:33:58Z","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 v4 [1]:\n  - Remove \"(see section X)\" pointer (suggested by Junio)\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\nRange-diff against v4 [1]:\n1:  976c17a485 = 1:  977c3dd77d blame: describe default output format\n2:  517dc2cb3d ! 2:  df39496623 blame: document --color-* options\n    @@ Documentation/blame-options.txt: take effect.\n      \tpreviously processed files.\n      \n     +--color-lines::\n    -+\tColor line annotations (see \"The Default Format\" section) differently if they\n    -+\tcome from the same commit as the preceding line, and if neither `--porcelain`\n    -+\tnor `--incremental` format option is specified. This makes it easier to distinguish\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 (see \"The Default Format\" section) depending on the age of\n    -+\tthe line, if neither `--porcelain` nor `--incremental` format option is specified.\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\n[1]:\nhttps://lore.kernel.org/git/20211003105327.215996-3-bagasdotme@gmail.com/T/#u\n\nbase-commit: 106298f7f9cca4158a980de149ef217751e1f943\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438269","messageId":"20211008043343.189651-2-bagasdotme@gmail.com","threadId":"56662","inReplyTo":"20211008043343.189651-1-bagasdotme@gmail.com","subject":"[PATCH 1/2] blame: describe default output format","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-08T04:33:42Z","receivedAt":"2021-10-08T04:34:03Z","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 <bagasdotme@gmail.com>\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":"438270","messageId":"20211008043343.189651-3-bagasdotme@gmail.com","threadId":"56662","inReplyTo":"20211008043343.189651-1-bagasdotme@gmail.com","subject":"[PATCH 2/2] blame: document --color-* options","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-08T04:33:43Z","receivedAt":"2021-10-08T04:34:05Z","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 <m.st.pierre@ncp-e.com>\nSigned-off-by: Dr. Matthias St. Pierre <m.st.pierre@ncp-e.com>\nSigned-off-by: Bagas Sanjaya <bagasdotme@gmail.com>\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 <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]\n \t    [--ignore-rev <rev>] [--ignore-revs-file <file>]\n-\t    [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>]\n-\t    [--] <file>\n+\t    [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]\n+\t    [<rev> | --contents <file> | --reverse <rev>..<rev>] [--] <file>\n \n DESCRIPTION\n -----------\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"}]}