Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



91 Commits

Repository files navigation


git-ratchet is a tool for building ratcheted builds. Ratcheted builds are builds that go red when a given measure increases.

Build Status

What's it for?

Ratcheted builds are for teams that would like to pay off technical debt or tackle larger architectural changes to a code base over a medium-to-long term time period. Let's dive into a few examples.

Perhaps you are working on a large legacy Javascript codebase, which you would like to run jshint on. The number of warnings raised by jshint is large enough that you can't tackle them in a single day, but you'd like to avoid increasing the number of warnings when writing new features. You could set up a ratcheted build measuring the number of jshint warnings, and tackle them with small improvements over time.

Or perhaps you are attempting to perform a library upgrade, but there are a large number of usages of a deprecated method call that need to be refactored. The refactoring isn't straight-forward and can't be easily automated. You could set up a ratcheted build measuring the number of usages of the deprecated method, and tackle them with small improvements over time.

How do I get started?

Download the latest official release for your platform.

Rename the binary to git-ratchet, put it on your $PATH, and make it executable.

Run git ratchet check -w on a CI server, on your master branch.

Feed in input that looks like this:


It then checks the measurements against previous values stored in your git repository, and returns a non-zero exit code if the measures have increased. Otherwise, it stores the measures againt the current commit hash and exits.

Note: If you're feeding measures via stdin in a terminal window (likely while testing), you'll need to send ^D to signify the end of input. See this StackOverflow answer for a longer explanation

Another option would be to put measures into a file and feed that to git-ratchet.

touch measures.csv
echo "test,100" > measures.csv
git ratchet check -v -w < measures.csv

How do I check my changes locally?

Run git ratchet check locally, feeding in the calculated input. This checks the measures against previous values but does not write the new values if they are okay.

How do I see the trend over time?

Run git ratchet dump to dump a data file containing the data. This file current is currently in CSV, and looks like this:


It's 2am and I need to release a hotfix to PROD. How do I ignore the increase?

Run git ratchet excuse -n "_measure_" -e "It's 2am and the servers are on fire." locally to write an excuse. This will allow the build to pass.

Where is the data stored?

The data is stored inside git-notes. This means this data follows around your repository, and can keep track of history, without having to pollute your working directory or commit graph.

Note: When doing a fresh clone (which is typical when using this in a CI environment), you'll need to make sure you pull down the git notes as well. A default clone will not do this.

> git fetch origin refs/notes/*:refs/notes/*

For example:

Running the following will return a list of commits starting at HEAD which include any git-ratchet-1-$SUFFIX_NAME notes that have been added by git-ratchet.

Note: $SUFFIX_NAME is likely master unless you passed in a suffix (with the -p flag)

 git --no-pager log --notes=git-ratchet-1-master HEAD

 commit c3d1bfe82a85d99f3e7ab8b00d435c4786f2eb5e
 Author: Your Name <>
 Date:   Fri Jul 31 17:37:52 2015 -0500

    Add ratchet script.

 Notes (git-ratchet-1-master):

 commit 6d4044923fbf3c35664797f56f4f54534decc872
 Author: Your Name <>
 Date:   Wed Jul 29 15:33:27 2015 -0500

    Initial commit