Skip to content

Commit 4274cdf

Browse files
committed
Merge branch 'es/contacts'
A helper to read from a set of format-patch output files or a range of commits and find those who may have insights to the code that the changes touch by running a series of "git blame" commands. * es/contacts: contrib: contacts: add documentation contrib: contacts: add mailmap support contrib: contacts: interpret committish akin to format-patch contrib: contacts: add ability to parse from committish contrib: add git-contacts helper
2 parents f01723a + acb01a3 commit 4274cdf

File tree

2 files changed

+282
-0
lines changed

2 files changed

+282
-0
lines changed

contrib/contacts/git-contacts

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
#!/usr/bin/perl
2+
3+
# List people who might be interested in a patch. Useful as the argument to
4+
# git-send-email --cc-cmd option, and in other situations.
5+
#
6+
# Usage: git contacts <file | rev-list option> ...
7+
8+
use strict;
9+
use warnings;
10+
use IPC::Open2;
11+
12+
my $since = '5-years-ago';
13+
my $min_percent = 10;
14+
my $labels_rx = qr/Signed-off-by|Reviewed-by|Acked-by|Cc/i;
15+
my %seen;
16+
17+
sub format_contact {
18+
my ($name, $email) = @_;
19+
return "$name <$email>";
20+
}
21+
22+
sub parse_commit {
23+
my ($commit, $data) = @_;
24+
my $contacts = $commit->{contacts};
25+
my $inbody = 0;
26+
for (split(/^/m, $data)) {
27+
if (not $inbody) {
28+
if (/^author ([^<>]+) <(\S+)> .+$/) {
29+
$contacts->{format_contact($1, $2)} = 1;
30+
} elsif (/^$/) {
31+
$inbody = 1;
32+
}
33+
} elsif (/^$labels_rx:\s+([^<>]+)\s+<(\S+?)>$/o) {
34+
$contacts->{format_contact($1, $2)} = 1;
35+
}
36+
}
37+
}
38+
39+
sub import_commits {
40+
my ($commits) = @_;
41+
return unless %$commits;
42+
my $pid = open2 my $reader, my $writer, qw(git cat-file --batch);
43+
for my $id (keys(%$commits)) {
44+
print $writer "$id\n";
45+
my $line = <$reader>;
46+
if ($line =~ /^([0-9a-f]{40}) commit (\d+)/) {
47+
my ($cid, $len) = ($1, $2);
48+
die "expected $id but got $cid\n" unless $id eq $cid;
49+
my $data;
50+
# cat-file emits newline after data, so read len+1
51+
read $reader, $data, $len + 1;
52+
parse_commit($commits->{$id}, $data);
53+
}
54+
}
55+
close $reader;
56+
close $writer;
57+
waitpid($pid, 0);
58+
die "git-cat-file error: $?\n" if $?;
59+
}
60+
61+
sub get_blame {
62+
my ($commits, $source, $start, $len, $from) = @_;
63+
$len = 1 unless defined($len);
64+
return if $len == 0;
65+
open my $f, '-|',
66+
qw(git blame --porcelain -C), '-L', "$start,+$len",
67+
'--since', $since, "$from^", '--', $source or die;
68+
while (<$f>) {
69+
if (/^([0-9a-f]{40}) \d+ \d+ \d+$/) {
70+
my $id = $1;
71+
$commits->{$id} = { id => $id, contacts => {} }
72+
unless $seen{$id};
73+
$seen{$id} = 1;
74+
}
75+
}
76+
close $f;
77+
}
78+
79+
sub scan_patches {
80+
my ($commits, $id, $f) = @_;
81+
my $source;
82+
while (<$f>) {
83+
if (/^From ([0-9a-f]{40}) Mon Sep 17 00:00:00 2001$/) {
84+
$id = $1;
85+
$seen{$id} = 1;
86+
}
87+
next unless $id;
88+
if (m{^--- (?:a/(.+)|/dev/null)$}) {
89+
$source = $1;
90+
} elsif (/^--- /) {
91+
die "Cannot parse hunk source: $_\n";
92+
} elsif (/^@@ -(\d+)(?:,(\d+))?/ && $source) {
93+
get_blame($commits, $source, $1, $2, $id);
94+
}
95+
}
96+
}
97+
98+
sub scan_patch_file {
99+
my ($commits, $file) = @_;
100+
open my $f, '<', $file or die "read failure: $file: $!\n";
101+
scan_patches($commits, undef, $f);
102+
close $f;
103+
}
104+
105+
sub parse_rev_args {
106+
my @args = @_;
107+
open my $f, '-|',
108+
qw(git rev-parse --revs-only --default HEAD --symbolic), @args
109+
or die;
110+
my @revs;
111+
while (<$f>) {
112+
chomp;
113+
push @revs, $_;
114+
}
115+
close $f;
116+
return @revs if scalar(@revs) != 1;
117+
return "^$revs[0]", 'HEAD' unless $revs[0] =~ /^-/;
118+
return $revs[0], 'HEAD';
119+
}
120+
121+
sub scan_rev_args {
122+
my ($commits, $args) = @_;
123+
my @revs = parse_rev_args(@$args);
124+
open my $f, '-|', qw(git rev-list --reverse), @revs or die;
125+
while (<$f>) {
126+
chomp;
127+
my $id = $_;
128+
$seen{$id} = 1;
129+
open my $g, '-|', qw(git show -C --oneline), $id or die;
130+
scan_patches($commits, $id, $g);
131+
close $g;
132+
}
133+
close $f;
134+
}
135+
136+
sub mailmap_contacts {
137+
my ($contacts) = @_;
138+
my %mapped;
139+
my $pid = open2 my $reader, my $writer, qw(git check-mailmap --stdin);
140+
for my $contact (keys(%$contacts)) {
141+
print $writer "$contact\n";
142+
my $canonical = <$reader>;
143+
chomp $canonical;
144+
$mapped{$canonical} += $contacts->{$contact};
145+
}
146+
close $reader;
147+
close $writer;
148+
waitpid($pid, 0);
149+
die "git-check-mailmap error: $?\n" if $?;
150+
return \%mapped;
151+
}
152+
153+
if (!@ARGV) {
154+
die "No input revisions or patch files\n";
155+
}
156+
157+
my (@files, @rev_args);
158+
for (@ARGV) {
159+
if (-e) {
160+
push @files, $_;
161+
} else {
162+
push @rev_args, $_;
163+
}
164+
}
165+
166+
my %commits;
167+
for (@files) {
168+
scan_patch_file(\%commits, $_);
169+
}
170+
if (@rev_args) {
171+
scan_rev_args(\%commits, \@rev_args)
172+
}
173+
import_commits(\%commits);
174+
175+
my $contacts = {};
176+
for my $commit (values %commits) {
177+
for my $contact (keys %{$commit->{contacts}}) {
178+
$contacts->{$contact}++;
179+
}
180+
}
181+
$contacts = mailmap_contacts($contacts);
182+
183+
my $ncommits = scalar(keys %commits);
184+
for my $contact (keys %$contacts) {
185+
my $percent = $contacts->{$contact} * 100 / $ncommits;
186+
next if $percent < $min_percent;
187+
print "$contact\n";
188+
}

contrib/contacts/git-contacts.txt

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
git-contacts(1)
2+
===============
3+
4+
NAME
5+
----
6+
git-contacts - List people who might be interested in a set of changes
7+
8+
9+
SYNOPSIS
10+
--------
11+
[verse]
12+
'git contacts' (<patch>|<range>|<rev>)...
13+
14+
15+
DESCRIPTION
16+
-----------
17+
18+
Given a set of changes, specified as patch files or revisions, determine people
19+
who might be interested in those changes. This is done by consulting the
20+
history of each patch or revision hunk to find people mentioned by commits
21+
which touched the lines of files under consideration.
22+
23+
Input consists of one or more patch files or revision arguments. A revision
24+
argument can be a range or a single `<rev>` which is interpreted as
25+
`<rev>..HEAD`, thus the same revision arguments are accepted as for
26+
linkgit:git-format-patch[1]. Patch files and revision arguments can be combined
27+
in the same invocation.
28+
29+
This command can be useful for determining the list of people with whom to
30+
discuss proposed changes, or for finding the list of recipients to Cc: when
31+
submitting a patch series via `git send-email`. For the latter case, `git
32+
contacts` can be used as the argument to `git send-email`'s `--cc-cmd` option.
33+
34+
35+
DISCUSSION
36+
----------
37+
38+
`git blame` is invoked for each hunk in a patch file or revision. For each
39+
commit mentioned by `git blame`, the commit message is consulted for people who
40+
authored, reviewed, signed, acknowledged, or were Cc:'d. Once the list of
41+
participants is known, each person's relevance is computed by considering how
42+
many commits mentioned that person compared with the total number of commits
43+
under consideration. The final output consists only of participants who exceed
44+
a minimum threshold of participation.
45+
46+
47+
OUTPUT
48+
------
49+
50+
For each person of interest, a single line is output, terminated by a newline.
51+
If the person's name is known, ``Name $$<user@host>$$'' is printed; otherwise
52+
only ``$$<user@host>$$'' is printed.
53+
54+
55+
EXAMPLES
56+
--------
57+
58+
* Consult patch files:
59+
+
60+
------------
61+
$ git contacts feature/*.patch
62+
------------
63+
64+
* Revision range:
65+
+
66+
------------
67+
$ git contacts R1..R2
68+
------------
69+
70+
* From a single revision to `HEAD`:
71+
+
72+
------------
73+
$ git contacts origin
74+
------------
75+
76+
* Helper for `git send-email`:
77+
+
78+
------------
79+
$ git send-email --cc-cmd='git contacts' feature/*.patch
80+
------------
81+
82+
83+
LIMITATIONS
84+
-----------
85+
86+
Several conditions controlling a person's significance are currently
87+
hard-coded, such as minimum participation level (10%), blame date-limiting (5
88+
years), and `-C` level for detecting moved and copied lines (a single `-C`). In
89+
the future, these conditions may become configurable.
90+
91+
92+
GIT
93+
---
94+
Part of the linkgit:git[1] suite

0 commit comments

Comments
 (0)