[PATCH 0/4] Selectively show only blamed limes

[PATCH 0/4] Selectively show only blamed limes

[Philip Oakley]

While `git blame` is able to select interesting line regions of a
file, it's not easy to just display blame lines since a recent date,
especially for large files.

The recent discussion on CMake[1] notes the issue of ensuring any CMake
scheme kept up with changes to the fairly long Makefile. This short
series first clarifies the marking of 'boundary' commits outwith the
revision range or time range, then adds a `--blame-only` option to
supress non-blame (boundary) commit lines, with tests, and finally
adds tests for the long standing `-b` option that simply blanks out
the oid, but still displays the whole file.

Philip


cc: Sibi Siddharthan <sibisiddharthan.github@gmail.com>
[1] https://lore.kernel.org/git/pull.614.v2.git.1589302254.gitgitgadget@gmail.com/

Philip Oakley (4):
  doc: blame: show the boundary commit '^' caret mark
  blame: add option to show only blamed commits `--blame-only`
  blame: do not show boundary commits, only those blamed
  blame: test the -b option, use blank oid for boundary commits.

 Documentation/blame-options.txt |  4 ++++
 Documentation/git-blame.txt     |  8 ++++----
 builtin/blame.c                 |  3 +++
 t/t8002-blame.sh                | 19 +++++++++++++++++++
 4 files changed, 30 insertions(+), 4 deletions(-)

-- 
2.26.2.windows.1.13.g9dddff6983

[PATCH 1/4] doc: blame: show the boundary commit '^' caret mark

[Philip Oakley]

Make the boundary commits' ^ caret findable in the documentation.

Signed-off-by: Philip Oakley <philipoakley@iee.email>
---
 Documentation/git-blame.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 7e81541996..02f9ad6fe9 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -87,8 +87,8 @@ include::blame-options.txt[]
 
 --abbrev=<n>::
 	Instead of using the default 7+1 hexadecimal digits as the
-	abbreviated object name, use <n>+1 digits. Note that 1 column
-	is used for a caret to mark the boundary commit.
+	abbreviated commit object name, use <n>+1 digits. Note that 1 column
+	is used for a caret (`^`) to mark boundary commits.
 
 
 THE PORCELAIN FORMAT
@@ -164,7 +164,7 @@ When revision range specifiers are used to limit the annotation,
 lines that have not changed since the range boundary (either the
 commit v2.6.18 or the most recent commit that is more than 3
 weeks old in the above example) are blamed for that range
-boundary commit.
+boundary commit (preceded by `^` if shown).
 
 A particularly useful way is to see if an added file has lines
 created by copy-and-paste from existing files.  Sometimes this
-- 
2.26.2.windows.1.13.g9dddff6983

[PATCH 2/4] blame: add option to show only blamed commits `--blame-only`

[Philip Oakley]

For large files the will be many lines which are not blamed with the
revision range or date period which clutter the output.

Add an option to suppress the display of boundary commits lines, not
just the object id (`-b` option).

This is non-functional at this stage. The next commit will add
functionality, tests, and documenation.

Signed-off-by: Philip Oakley <philipoakley@iee.email>
---
 Documentation/blame-options.txt | 4 ++++
 Documentation/git-blame.txt     | 2 +-
 builtin/blame.c                 | 2 ++
 3 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index 5d122db6e9..b4b27033a6 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt
@@ -2,6 +2,10 @@
 	Show blank SHA-1 for boundary commits.  This can also
 	be controlled via the `blame.blankboundary` config option.
 
+--blame-only::
+	Do not show any boundary commit lines created by revision range
+	specifiers. Only show blamed lines.
+
 --root::
 	Do not treat root commits as boundaries.  This can also be
 	controlled via the `blame.showRoot` config option.
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 02f9ad6fe9..74b6344c7b 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
-	    [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
+	    [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--blame-only]
 	    [--ignore-rev <rev>] [--ignore-revs-file <file>]
 	    [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>]
 	    [--] <file>
diff --git a/builtin/blame.c b/builtin/blame.c
index bf1cecdf3f..b699c777c4 100644
--- a/builtin/blame.c
+++ b/builtin/blame.c
@@ -45,6 +45,7 @@ static int max_score_digits;
 static int show_root;
 static int reverse;
 static int blank_boundary;
+static int blame_only;
 static int incremental;
 static int xdl_opts;
 static int abbrev = -1;
@@ -843,6 +844,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
 	const struct option options[] = {
 		OPT_BOOL(0, "incremental", &incremental, N_("Show blame entries as we find them, incrementally")),
 		OPT_BOOL('b', NULL, &blank_boundary, N_("Show blank SHA-1 for boundary commits (Default: off)")),
+		OPT_BOOL(0, "blame-only", &blame_only, N_("Only show blamed commits (Default: off)")),
 		OPT_BOOL(0, "root", &show_root, N_("Do not treat root commits as boundaries (Default: off)")),
 		OPT_BOOL(0, "show-stats", &show_stats, N_("Show work cost statistics")),
 		OPT_BOOL(0, "progress", &show_progress, N_("Force progress reporting")),
-- 
2.26.2.windows.1.13.g9dddff6983

[PATCH 3/4] blame: do not show boundary commits, only those blamed

[Philip Oakley]

Make the option functional and add tests

Signed-off-by: Philip Oakley <philipoakley@iee.email>
---
 builtin/blame.c  | 1 +
 t/t8002-blame.sh | 7 +++++++
 2 files changed, 8 insertions(+)

diff --git a/builtin/blame.c b/builtin/blame.c
index b699c777c4..61e5a7ff44 100644
--- a/builtin/blame.c
+++ b/builtin/blame.c
@@ -475,6 +475,7 @@ static void emit_other(struct blame_scoreboard *sb, struct blame_entry *ent, int
 			fputs(color, stdout);
 
 		if (suspect->commit->object.flags & UNINTERESTING) {
+			if (blame_only) continue;
 			if (blank_boundary)
 				memset(hex, ' ', length);
 			else if (!(opt & OUTPUT_ANNOTATE_COMPAT)) {
diff --git a/t/t8002-blame.sh b/t/t8002-blame.sh
index eea048e52c..d4877c7c54 100755
--- a/t/t8002-blame.sh
+++ b/t/t8002-blame.sh
@@ -122,4 +122,11 @@ test_expect_success '--exclude-promisor-objects does not BUG-crash' '
 	test_must_fail git blame --exclude-promisor-objects one
 '
 
+test_expect_success 'test --blame-only, exclude boundary commits' '
+	git blame --blame-only branch1.. -- file >actual &&
+	git blame branch1.. -- file >full &&
+	sed -e "/^\^/d" full >expected &&
+	test_cmp expected actual
+'
+
 test_done
-- 
2.26.2.windows.1.13.g9dddff6983

[PATCH 4/4] blame: test the -b option, use blank oid for boundary commits.

[Philip Oakley]

4c10a5caa7 (blame: -b (blame.blankboundary) and --root (blame.showroot),
2006-12-18) introduced the -b option. Add a test.

The sed script removes the last hex digit from boundary commit oids
'^hexx msg' -> '^hex  msg' until all leading hex's are gone, finally
removing the boundary commit marker.

Signed-off-by: Philip Oakley <philipoakley@iee.email>
---
 t/t8002-blame.sh | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/t/t8002-blame.sh b/t/t8002-blame.sh
index d4877c7c54..de0f81abe9 100755
--- a/t/t8002-blame.sh
+++ b/t/t8002-blame.sh
@@ -129,4 +129,16 @@ test_expect_success 'test --blame-only, exclude boundary commits' '
 	test_cmp expected actual
 '
 
+test_expect_success 'test -b option, blank oid for boundary commits' '
+	git blame -b branch1.. -- file >actual &&
+	git blame branch1.. -- file >full &&
+	sed -e "/^\^/{
+		:loop;
+		s/^\(\^[0-9a-f]*\)[0-9a-f] \(.*\)/\1  \2/g;
+		tloop;
+		s/^\^/ /;
+	}" full >expected &&
+	test_cmp expected actual
+'
+
 test_done
-- 
2.26.2.windows.1.13.g9dddff6983

Re: [PATCH 4/4] blame: test the -b option, use blank oid for boundary commits.

[Jeff King]

On Mon, May 25, 2020 at 10:57:51PM +0100, Philip Oakley wrote:

> The sed script removes the last hex digit from boundary commit oids
> '^hexx msg' -> '^hex  msg' until all leading hex's are gone, finally
> removing the boundary commit marker.

Thanks for documenting this, as the sed was rather hard to read:

> +test_expect_success 'test -b option, blank oid for boundary commits' '
> +	git blame -b branch1.. -- file >actual &&
> +	git blame branch1.. -- file >full &&
> +	sed -e "/^\^/{
> +		:loop;
> +		s/^\(\^[0-9a-f]*\)[0-9a-f] \(.*\)/\1  \2/g;
> +		tloop;
> +		s/^\^/ /;
> +	}" full >expected &&

I wonder if we can make it simpler.

In perl I'd probably just replace the whole string with the equivalent
number of spaces, like:

  perl -pe 's/^\^\S+/" " x length($&)/e'

but I suppose some would consider that pretty magical, too. It might be
simpler still to just avoid testing leading whitespace:

   sed 's/^\^[0-9a-f]* *//' <full >expected &&
   sed 's/^ *//' <actual >actual.stripped &&
   test_cmp expected actual.stripped

but perhaps the indentation is a useful part of what we're testing.

-Peff

Re: [PATCH 4/4] blame: test the -b option, use blank oid for boundary commits.

[Philip Oakley]

On 27/05/2020 08:30, Jeff King wrote:
> On Mon, May 25, 2020 at 10:57:51PM +0100, Philip Oakley wrote:
>
>> The sed script removes the last hex digit from boundary commit oids
>> '^hexx msg' -> '^hex  msg' until all leading hex's are gone, finally
>> removing the boundary commit marker.
> Thanks for documenting this, as the sed was rather hard to read:
It was hard to write as well;-) lots of dead ends in the sed language.
>
>> +test_expect_success 'test -b option, blank oid for boundary commits' '
>> +	git blame -b branch1.. -- file >actual &&
>> +	git blame branch1.. -- file >full &&
>> +	sed -e "/^\^/{
>> +		:loop;
>> +		s/^\(\^[0-9a-f]*\)[0-9a-f] \(.*\)/\1  \2/g;
>> +		tloop;
>> +		s/^\^/ /;
>> +	}" full >expected &&
> I wonder if we can make it simpler.
>
> In perl I'd probably just replace the whole string with the equivalent
> number of spaces, like:
>
>   perl -pe 's/^\^\S+/" " x length($&)/e'
I'm not a perl person, so I thought sed might be an easy target but ...
it wasn't.
>
> but I suppose some would consider that pretty magical, too. 
I'd need to look it up!

> It might be
> simpler still to just avoid testing leading whitespace:
>
>    sed 's/^\^[0-9a-f]* *//' <full >expected &&
>    sed 's/^ *//' <actual >actual.stripped &&
>    test_cmp expected actual.stripped
>
> but perhaps the indentation is a useful part of what we're testing.

The code does take care to exactly match indentation, so I felt that the
indentation should be tested.

Philip

Re: [PATCH 0/4] Selectively show only blamed limes

[Jeff King]

On Mon, May 25, 2020 at 10:57:47PM +0100, Philip Oakley wrote:

> While `git blame` is able to select interesting line regions of a
> file, it's not easy to just display blame lines since a recent date,
> especially for large files.

I'm not convinced this is a useful thing to do in general. Lines don't
always stand on their own, and you'd lack context for deciphering them.
So a real example from "git blame -b --since=1.year.ago Makefile", for
example (pardon the long lines):

  3a94cb31d52 (Johannes Schindelin        2019-07-29 13:08:16 -0700 2734)              -e 's|@@PROG@@|$(patsubst test-%,t/helper/test-%$(X),$(@F))$(patsubst git%,$(X),$(filter $(@F),$(BINDIR_PROGRAMS_NEED_X)))|' < $< > $@ && \

but in context it looks like:

              (Junio C Hamano             2019-05-19 16:46:42 +0900 2730) bin-wrappers/%: wrap-for-bin.sh
              (Junio C Hamano             2019-05-19 16:46:42 +0900 2731)         @mkdir -p bin-wrappers
              (Junio C Hamano             2019-05-19 16:46:42 +0900 2732)         $(QUIET_GEN)sed -e '1s|#!.*/sh|#!$(SHELL_PATH_SQ)|' \
              (Junio C Hamano             2019-05-19 16:46:42 +0900 2733)              -e 's|@@BUILD_DIR@@|$(shell pwd)|' \
  3a94cb31d52 (Johannes Schindelin        2019-07-29 13:08:16 -0700 2734)              -e 's|@@PROG@@|$(patsubst test-%,t/helper/test-%$(X),$(@F))$(patsubst git%,$(X),$(filter $(@F),$(BINDIR_PROGRAMS_NEED_X)))|' < $< > $@ && \
              (Junio C Hamano             2019-05-19 16:46:42 +0900 2735)         chmod +x $@

Of course there are cases where it might be useful. But you can already
do:

  git blame --since=1.year.ago Makefile | grep -v ^^

I'm not totally opposed to the feature. I'm just really struggling to
see how it would be generally useful. For special cases where you're
just counting up lines, you'd be more likely to post-process the result
anyway, at which point --line-porcelain is often easier to work with.

> Philip Oakley (4):
>   doc: blame: show the boundary commit '^' caret mark

This doc fix seems worthwhile on its own, though.

>   blame: add option to show only blamed commits `--blame-only`
>   blame: do not show boundary commits, only those blamed

If we do go this direction, these really ought to be a single commit.

>   blame: test the -b option, use blank oid for boundary commits.

This one might be worth doing independently, too.

-Peff

Re: [PATCH 0/4] Selectively show only blamed limes

[Philip Oakley]

Hi Peff

On 27/05/2020 08:23, Jeff King wrote:
> On Mon, May 25, 2020 at 10:57:47PM +0100, Philip Oakley wrote:
>
>> While `git blame` is able to select interesting line regions of a
>> file, it's not easy to just display blame lines since a recent date,
>> especially for large files.
> I'm not convinced this is a useful thing to do in general. Lines don't
> always stand on their own, and you'd lack context for deciphering them.
> So a real example from "git blame -b --since=1.year.ago Makefile", for
> example (pardon the long lines):

My contention is that there is a lot of effort needed _beforehand_ to
reach that point. We've already had to page down 2700 line to get there,
and then had to carefully select the differing before and after context
lines.

The use of the --blame-only (especially with broad date range --since)
is to quickly narrow focus with the rather large file to the few areas
of concern (probably related why the -b was introduced initially?)

>
>   3a94cb31d52 (Johannes Schindelin        2019-07-29 13:08:16 -0700 2734)              -e 's|@@PROG@@|$(patsubst test-%,t/helper/test-%$(X),$(@F))$(patsubst git%,$(X),$(filter $(@F),$(BINDIR_PROGRAMS_NEED_X)))|' < $< > $@ && \
>
> but in context it looks like:
>
>               (Junio C Hamano             2019-05-19 16:46:42 +0900 2730) bin-wrappers/%: wrap-for-bin.sh
>               (Junio C Hamano             2019-05-19 16:46:42 +0900 2731)         @mkdir -p bin-wrappers
>               (Junio C Hamano             2019-05-19 16:46:42 +0900 2732)         $(QUIET_GEN)sed -e '1s|#!.*/sh|#!$(SHELL_PATH_SQ)|' \
>               (Junio C Hamano             2019-05-19 16:46:42 +0900 2733)              -e 's|@@BUILD_DIR@@|$(shell pwd)|' \
>   3a94cb31d52 (Johannes Schindelin        2019-07-29 13:08:16 -0700 2734)              -e 's|@@PROG@@|$(patsubst test-%,t/helper/test-%$(X),$(@F))$(patsubst git%,$(X),$(filter $(@F),$(BINDIR_PROGRAMS_NEED_X)))|' < $< > $@ && \
>               (Junio C Hamano             2019-05-19 16:46:42 +0900 2735)         chmod +x $@
>
> Of course there are cases where it might be useful. But you can already
> do:
>
>   git blame --since=1.year.ago Makefile | grep -v ^^
>
> I'm not totally opposed to the feature. I'm just really struggling to
> see how it would be generally useful. For special cases where you're
> just counting up lines, you'd be more likely to post-process the result
> anyway, at which point --line-porcelain is often easier to work with.
I'm also thinking that use of Git has expanded well beyond its core
Linux VCS roots, so not all users are ready for the grep regex [1].
Hence the expansion of the `-b` to truly filter only the blamed commits.


>
>> Philip Oakley (4):
>>   doc: blame: show the boundary commit '^' caret mark
> This doc fix seems worthwhile on its own, though.
>
>>   blame: add option to show only blamed commits `--blame-only`
>>   blame: do not show boundary commits, only those blamed
> If we do go this direction, these really ought to be a single commit.
>
>>   blame: test the -b option, use blank oid for boundary commits.
> This one might be worth doing independently, too.
OK. The final test look a while to come up with, so it ended up last.

>
> -Peff
Thanks
Philip

[1] https://stackoverflow.com/a/42540014/717355 "Git Blame see changes
after a certain date" (longer regex for the same effect)

Re: [PATCH 0/4] Selectively show only blamed limes

[Jeff King]

On Wed, May 27, 2020 at 11:24:54AM +0100, Philip Oakley wrote:

> > I'm not convinced this is a useful thing to do in general. Lines don't
> > always stand on their own, and you'd lack context for deciphering them.
> > So a real example from "git blame -b --since=1.year.ago Makefile", for
> > example (pardon the long lines):
> 
> My contention is that there is a lot of effort needed _beforehand_ to
> reach that point. We've already had to page down 2700 line to get there,
> and then had to carefully select the differing before and after context
> lines.

I think:

  git blame -b --since=1.year.ago ... | less "+/^[^ ]"

works pretty well to get you to the right spot, with context (and then
"/<enter>" within less takes you to the next line).

But that's also pretty magical.

> The use of the --blame-only (especially with broad date range --since)
> is to quickly narrow focus with the rather large file to the few areas
> of concern (probably related why the -b was introduced initially?)

Perhaps. I think when you get an out-of-context chunk, though, it's
tricky to take the next step.

I'm still skeptical this will turn out to be all that useful in
practice. But it really isn't much code to carry, so I don't have any
real objection.

-Peff

Re: [PATCH 0/4] Selectively show only blamed limes

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, May 27, 2020 at 11:24:54AM +0100, Philip Oakley wrote:
>
>> > I'm not convinced this is a useful thing to do in general. Lines don't
>> > always stand on their own, and you'd lack context for deciphering them.
>> > So a real example from "git blame -b --since=1.year.ago Makefile", for
>> > example (pardon the long lines):
>> 
>> My contention is that there is a lot of effort needed _beforehand_ to
>> reach that point. We've already had to page down 2700 line to get there,
>> and then had to carefully select the differing before and after context
>> lines.
>
> I think:
>
>   git blame -b --since=1.year.ago ... | less "+/^[^ ]"
>
> works pretty well to get you to the right spot, with context (and then
> "/<enter>" within less takes you to the next line).

Yup.  I think this is mostly about knowing how to use the tools that
already exist.  I am not interested in this new "feature", either.

Thanks.

Re: [PATCH 0/4] Selectively show only blamed limes

[Philip Oakley]

On 28/05/2020 19:30, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
>
>> On Wed, May 27, 2020 at 11:24:54AM +0100, Philip Oakley wrote:
>>
>>>> I'm not convinced this is a useful thing to do in general. Lines don't
>>>> always stand on their own, and you'd lack context for deciphering them.
>>>> So a real example from "git blame -b --since=1.year.ago Makefile", for
>>>> example (pardon the long lines):
>>> My contention is that there is a lot of effort needed _beforehand_ to
>>> reach that point. We've already had to page down 2700 line to get there,
>>> and then had to carefully select the differing before and after context
>>> lines.
>> I think:
>>
>>   git blame -b --since=1.year.ago ... | less "+/^[^ ]"
>>
>> works pretty well to get you to the right spot, with context (and then
>> "/<enter>" within less takes you to the next line).
> Yup.  I think this is mostly about knowing how to use the tools that
> already exist.  I am not interested in this new "feature", either.
>
> Thanks.
Is the presumption of knowing the *nix tools something that should
documented, or is that an over simplification?

I'll trim this series to just the '^' documentation change and the '-b'
option test (after v2.27.0)

Philip

Re: [PATCH 0/4] Selectively show only blamed limes

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I think:
>
>   git blame -b --since=1.year.ago ... | less "+/^[^ ]"
>
> works pretty well to get you to the right spot, with context (and then
> "/<enter>" within less takes you to the next line).
>
> But that's also pretty magical.

Instead of teaching each and every tool (like "git blame", "diff",
"grep", etc.) a special trick to remove the lines from its output,
it may make a lot more sense to add a feature to pagers that lets
the users selectively "hide" the matching lines given a pattern.
Then when viewing "git blame -b" output, you can first declare
"lines that begin with a whitespace are sometimes uninteresting" and
then tell your pager "now unshow uninteresting lines", "the same, but
show 3 lines at the boundary of runs of uninteresting lines", "now
show everything", etc.

That's another reason why I do not particularly find the proposed
feature interesting.

Re: [PATCH 0/4] Selectively show only blamed limes

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Instead of teaching each and every tool (like "git blame", "diff",
> "grep", etc.) a special trick to remove the lines from its output,
> it may make a lot more sense to add a feature to pagers that lets
> the users selectively "hide" the matching lines given a pattern.
> Then when viewing "git blame -b" output, you can first declare
> "lines that begin with a whitespace are sometimes uninteresting" and
> then tell your pager "now unshow uninteresting lines", "the same, but
> show 3 lines at the boundary of runs of uninteresting lines", "now
> show everything", etc.

I forgot to say what I wanted to touch a bit more.  Such a feature
in pager is readily reusable for other types of payload.  "Lines
that begin with a whitespace are sometimes uninteresting" can also
be used for output from "diff -u -U<largenumber>", and "lines that
do not match '^[^:]*:[0-9]*:' are not interesting" can be used for
output from "grep n -C".  That would be a lot more sensible than
tweaking each and every tool that generates output that sometimes
needs to be read in full and sometimes needs to be shown with less
interesting parts ellided.