Git hooks from one config. No hook folder in your repo.
@hexlabelposition/ward runs your git hooks from a single config file. Version 0.1 replaces husky; running tasks on staged files (the lint-staged part) comes in 0.2.
- One config for all hooks -
ward.config.ts(typed, with autocomplete),ward.yml, or a"ward"section inpackage.json - No
.husky/-style folder - hooks are generated locally into.git/hooks, only the config is committed - Dynamic - edit the config and the change applies on the next commit, no reinstall
- Careful with existing hooks - a hook that is already there (git-lfs, a hand-written script) is never overwritten silently
- Clear config errors - every problem is listed with its place in the config and a suggestion for typos
⚠️ Status: early versions.0.xreleases may change the config and behavior. See What's next for planned features.
Requires Node ≥ 24 and Git ≥ 2.20.
npm install -D @hexlabelposition/ward
npm pkg set scripts.prepare=ward
npm run prepareThe prepare script runs on every npm install, so hooks are set up for everyone on the team automatically:
{
"scripts": {
"prepare": "ward"
}
}Then add a config. The shortest one lives in package.json:
{
"scripts": {
"prepare": "ward"
},
"ward": {
"hooks": {
"pre-commit": "npm run lint",
"commit-msg": "commitlint --edit {1}",
"pre-push": ["npm run typecheck", "npm test"]
}
}
}That's all: git commit now runs npm run lint and stops the commit if it fails.
Ward looks for the config in the repo root, in this order:
ward.config.tsward.yml/ward.yaml"ward"section inpackage.json
If more than one is found, Ward stops with an error instead of silently picking one. Without a config every hook does nothing.
// ward.config.ts
import { defineConfig } from "@hexlabelposition/ward";
export default defineConfig({
hooks: {
"pre-commit": ["npm run lint", "npm run format:check"],
"commit-msg": "commitlint --edit {1}",
"pre-push": {
tasks: {
typecheck: { run: "npm run typecheck" },
test: { run: "npm test" },
},
},
},
});defineConfig gives types and autocomplete for hook names and options. The file is loaded by Node's built-in type stripping, with no extra loader, so keep it to erasable syntax: no enum, namespace or constructor parameter properties.
# ward.yml
hooks:
pre-commit:
- npm run lint
- npm run format:check
commit-msg: commitlint --edit {1}
pre-push:
tasks:
typecheck:
run: npm run typecheck
test:
run: npm test| Form | Meaning |
|---|---|
"cmd" |
Run one command |
["a", "b"] |
Run commands in order, stop on first failure |
{ tasks: { name: { run: "cmd" } } } |
Named tasks, run in the order they are listed |
Any git hook can be used as a key: pre-commit, commit-msg, pre-push, post-checkout, post-merge and so on.
-
Commands run through the system shell from the repo root, so
&&, pipes andnpm run …work as in a terminal. -
Tasks run one after another. The first one that fails stops the hook, and git gets its exit code:
$ git commit -m "feat: add login" … output of npm run lint … ward: pre-commit failed: npm run lint (exit 1) -
Output is not captured: you see what the command prints, as it prints it.
-
Hooks that get data from git on stdin (
pre-push) pass it on to the command.
{1}, {2}, … are replaced with the arguments git passed to the hook. For commit-msg, {1} is the file with the commit message:
hooks:
commit-msg: commitlint --edit {1}
prepare-commit-msg: node scripts/prefill-message.js {1} {2}Values are quoted for the shell when needed, so write {1}, not "{1}". An argument git did not pass expands to nothing.
The whole config is checked on every run, and every problem is reported at once:
$ git commit -m "fix: typo"
ward: ward.yml is invalid:
hooks.pre-comit: unknown hook. Did you mean "pre-commit"?
hooks.pre-push[1]: command is empty
An invalid config fails every hook, not only the broken one: a typo in a hook name would otherwise never be noticed.
| Command | What it does |
|---|---|
ward |
Install hook stubs into .git/hooks (what prepare runs) |
ward run <hook> |
Run a hook manually - useful for testing without committing |
ward uninstall |
Remove Ward's hook stubs, put chained hooks back |
ward flags:
| Flag | Meaning |
|---|---|
--chain |
Keep existing hooks and run Ward after them |
--force |
Replace existing hooks; the old ones are lost |
--respect-hooks-path |
Install into the core.hooksPath directory instead of failing |
ward does nothing in CI (when CI is set), outside a git repository and when git is not installed, so npm install in Docker or CI does not fail.
If a hook file that Ward did not write is already in .git/hooks, Ward leaves it alone:
- In a terminal,
npx wardlists such hooks and asks whether to keep them. - From
prepare, it prints a warning with the command to run and does not fail the install. npx ward --chainkeeps them without asking: the old hook is renamed to<hook>.pre-wardand runs before Ward with the same arguments. If it fails, git stops and Ward does not run.npx ward --forcereplaces them.
ward uninstall removes only Ward's own stubs and moves each <hook>.pre-ward back to its place.
When core.hooksPath is set, git ignores .git/hooks, so Ward's hooks would never run. Ward stops with a message that names the value, where it is set and the command that removes it. To install into that directory instead, run ward --respect-hooks-path.
git commit --no-verify # git's built-in skip: no hooks at all
WARD=0 git commit # disable Ward for one commandWARD=0 skips only Ward: a hook that was there before Ward and is chained from the stub still runs.
Hooks are skipped automatically while a merge or rebase is in progress: the commits git makes there are not your working changes.
If dependencies are not installed yet (node_modules/.bin/ward is missing), the hook prints a warning and lets git continue.
-
Remove husky and install Ward:
npm uninstall husky npm install -D @hexlabelposition/ward npm pkg set scripts.prepare=ward -
Move the commands from
.husky/*into the config. A.husky/pre-commitwithnpm testand a.husky/commit-msgwithnpx commitlint --edit $1become:# ward.yml hooks: pre-commit: npm test commit-msg: npx commitlint --edit {1}
-
Delete the
.husky/folder and unset the hooks path husky configured, then install the hooks:git config --unset core.hooksPath npm run prepare
Each teammate needs the
git config --unsetonce in their clone; Ward prints this command when it finds the setting.
ward writes a small stub for every git hook into .git/hooks. Each stub only calls ward run <hook>. The config is read at run time, so changes apply on the next git command. A hook with no tasks exits right away, before anything else is loaded.
.git/hooks is not committed, so each clone generates its own stubs through prepare. The hooks directory is resolved by git itself, so worktrees and submodules work.
See ARCHITECTURE.md for details.
Planned, not available yet (see BACKLOG.md):
- 0.2 - replace lint-staged: tasks on staged files with
globand{staged_files}, safe partial staging with backup, parallel tasks - 0.3: Bun and Deno
- Later:
ward init, CI mode, presets and shared configs, monorepo support, migration from husky + lint-staged and lefthook
Options from these versions (glob, parallel, …) are rejected today with "not supported yet" instead of being silently ignored.