Skip to content

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

License

Notifications You must be signed in to change notification settings

semantic-rs/clog-lib

 
 

Repository files navigation

clog

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

Build Status

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

About

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)

Usage

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
[dependencies]
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
        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();
    });
}
  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.

[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

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:

[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"]

Companion Projects

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

LICENSE

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

About

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

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Rust 98.9%
  • Other 1.1%