Join the chat at https://gitter.im/thoughtram/clog
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.
- Clone the
clog-librepository (we will clone to our home directory to make things simple, feel free to change it)
$ git clone https://github.com/thoughtram/clog ~/clog- Add
clogas a dependency in yourCargo.toml
[dependencies] clog = "*"
- 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 e.exit(); }); // Set some options clog.repository("https://github.com/thoughtram/clog") .subtitle("Crazy Dog") .changelog("changelog.md") .from("6d8183f") .version("0.1.0"); // 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| { e.exit(); }); }
- Compile and run `$ cargo build --release && ./target/release/bin_name
- View the output in your favorite markdown viewer!
$ vim changelog.md
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.
[clog] # 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
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 suppported, such as "My Special Section" = ["ms", "mysec"]
- 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.