{"thread":{"id":"56637","subject":"[PATCH v4 1/2] blame: describe default output format","startedAt":"2021-10-03T10:54:38Z","lastAt":"2021-10-03T10:54:41Z","messageCount":3,"participants":["Bagas Sanjaya"],"isPatch":true,"patchVersion":4,"patchTotal":2},"messages":[{"id":"437804","messageId":"20211003105327.215996-2-bagasdotme@gmail.com","threadId":"56637","inReplyTo":"20211003105327.215996-1-bagasdotme@gmail.com","subject":"[PATCH v4 1/2] blame: describe default output format","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-03T10:53:27Z","receivedAt":"2021-10-03T10:54:38Z","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":"437805","messageId":"20211003105327.215996-1-bagasdotme@gmail.com","threadId":"56637","inReplyTo":null,"subject":"[PATCH v4 0/2] blame: documentation update","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-03T10:53:26Z","receivedAt":"2021-10-03T10:54:38Z","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 v3 [1]:\n  - grammatical and wording fixes (suggested by Eric and Junio)\n \nBagas Sanjaya (2):\n  blame: describe default output format\n  blame: document --color-* options\n\n Documentation/blame-options.txt | 13 +++++++++++++\n Documentation/config/color.txt  | 33 ++++++++++++++++++---------------\n Documentation/git-blame.txt     | 17 +++++++++++++++--\n 3 files changed, 46 insertions(+), 17 deletions(-)\n\nRange-diff against v3:\n1:  2478909d67 ! 1:  976c17a485 blame: Describe default output format\n    @@ Metadata\n     Author: Bagas Sanjaya <bagasdotme@gmail.com>\n     \n      ## Commit message ##\n    -    blame: Describe default output format\n    +    blame: describe default output format\n     \n         While there is descriptions for porcelain and incremental output\n         formats, the default format isn't described. Describe that format for\n    @@ Documentation/git-blame.txt: include::blame-options.txt[]\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    ++- author ident (by default author name and date, unless `-s` or `-e` is\n     +specified); and\n     +- line number\n     +\n2:  a6f75786ec < -:  ---------- blame: document --color-* options\n-:  ---------- > 2:  517dc2cb3d blame: document --color-* options\n\n[1]:\nhttps://lore.kernel.org/git/20211001113725.13354-1-bagasdotme@gmail.com/T/#t\n\nbase-commit: cefe983a320c03d7843ac78e73bd513a27806845\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"437806","messageId":"20211003105327.215996-3-bagasdotme@gmail.com","threadId":"56637","inReplyTo":"20211003105327.215996-1-bagasdotme@gmail.com","subject":"[PATCH v4 2/2] blame: document --color-* options","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-03T10:53:28Z","receivedAt":"2021-10-03T10:54:41Z","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 | 13 +++++++++++++\n Documentation/config/color.txt  | 33 ++++++++++++++++++---------------\n Documentation/git-blame.txt     |  4 ++--\n 3 files changed, 33 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt\nindex 117f4cf806..3972cc8cef 100644\n--- a/Documentation/blame-options.txt\n+++ b/Documentation/blame-options.txt\n@@ -136,5 +136,18 @@ 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 (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+\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+\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"}]}