A Git command line tool for managing your CHANGELOG from defined schema entries in your Git commit messages. If you prefer videos checkout the ~15 min video where we provide a detailed introduction below. Otherwise skip the video and get the details from the README.md.
We created git-cl primarily because of the following:
- conflicts caused by people changing a
CHANGELOG.mdfile are annoying - the audience of a CHANGELOG is different than the audience of your commit messages
- wanted Git tags to identify releases so people don't have to change their release workflow
There are a few different ways that you use git-cl. First you Record
Changelog Entries, then you Tag a Release, and then you Generate/Inspect
Changelog.
The first part of git-cl is Recording Changelog Entries. This is done
simply be adding entries directly to the git commit message in a specific
format. The idea is that when you make a change you include the Changelog
Entries associated with that change in the Git commit message.
Similar to what you are probably used to with CHANGELOG file formats, with
git-cl you include single line entries categorized within the following:
added, changed, deprecated, removed, fixed, security. The
difference is that you place these entries at the end of your Git commit
message body under a section identified via [changelog].
The following is an example of the schema. You effectively have a section
header of [changelog] and then below that you have any of the categorized
entries that follow.
[changelog]
added: some addition you made that you want in your changelog
changed: some change you made that you want in your changelog
deprecated: some deprecation notice you want in your changelog
removed: some removal you want in your changelog
fixed: some fix you want in your changelog
security: some security fix you want in your changelog
Still want to get more comfortable? Check out a snapshot of the Git log of this project example Git log.
Once you have made a series of commits including their respective Changelog
Entries in the Git commit message. You may be ready to tag a release. This is
probably extremely similar if not exactly the same as what you normally do. You
simply use Git to tag the head commit of your release in the following pattern
(vX.Y.Z or X.Y.Z). Any other tags that don't match those patterns exactly
including pre-release version patterns (e.g. v1.2.3-build-123) will not be
recognized as releases unless you use the (-p, --pre) switches in supported
commands to indicate you want to include pre-release versions as well.
Once you have some Git commits with Changelog Entries you can start to get some
useful things with git-cl. If you have a tagged release or two in addition
you can do even more useful things. The following is a list of the various
git-cl commands you can run and a short description of what they do.
git cl unreleased- get the unreleased changelog entries when prepping a releasegit cl unreleased --commits- get the unreleased commits when prepping a releasegit cl latest- get the changelog entries of the latest releasegit cl latest --commits- get the commits that are part of the latest releasegit cl full- get a full Markdown CHANGELOG based on keepachangelog, useful for automating publishing or doing a historical review of a projectgit cl released <release-id>- get changelog entries for the specified releasegit cl released <released-id> --commits- get commits included in the specified release
Curious to see what the produced Changelog looks like. Checkout our CHANGELOG.md. We regenerate and publish it to the repository after every release.
If you are on a platform other than macOS you will have to build your own version from source.
To install on macOS we provide a Homebrew tap which provides
the git-cl formula. You can use it by doing the following:
$ brew tap "drewdeponte/oss"
$ brew install drewdeponte/oss/git-cl
If you are on another platform you will have to build from source. Given
that git-cl is managed via GNU make. It can be built as follows:
$ make build
Once you have built it successfully you can install it in /usr/local/bin
using the following:
$ make install
We use GNU make to manage the developer build process with the following commands.
make build- build release version of thegit-clmake install- install the release build into/usr/local/binmake uninstall- uninstall the release build from/usr/local/binmake clean- clean the build directory
We believe that there are two distinct audiences involved. Your commit message and the context and details around them is targeted at the developers of the project. The other audience is the consumer of the product (library/app) and they don't care about all the intricate details. They just care about important things they should know about. In order to protect the value of the commit message and still support the CHANGELOG audience we decided to support the above defined schema within commit messages.
Well we used to use CHANGELOG.md files in our repositories for years and
years. However, we constantly ran into conflicts with the CHANGELOG.md file
as we had a policy of every Pull Request should update the CHANGELOG.md with
an entry in the Unreleased section. This aided us by having the CHANGELOG.md
entry tied to the associated code change. It also made life easier for people
doing the release as they didn't have to dig through all the commits and try
and cobble together a CHANGELOG release last minute.
So using the commit messages we were still able to keep the tight coupling to the
code change while avoiding all of the CHANGELOG.md conflicts.
We have used keep a changelog for a long time and haven't really seen much better so we decided to use it as the basis for the output here as well.
git-cl is free software, and may be redistributed under the terms specified
in the LICENSE file.
git-cl is maintained and funded by Drew De Ponte.