Table of contents:
Target of the project is to provide a framework to write more sensible commit messages for the git scm. Single commit messages should contain one logical change of the project which is described in a standardized way. This results in a much cleaner git history and provides contributors more information about the actual change.
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.
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:
terminal
sudo pacman -S rust cargo
Once these two dependencies are installed, git-journal can be installed via:
terminal
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.
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.
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:
```terminal
git journal [git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch'' [git-journal] [OKAY] Parsing done.
Fixes:
```
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:
```terminal
git journal -u [git-journal] [OKAY] Parsing done.
Using a specific commit range in the format REV..REV or a different starting point than HEAD for parsing can also
be done:
```terminal
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>:
```terminal
git journal -a [git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch'' [git-journal] [OKAY] Parsing done.
```terminal
git journal -un1 [git-journal] [OKAY] Parsing done.
Beside the usual detailed log a short version (-s) exists, which just uses the commit summary:
```terminal
git journal -as [git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch'' [git-journal] [OKAY] Parsing done.
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.
The design of commit message templates is described in RFC0002. From now on we are using this template for the test repository:
```toml [default]
[tag1] name = "Section 1"
[tag1.tag2] footers = ["Fixes"] ```
To use such a template just use the -t option:
```terminal
git journal -t CHANGELOG.toml [git-journal] [INFO] Skipping commit: Summary parsing: 'Merge branch 'test_branch'' [git-journal] [OKAY] Parsing done.
Fixes:
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 tags 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.
To use the automatic commit message preparation and verification the git journal setup has to be executed on every local repository:
```terminal
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:
```terminal
touch myfile git add myfile 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:
```terminal JIRA-1234 Added ...
```
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:
terminal
[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: ```terminal
git commit -m "Added myfile" [git-journal] [OKAY] Commit message prepared. [git-journal] [OKAY] Commit message valid. [master 1b1fcad] Added myfile 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:
-p).-a) or the past n releases (-n).-s).-o).rc tags (-e).You want to contribute to this project? Wow, thanks! So please just fork it and send me a pull request.