From dc2886c010dc34665370be055b2d93ff9aed68d2 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Thu, 4 Jul 2024 00:31:33 +0100 Subject: [PATCH] gitlog-to-changelog: improve doc --- doc/gitlog-to-changelog.texi | 70 ++++++++++++++---------------------- 1 file changed, 27 insertions(+), 43 deletions(-) diff --git a/doc/gitlog-to-changelog.texi b/doc/gitlog-to-changelog.texi index 137b15fcda..5dc1043e45 100644 --- a/doc/gitlog-to-changelog.texi +++ b/doc/gitlog-to-changelog.texi @@ -12,8 +12,8 @@ @cindex gitlog @cindex changelog -Gnulib have a module @code{gitlog-to-changelog} to parse @code{git log} -output and generate @code{ChangeLog} files, see +Gnulib has a module @code{gitlog-to-changelog} to parse @code{git log} +output and generate @file{ChangeLog} files; see @ifinfo @ref{Change Logs,,,standards}. @end ifinfo @@ -21,61 +21,45 @@ output and generate @code{ChangeLog} files, see @url{https://www.gnu.org/prep/standards/html_node/Change-Logs.html}. @end ifnotinfo -You would typically use it by extending the @code{dist-hook} in the -top-level @code{Makefile.am} like this: +You can use it by extending the @code{dist-hook} rule in the +top-level @file{Makefile.am} like this: @example dist-hook: gen-ChangeLog -... .PHONY: gen-ChangeLog gen-ChangeLog: - $(AM_V_GEN)if test -e .git; then \ - $(top_srcdir)/build-aux/gitlog-to-changelog > \ - $(distdir)/cl-t && \ - @{ rm -f $(distdir)/ChangeLog && \ - mv $(distdir)/cl-t $(distdir)/ChangeLog; @} \ + $(AM_V_GEN)if test -e .git; then \ + LC_ALL=en_US.UTF-8 TZ=UTC0 \ + $(top_srcdir)/build-aux/gitlog-to-changelog \ + > $(distdir)/ChangeLog.tmp && \ + mv -f $(distdir)/ChangeLog.tmp $(distdir)/ChangeLog; \ fi @end example See @code{gitlog-to-changelog --help} for complete documentation. -The tool prints timestamps using @code{localtime}, so its output may be -different depending on what locale the developer that runs the tool is -using. If your project desire reproducible ChangeLog files that doesn't -depend on locale settings, use something like the following. +The @code{LC_ALL=en_US.UTF-8 TZ=UTC0} line in this recipe assumes that +you want to generate reproducible @file{ChangeLog} files that do not +depend on the developer's locale and time zone. Omit this line if you +prefer @file{ChangeLog} files that depend on these developer settings. -@example -gen-ChangeLog: - $(AM_V_GEN)if test -e .git; then \ - env LC_ALL=en_US.UTF-8 TZ=UTC=0 \ - $(top_srcdir)/build-aux/gitlog-to-changelog > \ - $(distdir)/cl-t && \ - @{ rm -f $(distdir)/ChangeLog && \ - mv $(distdir)/cl-t $(distdir)/ChangeLog; @} \ - fi -@end example - - -If you wish to limit the ChangeLog entries (perhaps for size issues) to -only contain entries since a particular git tag, use something like the -following: +If you wish to limit the @file{ChangeLog} entries (perhaps for size +issues) to contain only entries since a particular git tag, you can +use a @code{gen-ChangeLog} rule like the following: @example -dist-hook: gen-ChangeLog -... gen_start_ver = 8.31 -.PHONY: gen-ChangeLog gen-ChangeLog: - $(AM_V_GEN)if test -e .git; then \ - log_fix="$(srcdir)/build-aux/git-log-fix"; \ - test -e "$$log_fix" \ - && amend_git_log="--amend=$$log_fix" \ - || amend_git_log=; \ - $(top_srcdir)/build-aux/gitlog-to-changelog $$amend_git_log \ - -- v$(gen_start_ver)~.. > $(distdir)/cl-t && \ - @{ printf '\n\nSee the source repo for older entries\n' \ - >> $(distdir)/cl-t && \ - rm -f $(distdir)/ChangeLog && \ - mv $(distdir)/cl-t $(distdir)/ChangeLog; @} \ + $(AM_V_GEN)if test -e .git; then \ + log_fix='$(srcdir)/build-aux/git-log-fix'; \ + test -e "$$log_fix" \ + && amend_git_log=--amend=$$log_fix \ + || amend_git_log=; \ + @{ LC_ALL=en_US.UTF-8 TZ=UTC0 \ + $(top_srcdir)/build-aux/gitlog-to-changelog \ + "$$amend_git_log" -- 'v$(gen_start_ver)~..' && \ + printf '\n\nSee the source repo for older entries.\n'; \ + @} > $(distdir)/ChangeLog.tmp && \ + mv -f $(distdir)/ChangeLog.tmp $(distdir)/ChangeLog; \ fi @end example -- 2.39.5