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 cmake
:
brew install cmake
Check out the Install Instructions of the rugged
gem.
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 toHEAD
.
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.0
will look up the commits starting from the tag with namev1.0
toHEAD
.git-releaselog v1.0 7c064bb
will look up the commits starting from the tag with namev1.0
to the commit7c064bb
.
Alternatively, you can choose the generate the whole releaselog for the whole repo:
git-releaselog --complete
will 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 slack
produces output that looks nice when copy/pasted into slack--format md
produces 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
fix
feat
gui
refactor
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
running
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 <mexx@devsub.net>
Date: Tue May 26 14:04:09 2015 +0200
fix(repo): back to the local repo
commit 1f4abe3399891cfd429e5aa474e6c414f7e2b3b2
Author: MeXx <mexx@devsub.net>
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 <mexx@devsub.net>
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 <mexx@devsub.net>
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 feat
keyword.
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