Mixmax's git hooks

This repository contains the git hooks for Mixmax's development workflow. We use commitlint to reduce friction when using semantic-release, and desire to tighten the feedback cycle to further reduce friction.

Install

Note that if you're in a mixmaxhq GitHub repository that uses semantic-release, these packages should already be installed. You might need to git pull and npm ci, and if you're still not seeing hooks in .git/hooks, double-check that you're running a version npm >= 6.13.4.

$ npm i -D @mixmaxhq/git-hooks @commitlint/cli

Configure

The git hooks are opt-in using the global mixmax configuration file ~/.config/mixmax/config:

[git.hooks]
commit_msg = true # default: false
pre_push = true # default: false
# Valid values: "all", "unpushed"
pre_push_mode = "all" # required if pre_push is enabled

(The syntax here is TOML.)

commit_msg

This flag determines whether commitlint will run on commit messages before the commit is created.

pre_push

This flag determines whether commitlint will run on the commit messages being pushed to the remote repository. It has two modes (pre_push_mode): all and unpushed. The all option lists the commits on the current branch since it diverged from the default branch and lints all of them. The unpushed option lists the commits on the current branch that aren't on the remote's copy of the branch and lints all of them.

How to use

Copy this to a .huskyrc.js file adjacent to the .git and node_modules directories of a project:

module.exports = require('@mixmaxhq/git-hooks');

// Husky explicitly greps for the hook itself to determine whether to run the hook. Here are the
// hooks, to bypass this check:
//
// - pre-push
// - commit-msg

Troubleshooting

You should get these hooks automatically in shared repositories that have @mixmaxhq/git-hooks configured. If you don't see evidence that this is working (e.g. husky > commit-msg (node v10.19.0)) when you run git commit - regardless of whether the message is valid), run through these troubleshooting steps!

Check husky

We use husky to manage the git hooks. If husky isn't getting installed or configured, the hooks won't work. Take a look at .git/hooks - you should see a husky.sh file alongside other files like pre-commit and commit-msg.

Expected	Misconfigured

If you see the former, try running npm ci again. If that doesn't work, make sure you're running a version of npm newer than 6.13.4 - if you're not, upgrade (it has a security fix anyway) - and try again. If that still doesn't work, try npm rebuild husky. Still no dice? Reach out to #core-team.

Check for .huskyrc.js

This should be installed for all repositories that use @mixmaxhq/git-hooks and semantic-release - if it's missing, try adding it in from another repository that has it configured, or reach out to #core-team.

Verbose logging

You can try enabling verbose logging for Husky to get additional information.

Building

npm run build

Outputs a commonjs-compatible bundle to dist/index.js.

Running tests

npm test

Publishing

Merging to master will automatically publish the package if commits with non-trivial changes have been introduced (per commit conventions).