Git Changelog

An application for generating a changelog from git commit tree

https://gitlab.com/claudiomattera/git-changes

Installation

Executables can be downloaded in the releases page.

If the executable git-changes is put inside a directory included in the PATH environment variable, a new git subcommand changelog is available.

~~~~shell git changelog /path/to/git/repository > changelog.txt ~~~~

Installation from Source

This is a Rust application and can be installed using Cargo.

~~~~shell cargo install git-changes ~~~~

Usage

This application makes the following assumptions about the git commit tree.

Version names follow [Semantic Versioning] format;
Available versions are encoded in git tags (tags not matching the format are ignored);
Versions are developed in sequence;
Changes are encoded in commits following a certain format (commit not matching such format are ignored).

The application looks at the commit tree and considers all changes between each pair of subsequent versions. then it creates a Markdown changelog listing all changes for each version and prints it to standard output.

~~~~plain git-changes 0.1.0 Claudio Giovanni Mattera dev@claudiomattera.it Generate changelog from git commit tree

USAGE: git-changes [FLAGS] [OPTIONS]

FLAGS: --add-tag-description Add version description from tag messages -h, --help Prints help information -o, --only-last Only last version changes --strip-gpg-signature Strip GPG signature from version descriptions -V, --version Prints version information -v, --verbose Verbosity

OPTIONS: -c, --commit-regex Commit message regular expression [default: (.+)\s+(issue\s+#(\d+))]

-r, --commit-replacement <commit-replacement>    Commit message replacement text [default: ${1} (issue ${2})]
-d, --head-description <head-description>        Set the current head description
-i, --include-head <include-head>                Include the current head as last version
-s, --select-version <selected-versions>...      Generate changelog for selected versions

ARGS: Repository path ~~~~

Example

Consider the following commit log.

This application will generate the following Markdown changelog.

~~~~markdown

Version 0.2.0 (2021-07-07)

Add file d (issue #4)
Add file c (issue #3)

Version 0.1.0 (2021-07-07)

Add other file (issue #2)
Add file (issue #1) ~~~~

Select and Convert Commit Messages

Commit messages are selected for changelog according to a regular expression passed via the command-line argument --commit-regex, and converted by substituting the pattern passed via --commit-replacement. Default values are, respectively, (.+)\s+$issue\s+#(\d+)$ and ${1} (issue ${2}).

In order to include links to the repository issues in the changelog, use something like:

~~~~plain ${1} (issue ${2})` ~~~~

Include Current Head

It is possible to generate a changelog for the current head, so that it can be included in the upcoming git tag.

In the following example, the version 1.0.3 is assigned to the current head.

~~~~shell git-changes --include-head 1.0.3 ~~~~

Include Tag Descriptions in Changelog

The tag message can be used as a summary before the list of changes in the changelog.

~~~~shell git-changes --add-tag-description ~~~~

This application will generate the following Markdown changelog.

~~~~markdown

Version 0.2.0 (2021-07-07)

This is the text in the tag message.

It can contain arbitrary text, it is not parsed as Markdown, but copied verbatim.

Add file d (issue #4)
Add file c (issue #3)

Version 0.1.0 (2021-07-07)

Add other file (issue #2)
Add file (issue #1) ~~~~

In case tags are signed, the flag --strip-gpg-signature will strip the signature in the changelog.

License

You are free to copy, modify, and distribute this application with attribution under the terms of the [MPL 2.0 license]. See the License.txt file for details.