Skip to main content

Verification Through Commit Hooks

Commit hooks are a neat feature of Git (and other DVCS) that allow you to 'tap into' certain functionality at certain stages of operation. One of the most useful places for hooks to run is right before finalizing a commit.

Commit hooks are very useful for running lint scripts, static analysis and anything else that commonly causes pull requests to be rejected due to housekeeping. Swimm's verification checks can effectively run here, but this will only be effective if everyone uses the hooks the same way.

To utilize pre-commit hooks, You'll need to make sure you have the latest swimm_cli executable somewhere. The swimm_cli executable should be invoked from the root of the repository you wish to verify.

You can run this code to install it to /home/yourname/bin for instance:

wget -O swimm_cli https://releases.swimm.io/ci/latest/packed-swimm-linux-cli
chmod +x ./swimm_cli

We recommend always fetching a new copy of swimm_cli in your scripts so that your verification is the same engine as the latest Swimm release.

Sample commit hook configurations:

Below are the sample configurations, in no specific order. If you need one that isn't listed, please reach out on our

Husky

Add the following to your package.json file:

// package.json
{
"scripts": {
"pre-commit": "swimm_cli verify"
}
}

Then, run the following in your terminal while in the repository root:

// run in terminal
$ npx husky add .husky/pre-commit "npm run pre-commit"

Pre-commit

Pre-commit works with Git to intercept certain kinds of events through the use of hooks, which allows actions to run before the commit transaction actually takes place. Swimm's CI tools are just as useful if run pre-commit as they are if run through a CI server - the main difference is the check runs on your local machine before the commit actually takes place, and not as a part of the push / PR / review cycle.

The result is the same, failed documentation checks can trigger other things to happen, or even block the commit, depending on the conventions that feel right for you and your team.

To install pre-commit hooks, first install pre-commit, and then follow the instructions in this repository.

Shell example: verifying docs are up-to-date

echo "Verifying docs"
wget -O swimm_cli https://releases.swimm.io/ci/latest/packed-swimm-linux-cli
chmod +x ./swimm_cli
./swimm_cli verify

Shell example: verify overall coverage

swimm_cli coverage Will scan whatever code Git knows about and compare that to the amount of documentation you've created. The result will be a score of 0 to 100. To get that number, try the following command:

swimm_cli coverage | grep "/" | awk '{print $4}'

Expect a float (as in 0.00 or 89.73). If you need a whole number (0 - 100), run this instead:

swimm_cli coverage | grep "/" | awk '{print $4}' | cut -d. -f1