[0/7] Add Format Specifier for Blame

Message

Aleks Todorov March 1, 2025, 9:44 p.m. UTC

Hi,

As previously discussed, this patch series implements a `--format`
option for `git-blame`, re-using the existing implementation from
`git-log`.

My motivation for this is that I use git blame quite often when
debugging, and find myself checking the commit subject for a large
number of lines that I look at. Instead, it would speed up my workflow
if I could see the commit subject next to each line in the blame output.

Since this is a personal preference and each git user probably has their
own personal preference for what kind of output they want to see, as per
Junio's suggestion, by implementing a generic format option, we serve a
variety of use cases all at the same time.

For context, we can now use a command like:

  git blame builtin/blame.c -F '%h %<(17,trunc)%F (%<(20,trunc)%an %ai %>(4)%L) '

to see output like:

  df8738116f7 builtin/blame.c   (Ævar Arnfjörð Bjar.. 2022-10-13 17:39:20 +0200   40) static char annotate_usage[] = N_("git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>");
  5817da01434 builtin-blame.c   (Pierre Habouzit      2008-07-08 15:19:34 +0200   41)
  5817da01434 builtin-blame.c   (Pierre Habouzit      2008-07-08 15:19:34 +0200   42) static const char *blame_opt_usage[] = {
  5817da01434 builtin-blame.c   (Pierre Habouzit      2008-07-08 15:19:34 +0200   43)     blame_usage,
  5817da01434 builtin-blame.c   (Pierre Habouzit      2008-07-08 15:19:34 +0200   44)     "",

However, one key feature I could not find an easy way to implement was
to include a length specifier that auto-detects the minimum column width
required to display a placeholder without trimming the output. As a
result, I could not re-implement the existing options using the
formatting syntax.

Nevertheless, these patches serve my purpose, are self-contained, and
could be extended in the future to complete the plan.

I've made my best effort to include clear atomic commits, write
conforming code, include tests, and add documentation. However, as this
is my first submission here, I expect that I may have missed something -
so please let me know what can be improved and whether this patch series
is suitable for integration.

A short logical summary of the patches:

  1. Add --format / -F option
  2. Add format config option
  3. Add %F and %L format specifiers (blame-only) to allow the filename
     and line number to be emitted
  4. Call into pretty.c to expand the provided format string
  5. Add tests
  6. Refactor documentation structure
  7. Add documentation specific to `git blame --format`

Patches are based on main.

Thanks,
Aleks

Aleks Todorov (7):
  builtin/blame: Accept a user-specified format
  builtin/blame: Add blame.format config option
  pretty: Add F and L format specifiers
  builtin/blame: Expand format when available
  t8015: Add tests for git blame -F
  Documentation: Move placeholders to separate file
  Documentation: Add docs for blame format

 Documentation/config/blame.adoc   |   5 +
 Documentation/git-blame.adoc      |  16 ++
 Documentation/placeholders.adoc   | 242 ++++++++++++++++++++++++++++++
 Documentation/pretty-formats.adoc | 239 +----------------------------
 builtin/blame.c                   | 119 +++++++++------
 pretty.c                          |  14 ++
 pretty.h                          |   5 +
 t/meson.build                     |   1 +
 t/t8015-blame-format.sh           |  39 +++++
 9 files changed, 395 insertions(+), 285 deletions(-)
 create mode 100644 Documentation/placeholders.adoc
 create mode 100755 t/t8015-blame-format.sh