npm package: @mixmaxhq/git-hooks
Description: Shared git-hooks at Mixmax, for use with Husky.
Author: Mixmax
Latest version: 1.3.0

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

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

## Configure

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

```toml
[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](https://github.com/toml-lang/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:

```js
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                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| ![expected](https://user-images.githubusercontent.com/1348991/75392527-15fb6f80-58a1-11ea-8c51-85ae5ae0dc3d.png) | ![misconfigured](https://user-images.githubusercontent.com/1348991/75392560-257ab880-58a1-11ea-8666-179d8f2a5c93.png) |

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](https://mixmax.slack.com/archives/CFX7QK7PW).

### 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](https://mixmax.slack.com/archives/CFX7QK7PW).

### Verbose logging

You can try enabling [verbose logging](https://github.com/typicode/husky#debug-messages) 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](https://www.conventionalcommits.org)).