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