This tool generates a release log from a git repository.
Its hard or even impossible to generate good releaselog from an ordinary git log. The git log usually contains very detailed, technical information, targeted at the maintainers of a project.
In contrast, the releaselog should be targetet at the users of a project and should describe changes relevant to those users at a higher abstraction.
Thats why this tool does not attempt to build a releaselog from normal commit messages but instead requires special keywords to mark notes that should show up in the releaselog.
These keywords can be used in commit messages.
As an example, check out the changelog for this repo which is automatically generated using this tool. Furthermore, the git release messages are also generated with this tool, see this release for example.
gem install git-releaselog
If you are having problems with installing the
rugged dependency, maybe you need to install
brew install cmake
Check out the Install Instructions of the
The default use is to generate the releaselog starting from the last release (the most recent tag) until now.
git-releaselog: will look up the most recent tag and will search all commits from this tag to
If you want to controll the range of commits that should be searched, you can specify a commit-hash or tag-name, e.g.
git-releaselog v1.0will look up the commits starting from the tag with name
git-releaselog v1.0 7c064bbwill look up the commits starting from the tag with name
v1.0to the commit
Alternatively, you can choose the generate the whole releaselog for the whole repo:
git-releaselog --completewill search the whole git log and group the changes nicely in sections by existing tags.
To control the markup of the output, you can use the
--format option (the default is slack):
--format slackproduces output that looks nice when copy/pasted into slack
--format mdproduces markdown output in reverse order, e.g this repo's releaselog
Entries that should show up in the releaselog must have a special format:
* <keyword>: [<optional-scope] <description>
The descriptions are extracted from the git history and grouped by keyword. Currently, the following keynotes are supported
The releaselog can be limited to a certain scope. This is helpful when multiple projects / targets are in the same git repository (E.g. several targets of an app with a large shared codebase).
When a scope is declared for the generation of the releaselog, only entries that are marked with that scope and entries without scope are included into the releaselog.
Given these lines in a commit message:
* feat: [project-x] add a new feature to project-x * fix: [project-y] fix a bug in project-y * fix: fix a bug that affected both projects
git-releaselog --scope project-x
will generate this releaselog:
*Features* * add a new feature to project-x *Fixes* * fix a bug that affected both projects
This is just what works best for us:
- Use guidelines for git commits, e.g. AngularJS
- Use the Gitflow workflow
- Create Merge Requests for merging feature branches back to develop
- Feature branch / merge request should address specific features / fixes / ...
- The description of the merge request should contain markup for the releaselog
- The description of the merge request should be the commit message of the merge commit (done automatically e.g. by gitlab, manually for github!)
The only additional step from our normal workflow is to use special markup for the change log in the description of a merge request. Doing so enables the generation of change logs between arbitrary commits / releases
The following is an excerpt of the this repos git log:
commit fa40cdb51c674df8b4a564e283a601d50fcdd55f Author: MeXx <firstname.lastname@example.org> Date: Tue May 26 14:04:09 2015 +0200 fix(repo): back to the local repo commit 1f4abe3399891cfd429e5aa474e6c414f7e2b3b2 Author: MeXx <email@example.com> Date: Tue May 26 14:02:47 2015 +0200 feat(releaselog): new feature to create a complete releaselog * feat: use the `--complete` parameter to generate a complete releaselog over all tags commit 61fe21959bb52ce09eaf1ee995650c8c4c3b073e Author: MeXx <firstname.lastname@example.org> Date: Tue May 26 13:18:10 2015 +0200 refactor(searchChanges): moved the function to search the git log into a function commit d41dac909757b265d226589ead6a5a57aba5dc87 Author: MeXx <email@example.com> Date: Tue May 26 12:49:00 2015 +0200 feat(printing): nicer printing of the log
Notice, that commit
1f4abe3399891cfd429e5aa474e6c414f7e2b3b2 has an extra line with a
The releaselog for these commits looks like this:
git-releaselog d41dac9 fa40cdb --format md
## Unreleased (_26.05.2015_) #### Feature * use the `--complete` parameter to generate a complete changelog over all tags