9 unstable releases (4 breaking)

Uses old Rust 2015

0.9.1 Apr 4, 2016
0.9.0 Oct 25, 2015
0.8.2 Aug 8, 2015
0.8.1 Jul 2, 2015
0.3.0 Mar 31, 2015

#10 in #changelog

Download history 28/week @ 2021-08-09 21/week @ 2021-08-16 20/week @ 2021-08-23 7/week @ 2021-08-30 32/week @ 2021-09-06 12/week @ 2021-09-13 22/week @ 2021-09-20 28/week @ 2021-09-27 21/week @ 2021-10-04 21/week @ 2021-10-11 17/week @ 2021-10-18 17/week @ 2021-10-25 24/week @ 2021-11-01 51/week @ 2021-11-08 36/week @ 2021-11-15 72/week @ 2021-11-22

196 downloads per month
Used in 4 crates (2 directly)

MIT license

1.5K SLoC


Join the chat at https://gitter.im/thoughtram/clog

Build Status

A library for generating a conventional changelog from git metadata, written in Rust


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.

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 (See clog-cli for details) or as a library in your applicaitons.

See the documentation for information on using clog in your applications.

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.

  1. Clone the clog-lib repository (we will clone to our home directory to make things simple, feel free to change it)
$ git clone https://github.com/thoughtram/clog ~/clog
  1. Add clog as a dependency in your Cargo.toml
clog = "*"
  1. Use the following in your src/main.rs
extern crate clog;

use clog::Clog;

fn main() {
    // Create the struct
    let mut clog = Clog::with_dir("~/clog").unwrap_or_else(|e| {
        // Prints the error message and exits

    // Set some options
        .subtitle("Crazy Dog")

    // Write the changelog to the current working directory
    // Alternatively we could have used .write_changelog_to("/somedir/some_file.md")
    clog.write_changelog().unwrap_or_else(|e| {
  1. Compile and run `$ cargo build --release && ./target/release/bin_name
  2. View the output in your favorite markdown viewer! $ vim changelog.md

Default Options

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.

# A repository link with the trailing '.git' which will be used to generate
# all commit and issue links
repository = "https://github.com/thoughtram/clog"
# A constant release title
subtitle = "my awesome title"

# specify the style of commit links to generate, defaults to "github" if omitted
link-style = "github"

# The preferred way to set a constant changelog. This file will be read for old changelog
# data, then prepended to for new changelog data. It's the equivilant to setting
# both infile and outfile to the same file.
# Do not use with outfile or infile fields!
# Defaults to stdout when omitted
changelog = "mychangelog.md"

# This sets an output file only! If it exists already, new changelog data will be
# prepended, if not it will be created.
# This is useful in conjunction with the infile field if you have a separate file
# that you would like to append after newly created clog data
# Defaults to stdout when omitted
outfile = "MyChangelog.md"

# This sets the input file old! Any data inside this file will be appended to any
# new data that clog picks up
# This is useful in conjunction with the outfile field where you may wish to read
# from one file and append that data to the clog output in another
infile = "My_old_changelog.md"

# This sets the output format. There are two options "json" or "markdown" and
# defaults to "markdown" when omitted
output-format = "json"

# If you use tags, you can set the following if you wish to only pick
# up changes since your latest tag
from-latest-tag = true

Custom Sections

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:

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 suppported, such as "My Special Section" = ["ms", "mysec"]

Companion Projects

  • Commitizen - A command line tool that helps you writing better commit messages.


clog is licensed under the MIT Open Source license. For more information, see the LICENSE file in this repository.


~84K SLoC