Generate beautiful changelogs from your Git commit history
Generate beautiful changelogs from your Git commit history
A conventional changelog for the rest of us
clog creates a changelog automatically from your local git metadata. See the clogs changelog.md for an example.
The way this works, is every time you make a commit, you ensure your commit subject line follows the conventional format. Then when you wish to update your changelog, you simply run clog inside your local repository with any options you'd like to specify.
NOTE: clog also supports empty components by making commit messages such as alias: message or alias(): message (i.e. without the component)
There are two ways to use clog, as a binary via the command line or as a library in your applications via clog-lib.
In order to use clog via the command line you must first obtain a binary by either compiling it yourself, or downloading and installing one of the precompiled binaries.
cargo installIf you want to both compile and install clog using cargo you can simply run
cargo install clog-cliFollow these instructions to compile clog, then skip down to Installation.
cargo and Rust installed$ git clone https://github.com/clog-tool/clog-cli && cd clog-cli$ cargo build --releasetarget/release/clogCurrently there are no precompiled binaries available.
Note: The Mac distribution is available on npm via clog-cli.
Once you have downloaded, or compiled, clog you simply need to place the binary somewhere in your $PATH. If you are not familiar with $PATH read-on; otherwise skip down to Using clog.
You can use clog-bin from the AUR, or follow the instructions for Linux / OS X
You have two options, place clog into a directory that is already located in your $PATH variable (To see which directories those are, open a terminal and type echo "${PATH//:/\n}", the quotation marks are important), or you can add a custom directory to your $PATH
Option 1
If you have write permission to a directory listed in your $PATH or you have root permission (or via sudo), simply copy the clog to that directory # sudo cp clog /usr/local/bin
Option 2
If you do not have root, sudo, or write permission to any directory already in $PATH you can create a directory inside your home directory, and add that. Many people use $HOME/.bin to keep it hidden (and not clutter your home directory), or $HOME/bin if you want it to be always visible. Here is an example to make the directory, add it to $PATH, and copy clog there.
Simply change bin to whatever you'd like to name the directory, and .bashrc to whatever your shell startup file is (usually .bashrc, .bash_profile, or .zshrc)
$ mkdir ~/bin
$ echo "export PATH=$PATH:$HOME/bin" >> ~/.bashrc
$ cp clog ~/bin
$ source ~/.bashrcOn Windows 7/8 you can add directory to the PATH variable by opening a command line as an administrator and running
C:\> setx path "%path%;C:\path\to\clog\binary"Otherwise, ensure you have the clog binary in the directory which you operating in the command line from, because Windows automatically adds your current directory to PATH (i.e. if you open a command line to C:\my_project\ to use clog ensure clog.exe is inside that directory as well).
clog works by reading your git metadata and specially crafted commit messages and subjects to create a changelog. clog has the following options available.
…In order to see it in action, you'll need a repository that already has some of those specially crafted commit messages in it's history. For this, we'll use the clog repository itself.
Clone the repo git clone https://github.com/clog-tool/clog-cli && cd clog-cli
Ensure you already clog binary from any of the steps above
There are many, many ways to run clog. Note, in these examples we will be typing the same options over and over again, in times like that we could a clog TOML configuration file to specify those options that don't normally change. Also note, all these CLI options have short versions as well, we're using the long version because they're easier to understand.
Let's start by picking up only new commits since our last release (this may not be a lot...or none)
Run clog -r https://github.com/clog-tool/clog-cli --outfile only_new.md
By default, clog outputs to stdout unless you have a file set inside a TOML configuration file. (Note, we could have used the shell > operator instead of --outfile)
Anything options you set via the CLI will override anything you set the configuration file.
Let's now tell clog where it can find our old changelog, and prepend any new commits to that old data
Run clog -r https://github.com/clog-tool/clog-cli --infile changelog.md --outfile new_combined.md
Finally, let's assume like most projects we just want to use one file, and prepend all new data to our old changelog (most useful)
First make a backup of the changelog.md so you can compare it later cp changelog.md changelog.md.bak
Run clog -r https://github.com/clog-tool/clog-cli --changelog changelog.md
Try viewing any of the only_new.md, new_combined.md, changelog.md.bak, or changelog.md in your favorite markdown viewer to compare them.
See the documentation or clog-lib for information on using clog in your applications. You can also see the clog crates.io page.
clog can also be configured using a default configuration file so that you don't have to specify all the options each time you want to update your changelog. To do this add a .clog.toml file to your repository.
…Now you can update your MyChangelog.md with clog --patch (assuming you want to update from the latest tag version, and increment your patch version by 1).
Note: Any options you specify at the command line will override options set in your .clog.toml
By default, clog will display three sections in your changelog, Features, Performance, and Bug Fixes. You can add additional sections by using a .clog.toml file. To add more sections, simply add a [sections] table, along with the section name and aliases you'd like to use in your commit messages:
[sections]
MySection = ["mysec", "ms"]Now if you make a commit message such as mysec(Component): some message or ms(Component): some message there will be a new "MySection" section along side the "Features" and "Bug Fixes" areas.
NOTE: Sections with spaces are supported, such as "My Special Section" = ["ms", "mysec"]
clog is licensed under the MIT Open Source license. For more information, see the LICENSE file in this repository.
No open issues yet, or sync has not completed.