doc/gitlog-to-changelog.texi

   1 @node gitlog-to-changelog
   2 @section gitlog-to-changelog
   3
   4 @c Copyright (C) 2024 Free Software Foundation, Inc.
   5
   6 @c Permission is granted to copy, distribute and/or modify this document
   7 @c under the terms of the GNU Free Documentation License, Version 1.3 or
   8 @c any later version published by the Free Software Foundation; with no
   9 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  10 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
  11
  12 @cindex gitlog
  13 @cindex changelog
  14 @mindex gitlog-to-changelog
  15
  16 Gnulib has a module @code{gitlog-to-changelog} to parse @code{git log}
  17 output and generate @file{ChangeLog} files; see
  18 @ifinfo
  19 @ref{Change Logs,,,standards}.
  20 @end ifinfo
  21 @ifnotinfo
  22 @url{https://www.gnu.org/prep/standards/html_node/Change-Logs.html}.
  23 @end ifnotinfo
  24
  25 You can use it by extending the @code{dist-hook} rule in the
  26 top-level @file{Makefile.am} like this:
  27
  28 @example
  29 dist-hook: gen-ChangeLog
  30 .PHONY: gen-ChangeLog
  31 gen-ChangeLog:
  32         $(AM_V_GEN)if test -e .git; then                       \
  33           LC_ALL=en_US.UTF-8 TZ=UTC0                           \
  34             $(top_srcdir)/build-aux/gitlog-to-changelog        \
  35               > $(distdir)/ChangeLog.tmp &&                    \
  36           mv -f $(distdir)/ChangeLog.tmp $(distdir)/ChangeLog; \
  37         fi
  38 @end example
  39
  40 See @code{gitlog-to-changelog --help} for complete documentation.
  41
  42 The @code{LC_ALL=en_US.UTF-8 TZ=UTC0} line in this recipe assumes that
  43 you want to generate reproducible @file{ChangeLog} files that do not
  44 depend on the developer's locale and time zone.  Omit this line if you
  45 prefer @file{ChangeLog} files that depend on these developer settings.
  46
  47 If you wish to output the @file{ChangeLog} with dates respecting the
  48 time zone each individual commit was made in you can use the
  49 @option{--commit-timezone} option.  For example:
  50
  51 @example
  52 dist-hook: gen-ChangeLog
  53 .PHONY: gen-ChangeLog
  54 gen-ChangeLog:
  55         $(AM_V_GEN)if test -e .git; then                       \
  56           $(top_srcdir)/build-aux/gitlog-to-changelog          \
  57             --commit-timezone > $(distdir)/ChangeLog.tmp &&    \
  58           mv -f $(distdir)/ChangeLog.tmp $(distdir)/ChangeLog; \
  59         fi
  60 @end example
  61
  62 The use of @option{--commit-timezone} means that @file{ChangeLog} dates
  63 correctly represent when a committer pushed a change according to their
  64 time zone.  However, as a consequence @file{ChangeLog} dates will no
  65 longer be monotonically increasing, if the developers are spread across
  66 different time zones.
  67 For example, the following three commits were made in a short period of
  68 time across two different time zones.
  69 This behavior may be undesired.
  70
  71 @example
  72 2024-06-19  Bruno Haible  <bruno@@clisp.org>
  73
  74         ...
  75
  76 2024-06-18  Collin Funk  <collin.funk1@@gmail.com>
  77
  78         ...
  79
  80 2024-06-19  Bruno Haible  <bruno@@clisp.org>
  81
  82         ...
  83 @end example
  84
  85 If you wish to limit the @file{ChangeLog} entries (perhaps for size
  86 issues) to contain only entries since a particular git tag, you can
  87 use a @code{gen-ChangeLog} rule like the following:
  88
  89 @example
  90 gen_start_ver = 8.31
  91 gen-ChangeLog:
  92         $(AM_V_GEN)if test -e .git; then                           \
  93           log_fix='$(srcdir)/build-aux/git-log-fix';               \
  94           test -e "$$log_fix"                                      \
  95             && amend_git_log=--amend=$$log_fix                     \
  96             || amend_git_log=;                                     \
  97           @{ LC_ALL=en_US.UTF-8 TZ=UTC0                             \
  98               $(top_srcdir)/build-aux/gitlog-to-changelog          \
  99                 "$$amend_git_log" -- 'v$(gen_start_ver)~..' &&     \
 100             printf '\n\nSee the source repo for older entries.\n'; \
 101           @} > $(distdir)/ChangeLog.tmp &&                          \
 102           mv -f $(distdir)/ChangeLog.tmp $(distdir)/ChangeLog;     \
 103         fi
 104 @end example