git-journal 0.3.0

The Git Commit Message and Changelog Generation Framework
Documentation

git-journal 📖

The Git Commit Message and Changelog Generation Framework

Crates.io License MIT Build Status Coverage Status doc gitjournal doc.rs

Table of contents:

TL;DR

Furthermore it should be easier to generate nice looking changelogs directly from your commit history. This is where git-journal solves common problems.

Two RFCs, one for a commit message syntax extension and another for the output templating engine is the base for this.

Installation

To use git-journal as a git extension a Rust installation is needed including the package manager cargo. Different package managers will provide these as well, for example via Pacman on Arch Linux:

sudo pacman -S rust cargo

Once these two dependencies are installed, git-journal can be installed via:

cargo install git-journal

After adapting your $PATH variable to search also within ~/.cargo/bin it should be possible to run it by invoking git journal.

Usage

The binary git-journal depends on the Rust library gitjournal, which also can be used independently from the binary application to write customized solutions. This repository will be used as an example for the following explanations.

Default output

If you run git journal anywhere inside this repository, the output will be a nice looking Markdown formatted changelog based on your repositories git log:

> git journal
[git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch''
[git-journal] [OKAY] Parsing done.

# Unreleased (2016-09-18):
- [Added] file4 again
    This paragraph explains the change in detail
    - [Fixed] multiple issues
    - [Removed] not needed things
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

Fixes:
#1, #2

# v2 (2016-09-12):
- [Added] file3.txt

All commits are sorted by time, which means that the newest elements occur at the top. The parsing of the commit message will be done regarding RFC0001, which describes the different syntax elements within a commit message. Categories ([Added], [Fixed], ...) are automatically wrapped in square brackets if available. The journal automatically lists the log from the last release and the unreleased entries.

The footers of the commit messages (described in RFC0001) are automatically accumulated and printed after the changelog list ordered by their values. It is also possible to skip the unreleased entries:

> git journal -u
[git-journal] [OKAY] Parsing done.

# v2 (2016-09-12):
- [Added] file3.txt

Using a specific commit range in the format REV..REV or a different starting point than HEAD for parsing can also be done:

> git journal v1
> git journal v2
> git journal v1...HEAD^

It is also possible to print all releases (git tags) with -a, the past n releases via -n <COUNT>:

> git journal -a
[git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch''
[git-journal] [OKAY] Parsing done.

# Unreleased (2016-09-18):
- [Added] file4 again
    This paragraph explains the change in detail
    - [Fixed] multiple issues
    - [Removed] not needed things
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

# v2 (2016-09-12):
- [Added] file3.txt

# v1 (2016-09-12):
- [Added] file2.txt
- [Added] file1.txt

> git journal -un1
[git-journal] [OKAY] Parsing done.

# v2 (2016-09-12):
- [Added] file3.txt

Beside the usual detailed log a short version (-s) exists, which just uses the commit summary:

> git journal -as
[git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch''
[git-journal] [OKAY] Parsing done.

# Unreleased (2016-09-18):
- [Added] file4 again
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

# v2 (2016-09-12):
- [Added] file3.txt

# v1 (2016-09-12):
- [Added] file2.txt
- [Added] file1.txt

It also possible to append the output of the journal to a file (-o), which will be separated by a newline (---) for each git journal invocation. Git tags with a specific patterns like rc will be excluded automatically, which can be customized via -e.

For more information please refer to the help git journal -h.

Template output

The design of commit message templates is described in RFC0002. From now on we are using this template for the test repository:

[[tag]]
tag = "default"
name = "Default"

[[tag]]
tag = "tag1"
name = "Section 1"

[[tag]]
[[tag.subtag]]
tag = "tag2"
name = "Subsection 1"
footers = ["Fixes"]

To use such a template just use the -t option:

> git journal -t CHANGELOG.toml
[git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch''
[git-journal] [OKAY] Parsing done.

# Unreleased (2016-09-21):
## Default
- [Removed] file3.txt
- [Removed] file4.txt
- [Removed] file5.txt
- [Added] new .gitjournal
- [Improved] file5.txt
- [Fixed] this
- [Removed] that
- [Added] .gitjournal.toml file
- [Removed] not needed things
- [Removed] file4.txt
- [Added] file4.txt
- [Added] file1.txt again
- [Removed] file1.txt

## Section 1
- [Added] file4 again
- This paragraph explains the change in detail

### Subsection 1
- [Fixed] multiple issues

Fixes:
#1, #2, #1, #2, #3, #5, #6, #7

# v2 (2016-09-12):
## Default
- [Added] file3.txt

Everything which is untagged will go into the default section. The name of tag1 will be mapped to Section 1 and tag2 is a subtag of tag1 (see the markdown header). This also means that it is now possible that list items are uncategorized since the templating engine gives the possibility to split commits into multiple pieces. Parsed paragraphs are converted to single list items to always provide a clean markdown. The footers are specified as an toml array of strings which will output the selected footer keys at the correct position of the log. Please consider that the accumulation of the footers are related to the complete tag, not just the section where there printed. Other command line options like in the default output are available as well.

Commit message preparation and verification

To use the automatic commit message preparation and verification the git journal setup has to be executed on every local repository:

> git journal setup
[git-journal] [OKAY] Defaults written to '.gitjournal.toml' file.
[git-journal] [OKAY] Git hook installed to '.git/hooks/commit-msg'.
[git-journal] [OKAY] Git hook installed to '.git/hooks/prepare-commit-msg'.
[git-journal] [OKAY] Installed bash completions to your current working path.
[git-journal] [OKAY] Installed fish completions to your current working path.

If there already exists these hooks git-journal tries to append the needed commands, which has to be verified by hand afterwards. The generated command line completions for bash and fish needs to be put in the correct directory of your shell. The default configuration file is a toml file which represents this structure. A default configuration with comments can also be found here.

If the setup is done git-journal will verify your inserted commit message as well as doing a preparation. For example, if we are now trying to commit something which can not be parsed:

> touch my_file
> git add my_file
> git commit -m "This commit contains no cactegory"
[git-journal] [ERROR] Commit message preparation failed: GitJournal: Parser: Summary parsing: 'This commit contains no cactegory'

Since we are using the -m flag there is no chance for the user to edit the message any more and git-journal will reject it. If we are using a commit message editor via the usual git commit without the -m we will get a default commit message template:

JIRA-1234 Added ...

# Add a more detailed description if needed

# - Added ...
# - Changed ...
# - Fixed ...
# - Improved ...
# - Removed ...

The JIRA-1234 prefix is just the default and can be configured via the .gitjournal.toml file. If the submitted commit message is also invalid we will get an error like this:

[git-journal] [ERROR] Commit message invalid: GitJournal: Parser: Summary parsing: 'This commit message is also invalid'

If everything went fine it should look like this:

> git commit -m "Added my_file"
[git-journal] [OKAY] Commit message prepared.
[git-journal] [OKAY] Commit message valid.
[master 1b1fcad] Added my_file
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 my_file

This means in detail that git-journal will build up two gates (one for preparation and one for verification) during doing the commit by the user. This graphic will sum up where git-journal will take influence on the local git repository:

Current Features

  • General
    • Generation of completions for bash and fish shell during setup.
  • Journal generation and output
    • Automatic up-level repository search if a sub path of a git repository was specified.
    • Custom commit ranges or different git commit starting points for parsing.
    • Run in a different specified path than the current working directory (-p).
    • Parse and print the complete history (-a) or the past n releases (-n).
    • Print a short version of the commit history based on the commit message summary (-s).
    • Output the parsed log in valid Markdown to the command line or a file (-o).
    • Custom git tag exclude pattern, e.g. rc tags (-e).
    • Enable/Disable debug message output.
    • Enable/Disable colored output via the command line.
    • Automatic wrapping of commit message categories in square brackets.
    • Templating support including tag and name mapping.
    • Support for accumulating footer data (also for templating engine).
  • Preparation and Verification of commit messages
    • Automatic installation of git hooks inside the local repository.
    • Generation of default configuration file during setup.
    • Commit message validation based on implemented parser.
    • Message preparation with custom commit prefix (config) and differentiation between amended and new commits

Planned features and improvements

  • Custom category support.
  • Custom commit message template support, which will be used for commit preparation.
  • Multiple template extensions, like custom header/footer or other different custom fields.
  • Generation of default templates based on commits within a given commit rage.
  • Custom sorting methods for the default and template based output.
  • Commit message validation via provided template

Contributing

You want to contribute to this project? Wow, thanks! So please just fork it and send me a pull request.