diff mbox series

[7/7] Documentation: Add docs for blame format

Message ID 20250301214652.536439-8-aleks.todorov.1337@gmail.com (mailing list archive)
State New
Headers show
Series Add Format Specifier for Blame | expand

Commit Message

Aleks Todorov March 1, 2025, 9:45 p.m. UTC 
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@gmail.com>
---
 Documentation/config/blame.adoc |  5 +++++
 Documentation/git-blame.adoc    | 16 ++++++++++++++++
 Documentation/placeholders.adoc |  4 ++++
 3 files changed, 25 insertions(+)
diff mbox series

Patch

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)