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
--
2.43.0
