4 # Convert git log output to ChangeLog format.
6 # Copyright (C) 2008-2024 Free Software Foundation, Inc.
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.
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.
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/>.
21 # Written by Jim Meyering
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" "$@"'
38 my
$VERSION = '2024-07-04 10:56'; # 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.
47 use POSIX qw
(strftime
);
49 (my
$ME = $0) =~ s|.
*/||
;
51 # use File::Coda; # https://meyering.net/code/Coda/
53 defined fileno STDOUT or
return;
54 close STDOUT and
return;
55 warn
"$ME: failed to close standard output: $!\n";
62 my
$STREAM = ($exit_code == 0 ?
*STDOUT
: *STDERR
);
65 print
$STREAM "Try '$ME --help' for more information.\n";
70 Usage: $ME [OPTIONS] [ARGS]
72 Convert git log output to ChangeLog format. If present, any ARGS
73 are passed to "git log". To avoid ARGS being parsed as options to
74 $ME, they may be preceded by '--'.
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 --commit-timezone use dates respecting the timezone commits were made in.
101 --help display this help and exit
102 --version output version information and exit
106 $ME --since=2008-01-01 > ChangeLog
107 $ME -- -n 5 foo > last-5-commits-to-branch-foo
111 The following types of strings are interpreted specially when they appear
112 at the beginning of a log message line. They are not copied to the output.
114 Copyright-paperwork-exempt: Yes
115 Append the "(tiny change)" notation to the usual "date name email"
116 ChangeLog header to mark a change that does not require a copyright
118 Co-authored-by: Joe User <user\@example.com>
119 List the specified name and email address on a second
120 ChangeLog header, denoting a co-author.
121 Signed-off-by: Joe User <user\@example.com>
122 These lines are simply elided.
124 In a FILE specified via --amend, comment lines (starting with "#") are ignored.
125 FILE must consist of <SHA,CODE+> pairs where SHA is a 40-byte SHA1 (alone on
126 a line) referring to a commit in the current project, and CODE refers to one
127 or more consecutive lines of Perl code. Pairs must be separated by one or
130 Here is sample input for use with --amend=FILE, from coreutils:
132 3a169f4c5d9159283548178668d2fae6fced3030
134 s/all tile types/all file types/
136 1379ed974f1fa39b12e2ffab18b3f7a607082202
137 # Due to a bug in vc-dwim, I mis-attributed a patch by Paul to myself.
138 # Change the author to be Paul. Note the escaped "@":
139 s,Jim .*>,Paul Eggert <eggert\\\@cs.ucla.edu>,
146 # If the string $S is a well-behaved file name, simply return it.
147 # If it contains white space, quotes, etc., quote it, and return the new string.
151 if ($s =~ m
![^\w
+/.
,-]!)
153 # Convert each single quote to '\''
154 $s =~ s
/\'/\'\\\'\'/g
;
155 # Then single quote the string.
163 return join (' ', map
{shell_quote
$_} @_
);
167 # Comment lines (starting with "#") are ignored.
168 # F must consist of <SHA,CODE+> pairs where SHA is a 40-byte SHA1
169 # (alone on a line) referring to a commit in the current project, and
170 # CODE refers to one or more consecutive lines of Perl code.
171 # Pairs must be separated by one or more blank line.
172 sub parse_amend_file
($
)
177 or die
"$ME: $f: failed to open for reading: $!\n";
183 while (defined
(my
$line = <F
>))
189 and
$in_code = 0, next
;
193 $line =~
/^
([[:xdigit
:]]{40})$
/
194 or
(warn
"$ME: $f:$.: invalid line; expected an SHA1\n"),
199 and
(warn
"$ME: $f:$.: duplicate SHA1\n"),
205 $h->{$sha} .
= "$line\n";
216 # git_dir_option $SRCDIR
218 # From $SRCDIR, the --git-dir option to pass to git (none if $SRCDIR
219 # is undef). Return as a list (0 or 1 element).
220 sub git_dir_option
($
)
226 my
$qdir = shell_quote
$srcdir;
227 my
$cmd = "cd $qdir && git rev-parse --show-toplevel";
228 my
$qcmd = shell_quote
$cmd;
229 my
$git_dir = qx
($cmd);
231 or die
"$ME: cannot run $qcmd: $!\n";
233 or die
"$ME: $qcmd had unexpected exit code or signal ($?)\n";
235 push @res
, "--git-dir=$git_dir/.git";
243 my
$format_string = '%s%n%b%n';
250 my
$strip_cherry_pick = 0;
251 my
$commit_timezone = 0;
255 help => sub
{ usage
0 },
256 version
=> sub
{ print
"$ME version $VERSION\n"; exit },
257 'since=s' => \
$since_date,
258 'until=s' => \
$until_date,
259 'format=s' => \
$format_string,
260 'amend=s' => \
$amend_file,
261 'append-dot' => \
$append_dot,
262 'cluster!' => \
$cluster,
263 'ignore-matching=s' => \
$ignore_matching,
264 'ignore-line=s' => \
$ignore_line,
265 'strip-tab' => \
$strip_tab,
266 'strip-cherry-pick' => \
$strip_cherry_pick,
267 'commit-timezone' => \
$commit_timezone,
268 'srcdir=s' => \
$srcdir,
272 and unshift @ARGV
, "--since=$since_date";
274 and unshift @ARGV
, "--until=$until_date";
276 # This is a hash that maps an SHA1 to perl code (i.e., s/old/new/)
277 # that makes a correction in the log or attribution of that commit.
278 my
$amend_code = defined
$amend_file ? parse_amend_file
$amend_file : {};
280 my
$commit_time_format = $commit_timezone ?
'%cI' : '%ct';
282 git_dir_option
$srcdir,
284 ("--pretty=format:%H:$commit_time_format"
285 .
' %an <%ae>%n%n'.
$format_string, @ARGV
));
286 open PIPE
, '-|', @cmd
287 or die
("$ME: failed to run '". quoted_cmd
(@cmd
) .
"': $!\n"
288 .
"(Is your Git too old? Version 1.5.1 or later is required.)\n");
290 my
$prev_multi_paragraph;
291 my
$prev_date_line = '';
292 my @prev_coauthors
= ();
296 defined
(my
$in = <PIPE
>)
298 $in =~
/^log size
(\d
+)$
/
299 or die
"$ME:$.: Invalid line (expected log size):\n$in";
303 my
$n_read = read PIPE
, $log, $log_nbytes;
304 $n_read == $log_nbytes
305 or die
"$ME:$.: unexpected EOF\n";
307 # Extract leading hash.
308 my
($sha, $rest) = split ':', $log, 2;
310 or die
"$ME:$.: malformed log entry\n";
311 $sha =~
/^
[[:xdigit
:]]{40}$
/
312 or die
"$ME:$.: invalid SHA1: $sha\n";
327 # If this commit's log requires any transformation, do it now.
328 my
$code = $amend_code->{$sha};
333 # Put the unpreprocessed entry into "$_".
336 # Let $code operate on it, safely.
337 my
$r = $s->reval
("$code")
338 or die
"$ME:$.:$sha: failed to eval \"$code\":\n$@\n";
340 # Note that we've used this entry.
341 delete
$amend_code->{$sha};
343 # Update $rest upon success.
347 # Remove lines inserted by "git cherry-pick".
348 if ($strip_cherry_pick)
350 $rest =~ s
/^\s
*Conflicts
:\n.
*//sm
;
351 $rest =~ s
/^\s
*\
(cherry picked from commit
[\da-f
]+\
)\n//m
;
354 my @line
= split /[ \t]*\n/, $rest;
355 my
$author_line = shift @line
;
357 or die
"$ME:$.: unexpected EOF\n";
358 $author_line =~
/^
(\S
+) (.
*>)$
/
359 or die
"$ME:$.: Invalid line "
360 .
"(expected date/author/email):\n$author_line\n";
365 my
$commit_date = $1;
366 if (! $commit_timezone)
368 # Seconds since the Epoch.
369 $commit_date = strftime
"%Y-%m-%d", localtime
($commit_date);
374 $commit_date =~ s
/T.
*$
//;
377 # Format 'Copyright-paperwork-exempt: Yes' as a standard ChangeLog
378 # '(tiny change)' annotation.
379 my
$tiny = (grep (/^
(?
:Copyright-paperwork-exempt|Tiny-change
):\s
+[Yy
]es$
/, @line
)
380 ?
' (tiny change)' : '');
382 my
$date_line = "$commit_date $author$tiny\n";
384 my @coauthors
= grep /^Co-authored-by
:.
*$
/, @line
;
385 # Omit meta-data lines we've already interpreted.
386 @line
= grep !/^
(?
:Signed-off-by
:[ ].
*>$
388 |Copyright-paperwork-exempt
:[ ]
392 # Remove leading and trailing blank lines.
395 while ($line[0] =~
/^\s
*$
/) { shift @line
; }
396 while ($line[$#line] =~
/^\s
*$
/) { pop @line
; }
399 # Handle Emacs gitmerge.el "skipped" commits.
400 # Yes, this should be controlled by an option. So sue me.
401 if ( grep /^
(; )?Merge from
/, @line
)
406 if (grep /^The following commit.
*skipped
:$
/, $_)
409 ## Reset at each merge to reduce chance of false matches.
413 if ($found && $_ =~
/^
([[:xdigit
:]]{7,}) [^
]/)
415 push
( @skipshas
, $1 );
420 # Ignore commits that match the --ignore-matching pattern, if specified.
421 if (defined
$ignore_matching && @line
&& $line[0] =~
/$ignore_matching/)
427 ## Perhaps only warn if a pattern matches more than once?
428 warn
"$ME: warning: skipping $sha due to $skipflag\n";
433 if (defined
$ignore_line && @line
)
435 @line
= grep ! /$ignore_line/, @line
;
436 while ($line[$#line] =~
/^\s
*$
/) { pop @line
; }
439 # Record whether there are two or more paragraphs.
440 my
$multi_paragraph = grep /^\s
*$
/, @line
;
442 # Format 'Co-authored-by: A U Thor <email@example.com>' lines in
443 # standard multi-author ChangeLog format.
446 s
/^Co-authored-by
:\s
*/\t /;
450 or warn
"$ME: warning: missing email address for "
451 . substr
($_, 5) .
"\n";
454 # If clustering of commit messages has been disabled, if this header
455 # would be different from the previous date/name/etc. header,
456 # or if this or the previous entry consists of two or more paragraphs,
457 # then print the header.
459 ||
$date_line ne
$prev_date_line
460 ||
"@coauthors" ne
"@prev_coauthors"
462 ||
$prev_multi_paragraph)
464 $prev_date_line eq
''
468 and print
join ("\n", @coauthors
), "\n";
470 $prev_date_line = $date_line;
471 @prev_coauthors
= @coauthors
;
472 $prev_multi_paragraph = $multi_paragraph;
474 # If there were any lines
477 warn
"$ME: warning: empty commit message:\n"
478 .
" commit $sha\n $date_line\n";
484 # If the first line of the message has enough room, then
485 if (length
$line[0] < 72)
487 # append a dot if there is no other punctuation or blank
489 $line[0] =~
/[[:punct
:]\s
]$
/
494 # Remove one additional leading TAB from each line.
496 and map
{ s
/^
\t// } @line
;
498 # Prefix each non-empty line with a TAB.
499 @line
= map
{ length
$_ ?
"\t$_" : '' } @line
;
501 print
"\n", join ("\n", @line
), "\n";
505 defined
($in = <PIPE
>)
508 and die
"$ME:$.: unexpected line:\n$in";
512 or die
"$ME: error closing pipe from " . quoted_cmd
(@cmd
) .
"\n";
513 # FIXME-someday: include $PROCESS_STATUS in the diagnostic
515 # Complain about any unused entry in the --amend=F specified file.
517 foreach my
$sha (sort keys
%$amend_code)
519 warn
"$ME:$amend_file: unused entry: $sha\n";
528 # indent-tabs-mode: nil
529 # eval: (add-hook 'before-save-hook 'time-stamp nil t)
530 # time-stamp-line-limit: 50
531 # time-stamp-start: "my $VERSION = '"
532 # time-stamp-format: "%:y-%02m-%02d %02H:%02M"
533 # time-stamp-time-zone: "UTC0"
534 # time-stamp-end: "'; # UTC"