Repository files navigation

Aconventional changelog for the rest of us

clog creates a changelog automatically from your local git metadata. See theclogschangelog.md for an example.

The way this works, is every time you make a commit, you ensure your commit subject line follows theconventional format. Then when you wish to update your changelog, you simply runclog inside your local repository with any options you'd like to specify.

NOTE:clog also supports empty components by making commit messages such asalias: message oralias(): message (i.e. without the component)

There are two ways to useclog, as a binary via the command line or as a library in your applications viaclog-lib.

In order to useclog via the command line you must first obtain a binary by either compiling it yourself, or downloading and installing one of the precompiled binaries.

If you want to both compile and installclog usingcargo you can simply run

cargo install clog-cli

Follow these instructions to compileclog, then skip down to Installation.

1. Ensure you have current version ofcargo andRust installed
2. Clone the project$ git clone https://github.com/clog-tool/clog-cli && cd clog-cli
3. Build the project$ cargo build --release
4. Once complete, the binary will be located attarget/release/clog

Currently there are no precompiled binaries available.

Note: The Mac distribution is available on npm viaclog-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 useclog-bin from the AUR, or follow the instructions for Linux / OS X

You have two options, placeclog into a directory that is already located in your$PATH variable (To see which directories those are, open a terminal and typeecho "${PATH//:/\n}", the quotation marks are important), or you can add a custom directory to your$PATH

Option 1If you have write permission to a directory listed in your$PATH or you have root permission (or viasudo), simply copy theclog to that directory# sudo cp clog /usr/local/bin

Option 2If 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 copyclog there.

Simply changebin 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~/.bashrc

On Windows 7/8 you can add directory to thePATH variable by opening a command line as an administrator and running

C:\> setx path"%path%;C:\path\to\clog\binary"

Otherwise, ensure you have theclog 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 toC:\my_project\ to useclog ensureclog.exe is inside that directory as well).

clog works by reading yourgit metadata and specially crafted commit messages and subjects to create a changelog.clog has the following options available.

Usage: clog [OPTIONS]Options:  -r, --repository<URL>  Repository usedfor generating commit and issue links (without the .git, e.g.                          https://github.com/thoughtram/clog)  -f, --from<COMMIT>     e.g. 12a8546  -T, --format<STR>      The output format, defaults to markdown [default: markdown] [possible values: markdown,                          json]  -M, --major             Increment major version by one (Sets minor and patch to 0)  -g, --git-dir<PATH>    Local .git directory (defaults to"$(pwd)/.git")  -w, --work-tree<PATH>  Local working tree of the git project (defaults to"$(pwd)")  -m, --minor             Increment minor version by one (Sets patch to 0)  -p, --patch             Increment patch version by one  -s, --subtitle<STR>      -t, --to<COMMIT>       e.g. 8057684 [default: HEAD]  -o, --outfile<PATH>    Where to write the changelog (Defaults to stdout when omitted)  -c, --config<COMMIT>   The Clog Configuration TOML file to use [default: .clog.toml]  -i, --infile<PATH>     A changelog to append to, but*NOT* write to (Usefulin conjunction with --outfile)      --setversion<VER>  e.g. 1.0.1  -F, --from-latest-tag   use latest tag as start (instead of --from)  -l, --link-style<STR>  The style of repository link to generate [default: github] [possible values: github,                          gitlab, stash, cgit]  -C, --changelog<PATH>  A previous changelog to prepend new changes to (this is like using the same filefor both                          --infile and --outfile and should not be usedin conjunction with either)  -h, --help              Printhelp  -V, --version           Print versionIf your .git directory is a child of your project directory (most common, such as /myproject/.git) AND notin thecurrent working directory (i.e you need to use --work-tree or --git-dir) you only need to specify either the--work-tree (i.e. /myproject) OR --git-dir (i.e. /myproject/.git), you don't need to use both.If using the --config to specify a clog configuration TOML file NOT in the current working directory (meaning youneed to use --work-tree or --git-dir) AND the TOML file is inside your project directory (i.e./myproject/.clog.toml) you do not need to use --work-tree or --git-dir.

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 theclog repository itself.

1. Clone the repogit clone https://github.com/clog-tool/clog-cli && cd clog-cli

2. Ensure you alreadyclog binary from any of the steps above

3. There are many, many ways to runclog. Note, in these examples we will be typing the same options over and over again, in times like that we could aclog 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.

4. Let's start by picking up only new commits since our last release (this may not be a lot...or none)

5. Runclog -r https://github.com/clog-tool/clog-cli --outfile only_new.md

6. By default,clog outputs tostdout unless you have a file set inside a TOML configuration file. (Note, we could have used the shell> operator instead of--outfile)

7. Anything options you set via the CLI will override anything you set the configuration file.

8. Let's now tellclog where it can find our old changelog, and prepend any new commits to that old data

9. Runclog -r https://github.com/clog-tool/clog-cli --infile changelog.md --outfile new_combined.md

10. 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)

11. First make a backup of thechangelog.md so you can compare it latercp changelog.md changelog.md.bak

12. Runclog -r https://github.com/clog-tool/clog-cli --changelog changelog.md

13. Try viewing any of theonly_new.md,new_combined.md,changelog.md.bak, orchangelog.md in your favorite markdown viewer to compare them.

See thedocumentation orclog-lib for information on usingclog in your applications. You can also see theclog 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.

[clog]# A repository link with the trailing '.git' which will be used to generate# all commit and issue linksrepository ="https://github.com/clog-tool/clog-cli"# A constant release titlesubtitle ="my awesome title"# specify the style of commit links to generate, defaults to "github" if omittedlink-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 equivalent to setting# both infile and outfile to the same file.## Do not use with outfile or infile fields!## Defaults to stdout when omittedchangelog ="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 omittedoutfile ="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 anotherinfile ="My_old_changelog.md"# This sets the output format. There are two options "json" or "markdown" and# defaults to "markdown" when omittedoutput-format ="json"# If you use tags, you can set the following if you wish to only pick# up changes since your latest tagfrom-latest-tag =true

Now you can update yourMyChangelog.md withclog --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, andBug 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 asmysec(Component): some message orms(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"]

• 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.