skooh v0.3.2

skooh

skooh is a git hooks management tool. It has no dependencies and aims to have the simplest developer experience possible.

npm install -D skooh
npm set-script prepare skooh

// package.json
{
  "hooks": {
    "pre-commit": "npm run test"
  }
}

All valid git hooks are supported.

How-To Guides

How to run tests in a pre-commit hook

After installing (npm i -D skooh) and setting up the prepare script (npm set-script prepare skooh), then, assuming you have already setup a npm run test script, then add the following as a top-level key to your package.json file:

// package.json
{
  "hooks": {
    "pre-commit": "npm run test"
  }
}

Then run npx skooh, which updates your .git/hooks/pre-commit file.

Now, in the future, when you checkout this branch or clone this repo, skooh's builtin post-checkout hook will run which will looks for hooks and write them to .git/hooks/.

How to edit your hooks block

Run npx skooh after manually editing the package.json hooks block. (This is normally ran automatically via the prepare life-cycle hook, but, manual edits cannot be detected.)

Reference

skooh

skooh sets up your git hooks. Call it by runnings npx skooh on the CLI.

Explanation

The goal of skooh is to version control your git hooks so you have a consistent way of triggering them across teams and development environments. .git/hooks/ is not version controlled itself, but it is a straightforward, user-friendly, and git-approved way of managing git hooks. This means we should use it for managing hooks. Skooh reads your package.json in order to prepare your git hooks.

How the "prepare: skooh" script works

prepare is a npm life-cycle script that runs automatically on npm install (and at a few other times as well). prepare calls skooh, which works as follows:

1. It removes previously defined git hooks in preparation for updates.
2. It scans your package.json for a top-level "hooks" block.

3. It writes all valid hooks to .git/hooks/. For example, a "pre-commit": "npm run test" hook would result in the file .git/hooks/pre-commit with the following contents:

   #!bin/sh
   
   npm run test

4. It writes a post-checkout hook to manage automatic updates (or appends to the one you define). This ensures that differently defined hooks from branches, changesets, etc., are automatically applied.

Migrating from Husky

Husky changes the hook path in git via the core.hookspath setting. You can see your current settings by running git config -l. You will need to unset this config by running git config --unset core.hookspath in order reset the git hooks path back to the default .git/hooks/.

Skooh vs Husky

1. To begin with, husky is reliable. It has been battle-tested throughout the years. It's a safe bet with good documentation, and the author seems friendly. So, use husky, (unless you are persuaded by what follows).

2. husky edits your core.hookspath

   1. This forces you to use husky for all your git hooks, because git isn't looking in the default location anymore (.git/hooks).
   2. If you move on from husky and forget to unset the core.hookspath overwrite, you will get unfamiliar errors and have an unpleasant debugging experience (you don't often get "missing git hook" errors, and so it will feel foreign to you).

3. Husky also makes you write a top-level .husky/ folder that contains all your hooks.

   1. This is overkill for many use-cases, such as when you want to "just" run your linter on pre-commit. Do you really want yet another top-level folder which contains "just" a single file with a single line of code in it? I don't. I'd rather have that one-liner in my package.json.

4. Husky has a CLI.

   1. It is simple, but that's because it's almost unnecessary.
   2. You will use it so rarely that you will forget the keywords and help commands.
   3. It's purpose is to help you add simple one-liner code to your .husky files. If you didn't have .husky files, you wouldn't need the CLI.

In conclusions, it is my opinion that skooh is simpler to use than husky. No top-level directory, no shell script management, no git config overrides, and no CLI needed.

What does a good git hook look like

I'd argue that the "ideal git hook" is a combination of other package.json scripts. Personally, the goal I aim for in most of my projects is something like the following:

// package.json
{
  "scripts": {
    "format": "...",
    "lint": "...",
    "test": "..."
  },
  "hooks": {
    "pre-commit": "npm run format && npm run lint && npm run test"
  }
}