Document the default output format for git-blame(1), as well as the
--color-* options which are currently undocumented but mentioned in
usage help.
Changes since v2 [1]:
- describe that the default blame format has "author ident" (suggested
by Junio)
- s/they belong to/they come from/ (suggested by Junio)
Bagas Sanjaya (2):
blame: Describe default output format
blame: document --color-* options
Documentation/blame-options.txt | 12 ++++++++++++
Documentation/config/color.txt | 12 ++++++------
Documentation/git-blame.txt | 17 +++++++++++++++--
3 files changed, 33 insertions(+), 8 deletions(-)
Range-diff against v2 [1]:
1: d6433fc682 ! 1: 2478909d67 blame: Describe default output format
@@ Documentation/git-blame.txt: include::blame-options.txt[]
+------------------
+
+When neither `--porcelain` nor `--incremental` option is specified,
-+`git blame` will output inline annotation for each line with:
++`git blame` will output annotation for each line with:
+
-+- abbreviated SHA-1 of the commit the line is attributed to;
-+- author name (or author email if `-e` or `--show-email` is specified);
-+- author date; and
++- abbreviated object name for the commit the line came from;
++- author ident (by default author name and date unless `-s` or `-e` is
++specified); and
+- line number
+
++before the line contents.
+
THE PORCELAIN FORMAT
--------------------
2: 5a5ca69012 ! 2: a6f75786ec blame: document --color-* options
@@ Documentation/blame-options.txt: take effect.
previously processed files.
+--color-lines::
-+ Color lines differently, if they belong to the same commit as the preceding line.
++ Color lines differently, if they come from the same commit as the preceding line.
+ This facilitates distinguishing code blocks introduced by different commits.
+ The color defaults to cyan and be adjusted using the `color.blame.repeatedLines`
+ config option. Only the line annotation (see "The Default Format" section)
@@ Documentation/config/color.txt: before the given timestamp, overwriting older ti
- Use the customized color for the part of git-blame output that
- is repeated meta information per line (such as commit id,
- author name, date and timezone). Defaults to cyan.
-+ Use the specified color to colorize line annotations, if they belong to the
++ Use the specified color to colorize line annotations, if they come from the
+ same commit as the preceding line (`git blame --color-lines`). Defaults to
+ cyan.
[1]:
https://lore.kernel.org/git/20210929124935.41917-1-bagasdotme@xxxxxxxxx/T/#t
base-commit: cefe983a320c03d7843ac78e73bd513a27806845
--
An old man doll... just what I always wanted! - Clara
