git-ratchet is a tool for building ratcheted builds. Ratcheted builds are builds that go red when a given measure increases.
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.
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:
_measure_,_value_
...
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
^Dto signify the end of input. See this StackOverflow answer for a longer explanationAnother 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
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.
Run git ratchet dump to dump a data file containing the data. This file current is currently in CSV, and looks like this:
Time,Measure,Value,Baseline
_timestamp_,_measure_,_value_,_baseline_
...
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.
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
masterunless you passed in a suffix (with the-pflag)
git --no-pager log --notes=git-ratchet-1-master HEAD
commit c3d1bfe82a85d99f3e7ab8b00d435c4786f2eb5e
Author: Your Name <yourname@email.com>
Date: Fri Jul 31 17:37:52 2015 -0500
Add ratchet script.
Notes (git-ratchet-1-master):
errors,0,0
warnings,0,0
commit 6d4044923fbf3c35664797f56f4f54534decc872
Author: Your Name <yourname@email.com>
Date: Wed Jul 29 15:33:27 2015 -0500
Initial commit