Add documentation explaining the new `git blame --format` option as well
as the associated `blame.format` config option.
Include a section listing the available placeholders. Also document the
new (blame-specific) placeholders in this section.
Signed-off-by: Aleks Todorov <aleks.todorov.1337@xxxxxxxxx>
---
Documentation/config/blame.adoc | 5 +++++
Documentation/git-blame.adoc | 16 ++++++++++++++++
Documentation/placeholders.adoc | 4 ++++
3 files changed, 25 insertions(+)
diff --git a/Documentation/config/blame.adoc b/Documentation/config/blame.adoc
index 4d047c1790..88ef551c04 100644
--- a/Documentation/config/blame.adoc
+++ b/Documentation/config/blame.adoc
@@ -35,3 +35,8 @@ blame.markUnblamableLines::
blame.markIgnoredLines::
Mark lines that were changed by an ignored revision that we attributed to
another commit with a '?' in the output of linkgit:git-blame[1].
+
+blame.format::
+ Apply the specified format by default when invoking
+ linkgit:git-blame[1]. For supported format specifiers, see the
+ discussion of the `--format` option in linkgit:git-blame[1].
diff --git a/Documentation/git-blame.adoc b/Documentation/git-blame.adoc
index f75ed44790..373ff6b994 100644
--- a/Documentation/git-blame.adoc
+++ b/Documentation/git-blame.adoc
@@ -62,6 +62,17 @@ include::blame-options.adoc[]
a certain threshold for 'git blame' to consider those lines
of code to have been moved.
+-F::
+--format::
+ Emit blame information in a given '<format>'. '<format>' is a string
+ that can contain '%placeholder' specifiers, which will be expanded to
+ produce blame information.
++
+See the "PLACEHOLDERS" section to learn about all of the available specifiers.
++
+Note: you can specify the default blame format in the repository configuration
+(see `blame.format` in linkgit:git-config[1]).
+
-f::
--show-name::
Show the filename in the original commit. By default
@@ -235,6 +246,11 @@ one) at the beginning of the "extended information" lines. That way, if
there is ever added information (like the commit encoding or extended
commit commentary), a blame viewer will not care.
+PLACEHOLDERS
+------------
+
+:git-blame: 1
+include::placeholders.adoc[]
MAPPING AUTHORS
---------------
diff --git a/Documentation/placeholders.adoc b/Documentation/placeholders.adoc
index 7f4d0b59c7..5420a44e94 100644
--- a/Documentation/placeholders.adoc
+++ b/Documentation/placeholders.adoc
@@ -145,6 +145,10 @@ tags are added or removed at the same time.
(like `git log --source`), only works with `git log`
'%e':: encoding
'%s':: subject
+ifdef::git-blame[]
+'%L':: line number
+'%F':: filename in the original commit
+endif::git-blame[]
'%f':: sanitized subject line, suitable for a filename
'%b':: body
'%B':: raw body (unwrapped subject and body)
--
2.43.0
