ft online/ computer/ genchangelog
debian openbsd
hacker keine zielgruppe
vim zsh lover
use-gpg! code perl!

Note, that an extended version of this script of part of zsh-am.

genchangelog: Git history to classic ChangeLog generation script

Sometimes, people like to have a detailed ChangeLog file on top of a proper detailed git commit log. Having to update such a file manually is tedious and unnecessary work. So, the file should really be generated automatically. This script does exactly that.

The genchangelog script (HTML)

How does a ChangeLog file look like?

There is no formal definition I know of, but you can always go with what emacs produces if you execute its `add-change-log-entry'. That looks roughly like this:

2012-01-23  Joe D. Veloper  <jdv@example.tld>

    * list/of/changed/files.c: Descriptive message.

    * more/changed/files.c: Another message.

All indentation is done using ASCII horizontal tabs.

The zsh project uses a numeric prefix to each of the entries, to reference postings to its development mailing list, where usually longer explanations of the commit in question can be found (stuff that you'd put into the actual commit message with git). So it looks something like this:

2012-01-23  Joe D. Veloper  <jdv@example.tld>

    * 12345: list/of/changed/files.c: Descriptive message.

    * 12344: more/changed/files.c: Another message.

People have their own flavours, but that's the format more or less. Long lines are usually wrapped at some point (between 70 and 80 characters).

Okay then, and this script automates this?

Well, you got to call it somehow, but then essentially, yes.

The format generated is a derivative of the zsh project's format, looking like this:

 2012-01-23  Joe D. Veloper  <jdv@example.tld>

     * cafebabe: list/of/changed/files.c: Descriptive message.

     * deadbeef: more/changed/files.c: Another message.

So, the numeric prefix is replaced by an abbreviated version of the commit's hash-sum.

And how to use it?

Simple, you tell the script from where to where you want logs to be generated and it'll go off and produce a file `ChangeLog' (configurable in the script and via a file in the .git directory):

% perl genchangelog -o v3.0 -n v4.0

The fun starts when you have to update an existing file, like shortly before a release:

% perl genchangelog -n v4.0

If the `-o' switch is not there, the script will try to find the last documented commit in `ChangeLog' and use that revision instead (remember how the generated format had an abbreviated version of the hash-sum?).

If exactly one non-option argument is given, used as if it were the argument to the `-n' option. If `-n' (or equal) is left out, `HEAD' is used. Therefore, to get a ChangeLog update, you merely have to call this:

% perl genchangelog

See the top of the script for further details.

Example ChangeLog generation

The following is an example of what would be generated in zsh's git repository using the following:

% perl genchangelog -o zsh-4.3.14 -n zsh-4.3.15

The final result looks like this:

2011-12-17  Peter Stephenson  <pws@users.sourceforge.net>

    * 09532a70: ChangeLog, Config/version.mk, Etc/FAQ.yo, README:
    unposted: release 4.3.15

2011-12-16  Peter Stephenson  <pws@users.sourceforge.net>

    * 0082320b: ChangeLog, Completion/Unix/Command/_subversion: Simon
    Olofsson: fix matching of subversion help text

2011-12-14  Mikael Magnusson  <mikachu@gmail.com>

    * 4264cab6: ChangeLog,
    Completion/Debian/Command/_update-alternatives: 29783:
    _update-alternatives: Add more options.

    * 346c4c46: ChangeLog, Completion/Zsh/Type/_globquals: 30021:
    _globquals: Add d flag, show what unit the digits are entered in.

2011-12-13  Mikael Magnusson  <mikachu@gmail.com>

    * fd1c2364: ChangeLog, Completion/Unix/Command/_tar: 30019: _tar:
    fix parsing of argument to -C.

    * 02dc5c68: ChangeLog, Completion/Unix/Command/_git: 29998: _git:
    fix a typo (--rerbose).

2011-12-13  Bart Schaefer  <barts@users.sourceforge.net>

    * 71996d83: ChangeLog: 30012 and 30020: $state_descr and
    prompt_preview_theme

    * c33f3b07: Functions/Prompts/promptinit: 30020: prevent
    prompt_opts and zle_highlight from leaking out of
    prompt_preview_theme

    * 3f98949c: Completion/Base/Core/_main_complete,
    Completion/Base/Utility/_arguments,
    Completion/Base/Utility/_values, Completion/Zsh/Command/_zle,
    Doc/Zsh/compsys.yo: 30012: add $state_descr

2011-12-12  Peter Stephenson  <pws@users.sourceforge.net>

    * 93139f39: ChangeLog, Src/exec.c: 30000 plus some comments:
    Better POSIXJOBs behaviour. Don't restore default SIGTTOU etc.
    behaviour if still doing job control. Only carry on doing job
    control in subshell if it's a real (...) subshell

2011-12-11  Peter Stephenson  <pws@users.sourceforge.net>

    * 290ab118: ChangeLog, Doc/Zsh/compsys.yo: discussed in 29984: use
    m+7 for files more than a week old

    * acb97e61: ChangeLog, Doc/Zsh/expn.yo, Src/glob.c: 29991: allow
    explicit "d" for days in time qualifiers

2011-12-10  Mikael Magnusson  <mikachu@gmail.com>

    * a7794bd1: ChangeLog, Completion/Unix/Command/_ssh: 29961: _ssh:
    extend option completion.

    * ac78bd01: ChangeLog, Completion/Unix/Command/_ssh: 29962:
    Actually return ret in _ssh.

2011-12-10  Peter Stephenson  <pws@users.sourceforge.net>

    * 3346803f: ChangeLog: Fix ChangeLog --- last entry was added in
    the middle instead of the top

    * 2b4e0140: ChangeLog, Completion/Linux/Command/_modutils: GI:
    29977: caching and function definition fixes for _modutils

2011-12-10  Bart Schaefer  <barts@users.sourceforge.net>

    * 48c46fe9: ChangeLog: Fix some zsh-users article references that
    have transposed or off-by-one digits.

2011-12-09  Simon Ruderich  <rudi_s@users.sourceforge.net>

    * d374f2b1: ChangeLog, Completion/Base/Utility/.distfiles,
    Completion/Base/Utility/_remote_files,
    Completion/Unix/Command/_git, Completion/Unix/Command/_rlogin,
    Completion/Unix/Command/_rsync, Completion/Unix/Command/_ssh:
    29918: Completion: Add new _remote_files() helper and use it to
    reduce code duplication.

    * 3e114667: ChangeLog, Completion/Unix/Command/_ssh: 29917:
    Completion/Unix/Command/_ssh: Tabs to spaces.

2011-12-09  Mikael Magnusson  <mikachu@gmail.com>

    * df2140e4: ChangeLog, Completion/X/Command/_x_utils,
    Completion/X/Type/_x_font: 29409: Add xprop and xlsatoms
    completions.

    * 9d83e165: ChangeLog, Doc/Zsh/compsys.yo: unposted: remove
    duplicated 'the' in compsys.yo.

2011-12-09  Peter Stephenson  <pws@users.sourceforge.net>

    * 94ef211b: ChangeLog, Completion/compinit: unposted: add
    NO_ignoreclosebraces to options for completion

    * 87151e8b: ChangeLog, config.guess, config.sub: users/16614:
    update config.guess and config.sub from automake 1.11.1

2011-12-09  Mikael Magnusson  <mikachu@gmail.com>

    * 86df8f16: ChangeLog: unposted: fix typo in ChangeLog

    * 45cd289e: ChangeLog, Completion/Unix/Command/_getent: 29876:
    Update getent completion.

2011-12-08  Peter Stephenson  <pws@users.sourceforge.net>

    * e3182c18: ChangeLog, Doc/Zsh/grammar.yo, Doc/Zsh/options.yo,
    Src/lex.c, Src/options.c, Src/zsh.h, Test/E01options.ztst:
    29955++: IGNORE_CLOSE_BRACES option

    * 22aede45: ChangeLog, Test/A04redirect.ztst: 29928: belated
    commit to fix OpenBSD redirection test

2011-12-07  Peter Stephenson  <pws@users.sourceforge.net>

    * b0182829: ChangeLog, Config/version.mk: Update version to
    4.3.14-dev-0

2011-12-07  Oliver Kiddle  <opk@users.sourceforge.net>

    * fe1dc510: ChangeLog, Src/glob.c: 29952: fix cut'n'paste error in
    Nanosecond timestamp support