[PATCH 7/7] Documentation: Add docs for blame format
- From
- Aleks Todorov <aleks.todorov.1337@gmail.com>
- Date
- Mar 1, 2025, 21:45 UTC
- Message-ID
- <20250301214652.536439-8-aleks.todorov.1337@gmail.com>
- In-Reply-To
- <20250301214652.536439-1-aleks.todorov.1337@gmail.com>
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 --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