Debian Codegraph @

gitlog-to-changelog

raw
1 #!/bin/sh
2 #! -*-perl-*-
3
4 # Convert git log output to ChangeLog format.
5
6 # Copyright (C) 2008-2025 Free Software Foundation, Inc.
7 #
8 # This program is free software: you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation, either version 3 of the License, or
11 # (at your option) any later version.
12 #
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
17 #
18 # You should have received a copy of the GNU General Public License
19 # along with this program. If not, see <https://www.gnu.org/licenses/>.
20 #
21 # Written by Jim Meyering
22
23 # This is a prologue that allows running a perl script as an executable
24 # on systems that are compliant to a POSIX version before POSIX:2017.
25 # On such systems, the usual invocation of an executable through execlp()
26 # or execvp() fails with ENOEXEC if it is a script that does not start
27 # with a #! line. The script interpreter mentioned in the #! line has
28 # to be /bin/sh, because on GuixSD systems that is the only program that
29 # has a fixed file name. The second line is essential for perl and is
30 # also useful for editing this file in Emacs. The next two lines below
31 # are valid code in both sh and perl. When executed by sh, they re-execute
32 # the script through the perl program found in $PATH. The '-x' option
33 # is essential as well; without it, perl would re-execute the script
34 # through /bin/sh. When executed by perl, the next two lines are a no-op.
35 eval 'exec perl -wSx "$0" "$@"'
36 if 0;
37
38 my $VERSION = '2024-07-17 02:20'; # UTC
39 # The definition above must lie within the first 8 lines in order
40 # for the Emacs time-stamp write hook (at end) to update it.
41 # If you change this file with Emacs, please let the write hook
42 # do its job. Otherwise, update this string manually.
43
44 (my $copyright_year = $VERSION) =~ s/^(\d*)-.*$/$1/;
45
46 use strict;
47 use warnings;
48 use Getopt::Long;
49 use POSIX qw(strftime);
50
51 (my $ME = $0) =~ s|.*/||;
52
53 # use File::Coda; # https://meyering.net/code/Coda/
54 END {
55 defined fileno STDOUT or return;
56 close STDOUT and return;
57 warn "$ME: failed to close standard output: $!\n";
58 $? ||= 1;
59 }
60
61 sub usage ($)
62 {
63 my ($exit_code) = @_;
64 my $STREAM = ($exit_code == 0 ? *STDOUT : *STDERR);
65 if ($exit_code != 0)
66 {
67 print $STREAM "Try '$ME --help' for more information.\n";
68 }
69 else
70 {
71 print $STREAM <<EOF;
72 Usage: $ME [OPTIONS] [ARGS]
73
74 Convert git log output to ChangeLog format. If present, any ARGS
75 are passed to "git log". To avoid ARGS being parsed as options to
76 $ME, they may be preceded by '--'.
77
78 OPTIONS:
79
80 --amend=FILE FILE maps from an SHA1 to perl code (i.e., s/old/new/) that
81 makes a change to SHA1's commit log text or metadata.
82 --append-dot append a dot to the first line of each commit message if
83 there is no other punctuation or blank at the end.
84 --no-cluster never cluster commit messages under the same date/author
85 header; the default is to cluster adjacent commit messages
86 if their headers are the same and neither commit message
87 contains multiple paragraphs.
88 --srcdir=DIR the root of the source tree, from which the .git/
89 directory can be derived.
90 --since=DATE convert only the logs since DATE;
91 the default is to convert all log entries.
92 --until=DATE convert only the logs older than DATE.
93 --ignore-matching=PAT ignore commit messages whose first lines match PAT.
94 --ignore-line=PAT ignore lines of commit messages that match PAT.
95 --format=FMT set format string for commit subject and body;
96 see 'man git-log' for the list of format metacharacters;
97 the default is '%s%n%b%n'
98 --strip-tab remove one additional leading TAB from commit message lines.
99 --strip-cherry-pick remove data inserted by "git cherry-pick";
100 this includes the "cherry picked from commit ..." line,
101 and the possible final "Conflicts:" paragraph.
102 --commit-timezone use dates respecting the timezone commits were made in.
103 --help display this help and exit
104 --version output version information and exit
105
106 EXAMPLE:
107
108 $ME --since=2008-01-01 > ChangeLog
109 $ME -- -n 5 foo > last-5-commits-to-branch-foo
110
111 SPECIAL SYNTAX:
112
113 The following types of strings are interpreted specially when they appear
114 at the beginning of a log message line. They are not copied to the output.
115
116 Copyright-paperwork-exempt: Yes
117 Append the "(tiny change)" notation to the usual "date name email"
118 ChangeLog header to mark a change that does not require a copyright
119 assignment.
120 Co-authored-by: Joe User <user\@example.com>
121 List the specified name and email address on a second
122 ChangeLog header, denoting a co-author.
123 Signed-off-by: Joe User <user\@example.com>
124 These lines are simply elided.
125
126 In a FILE specified via --amend, comment lines (starting with "#") are ignored.
127 FILE must consist of <SHA,CODE+> pairs where SHA is a 40-byte SHA1 (alone on
128 a line) referring to a commit in the current project, and CODE refers to one
129 or more consecutive lines of Perl code. Pairs must be separated by one or
130 more blank line.
131
132 Here is sample input for use with --amend=FILE, from coreutils:
133
134 3a169f4c5d9159283548178668d2fae6fced3030
135 # fix typo in title:
136 s/all tile types/all file types/
137
138 1379ed974f1fa39b12e2ffab18b3f7a607082202
139 # Due to a bug in vc-dwim, I mis-attributed a patch by Paul to myself.
140 # Change the author to be Paul. Note the escaped "@":
141 s,Jim .*>,Paul Eggert <eggert\\\@cs.ucla.edu>,
142
143 Send patches and bug reports to <bug-gnulib\@gnu.org>.
144 EOF
145 }
146 exit $exit_code;
147 }
148
149 sub print_version ()
150 {
151 print "$ME version $VERSION\n";
152 print "Copyright (C) $copyright_year Free Software Foundation, Inc.\n";
153 print "License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>\n"
154 . "This is free software: you are free to change and redistribute it.\n"
155 . "There is NO WARRANTY, to the extent permitted by law.\n";
156 print "\n";
157 my $author = "Jim Meyering";
158 print "Written by $author.\n";
159 }
160
161 # If the string $S is a well-behaved file name, simply return it.
162 # If it contains white space, quotes, etc., quote it, and return the new string.
163 sub shell_quote($)
164 {
165 my ($s) = @_;
166 if ($s =~ m![^\w+/.,-]!)
167 {
168 # Convert each single quote to '\''
169 $s =~ s/\'/\'\\\'\'/g;
170 # Then single quote the string.
171 $s = "'$s'";
172 }
173 return $s;
174 }
175
176 sub quoted_cmd(@)
177 {
178 return join (' ', map {shell_quote $_} @_);
179 }
180
181 # Parse file F.
182 # Comment lines (starting with "#") are ignored.
183 # F must consist of <SHA,CODE+> pairs where SHA is a 40-byte SHA1
184 # (alone on a line) referring to a commit in the current project, and
185 # CODE refers to one or more consecutive lines of Perl code.
186 # Pairs must be separated by one or more blank line.
187 sub parse_amend_file($)
188 {
189 my ($f) = @_;
190
191 open F, '<', $f
192 or die "$ME: $f: failed to open for reading: $!\n";
193
194 my $fail;
195 my $h = {};
196 my $in_code = 0;
197 my $sha;
198 while (defined (my $line = <F>))
199 {
200 $line =~ /^\#/
201 and next;
202 chomp $line;
203 $line eq ''
204 and $in_code = 0, next;
205
206 if (!$in_code)
207 {
208 $line =~ /^([[:xdigit:]]{40})$/
209 or (warn "$ME: $f:$.: invalid line; expected an SHA1\n"),
210 $fail = 1, next;
211 $sha = lc $1;
212 $in_code = 1;
213 exists $h->{$sha}
214 and (warn "$ME: $f:$.: duplicate SHA1\n"),
215 $fail = 1, next;
216 }
217 else
218 {
219 $h->{$sha} ||= '';
220 $h->{$sha} .= "$line\n";
221 }
222 }
223 close F;
224
225 $fail
226 and exit 1;
227
228 return $h;
229 }
230
231 # git_dir_option $SRCDIR
232 #
233 # From $SRCDIR, the --git-dir option to pass to git (none if $SRCDIR
234 # is undef). Return as a list (0 or 1 element).
235 sub git_dir_option($)
236 {
237 my ($srcdir) = @_;
238 my @res = ();
239 if (defined $srcdir)
240 {
241 my $qdir = shell_quote $srcdir;
242 my $cmd = "cd $qdir && git rev-parse --show-toplevel";
243 my $qcmd = shell_quote $cmd;
244 my $git_dir = qx($cmd);
245 defined $git_dir
246 or die "$ME: cannot run $qcmd: $!\n";
247 $? == 0
248 or die "$ME: $qcmd had unexpected exit code or signal ($?)\n";
249 chomp $git_dir;
250 push @res, "--git-dir=$git_dir/.git";
251 }
252 @res;
253 }
254
255 {
256 my $since_date;
257 my $until_date;
258 my $format_string = '%s%n%b%n';
259 my $amend_file;
260 my $append_dot = 0;
261 my $cluster = 1;
262 my $ignore_matching;
263 my $ignore_line;
264 my $strip_tab = 0;
265 my $strip_cherry_pick = 0;
266 my $commit_timezone = 0;
267 my $srcdir;
268 GetOptions
269 (
270 help => sub { usage 0 },
271 version => sub { print_version; exit },
272 'since=s' => \$since_date,
273 'until=s' => \$until_date,
274 'format=s' => \$format_string,
275 'amend=s' => \$amend_file,
276 'append-dot' => \$append_dot,
277 'cluster!' => \$cluster,
278 'ignore-matching=s' => \$ignore_matching,
279 'ignore-line=s' => \$ignore_line,
280 'strip-tab' => \$strip_tab,
281 'strip-cherry-pick' => \$strip_cherry_pick,
282 'commit-timezone' => \$commit_timezone,
283 'srcdir=s' => \$srcdir,
284 ) or usage 1;
285
286 defined $since_date
287 and unshift @ARGV, "--since=$since_date";
288 defined $until_date
289 and unshift @ARGV, "--until=$until_date";
290
291 # This is a hash that maps an SHA1 to perl code (i.e., s/old/new/)
292 # that makes a correction in the log or attribution of that commit.
293 my $amend_code = defined $amend_file ? parse_amend_file $amend_file : {};
294
295 my $commit_time_format = $commit_timezone ? '%cI' : '%ct';
296 my @cmd = ('git',
297 git_dir_option $srcdir,
298 qw(log --log-size),
299 ("--pretty=format:%H:$commit_time_format"
300 . ' %an <%ae>%n%n'.$format_string, @ARGV));
301 open PIPE, '-|', @cmd
302 or die ("$ME: failed to run '". quoted_cmd (@cmd) ."': $!\n"
303 . "(Is your Git too old? Version 1.5.1 or later is required.)\n");
304
305 my $prev_multi_paragraph;
306 my $prev_date_line = '';
307 my @prev_coauthors = ();
308 my @skipshas = ();
309 while (1)
310 {
311 defined (my $in = <PIPE>)
312 or last;
313 $in =~ /^log size (\d+)$/
314 or die "$ME:$.: Invalid line (expected log size):\n$in";
315 my $log_nbytes = $1;
316
317 my $log;
318 my $n_read = read PIPE, $log, $log_nbytes;
319 $n_read == $log_nbytes
320 or die "$ME:$.: unexpected EOF\n";
321
322 # Extract leading hash.
323 my ($sha, $rest) = split ':', $log, 2;
324 defined $sha
325 or die "$ME:$.: malformed log entry\n";
326 $sha =~ /^[[:xdigit:]]{40}$/
327 or die "$ME:$.: invalid SHA1: $sha\n";
328
329 my $skipflag = 0;
330 if (@skipshas)
331 {
332 foreach(@skipshas)
333 {
334 if ($sha =~ /^$_/)
335 {
336 $skipflag = $_;
337 last;
338 }
339 }
340 }
341
342 # If this commit's log requires any transformation, do it now.
343 my $code = $amend_code->{$sha};
344 if (defined $code)
345 {
346 eval 'use Safe';
347 my $s = new Safe;
348 # Put the unpreprocessed entry into "$_".
349 $_ = $rest;
350
351 # Let $code operate on it, safely.
352 my $r = $s->reval("$code")
353 or die "$ME:$.:$sha: failed to eval \"$code\":\n$@\n";
354
355 # Note that we've used this entry.
356 delete $amend_code->{$sha};
357
358 # Update $rest upon success.
359 $rest = $_;
360 }
361
362 # Remove lines inserted by "git cherry-pick".
363 if ($strip_cherry_pick)
364 {
365 $rest =~ s/^\s*Conflicts:\n.*//sm;
366 $rest =~ s/^\s*\(cherry picked from commit [\da-f]+\)\n//m;
367 }
368
369 my @line = split /[ \t]*\n/, $rest;
370 my $author_line = shift @line;
371 defined $author_line
372 or die "$ME:$.: unexpected EOF\n";
373 $author_line =~ /^(\S+) (.*>)$/
374 or die "$ME:$.: Invalid line "
375 . "(expected date/author/email):\n$author_line\n";
376
377 # Author <email>
378 my $author = $2;
379
380 my $commit_date = $1;
381 if (! $commit_timezone)
382 {
383 # Seconds since the Epoch.
384 $commit_date = strftime "%Y-%m-%d", localtime ($commit_date);
385 }
386 else
387 {
388 # ISO 8601 date.
389 $commit_date =~ s/T.*$//;
390 }
391
392 # Format 'Copyright-paperwork-exempt: Yes' as a standard ChangeLog
393 # '(tiny change)' annotation.
394 my $tiny = (grep (/^(?:Copyright-paperwork-exempt|Tiny-change):\s+[Yy]es$/, @line)
395 ? ' (tiny change)' : '');
396
397 my $date_line = "$commit_date $author$tiny\n";
398
399 my @coauthors = grep /^Co-authored-by:.*$/, @line;
400 # Omit meta-data lines we've already interpreted.
401 @line = grep !/^(?:Signed-off-by:[ ].*>$
402 |Co-authored-by:[ ]
403 |Copyright-paperwork-exempt:[ ]
404 |Tiny-change:[ ]
405 )/x, @line;
406
407 # Remove leading and trailing blank lines.
408 if (@line)
409 {
410 while ($line[0] =~ /^\s*$/) { shift @line; }
411 while ($line[$#line] =~ /^\s*$/) { pop @line; }
412 }
413
414 # Handle Emacs gitmerge.el "skipped" commits.
415 # Yes, this should be controlled by an option. So sue me.
416 if ( grep /^(; )?Merge from /, @line )
417 {
418 my $found = 0;
419 foreach (@line)
420 {
421 if (grep /^The following commit.*skipped:$/, $_)
422 {
423 $found = 1;
424 ## Reset at each merge to reduce chance of false matches.
425 @skipshas = ();
426 next;
427 }
428 if ($found && $_ =~ /^([[:xdigit:]]{7,}) [^ ]/)
429 {
430 push ( @skipshas, $1 );
431 }
432 }
433 }
434
435 # Ignore commits that match the --ignore-matching pattern, if specified.
436 if (defined $ignore_matching && @line && $line[0] =~ /$ignore_matching/)
437 {
438 $skipflag = 1;
439 }
440 elsif ($skipflag)
441 {
442 ## Perhaps only warn if a pattern matches more than once?
443 warn "$ME: warning: skipping $sha due to $skipflag\n";
444 }
445
446 if (! $skipflag)
447 {
448 if (defined $ignore_line && @line)
449 {
450 @line = grep ! /$ignore_line/, @line;
451 while ($line[$#line] =~ /^\s*$/) { pop @line; }
452 }
453
454 # Record whether there are two or more paragraphs.
455 my $multi_paragraph = grep /^\s*$/, @line;
456
457 # Format 'Co-authored-by: A U Thor <[email protected]>' lines in
458 # standard multi-author ChangeLog format.
459 for (@coauthors)
460 {
461 s/^Co-authored-by:\s*/\t /;
462 s/\s*</ </;
463
464 /<.*?@.*\..*>/
465 or warn "$ME: warning: missing email address for "
466 . substr ($_, 5) . "\n";
467 }
468
469 # If clustering of commit messages has been disabled, if this header
470 # would be different from the previous date/name/etc. header,
471 # or if this or the previous entry consists of two or more paragraphs,
472 # then print the header.
473 if ( ! $cluster
474 || $date_line ne $prev_date_line
475 || "@coauthors" ne "@prev_coauthors"
476 || $multi_paragraph
477 || $prev_multi_paragraph)
478 {
479 $prev_date_line eq ''
480 or print "\n";
481 print $date_line;
482 @coauthors
483 and print join ("\n", @coauthors), "\n";
484 }
485 $prev_date_line = $date_line;
486 @prev_coauthors = @coauthors;
487 $prev_multi_paragraph = $multi_paragraph;
488
489 # If there were any lines
490 if (@line == 0)
491 {
492 warn "$ME: warning: empty commit message:\n"
493 . " commit $sha\n $date_line\n";
494 }
495 else
496 {
497 if ($append_dot)
498 {
499 # If the first line of the message has enough room, then
500 if (length $line[0] < 72)
501 {
502 # append a dot if there is no other punctuation or blank
503 # at the end.
504 $line[0] =~ /[[:punct:]\s]$/
505 or $line[0] .= '.';
506 }
507 }
508
509 # Remove one additional leading TAB from each line.
510 $strip_tab
511 and map { s/^\t// } @line;
512
513 # Prefix each non-empty line with a TAB.
514 @line = map { length $_ ? "\t$_" : '' } @line;
515
516 print "\n", join ("\n", @line), "\n";
517 }
518 }
519
520 defined ($in = <PIPE>)
521 or last;
522 $in ne "\n"
523 and die "$ME:$.: unexpected line:\n$in";
524 }
525
526 close PIPE
527 or die "$ME: error closing pipe from " . quoted_cmd (@cmd) . "\n";
528 # FIXME-someday: include $PROCESS_STATUS in the diagnostic
529
530 # Complain about any unused entry in the --amend=F specified file.
531 my $fail = 0;
532 foreach my $sha (sort keys %$amend_code)
533 {
534 warn "$ME:$amend_file: unused entry: $sha\n";
535 $fail = 1;
536 }
537
538 exit $fail;
539 }
540
541 # Local Variables:
542 # mode: perl
543 # indent-tabs-mode: nil
544 # eval: (add-hook 'before-save-hook 'time-stamp nil t)
545 # time-stamp-line-limit: 50
546 # time-stamp-start: "my $VERSION = '"
547 # time-stamp-format: "%:y-%02m-%02d %02H:%02M"
548 # time-stamp-time-zone: "UTC0"
549 # time-stamp-end: "'; # UTC"
550 # End: