- One package replaces husky + lint-staged.
- The only file in the repo is the config (
ward.config.ts/ward.yml/package.jsonsection). - Config changes apply without reinstalling.
- Fast no-op when a hook has nothing to do.
- Never lose user changes (partial staging, existing hooks).
- The same config runs locally and in CI.
- Few dependencies, small package.
npm install
└─ "prepare": ward
└─ writes stubs → .git/hooks/<every-hook>
git commit
└─ .git/hooks/pre-commit (stub)
└─ ward run pre-commit "$@"
├─ merge / rebase in progress? → exit 0
├─ load config (fresh, every time)
├─ no tasks for hook? → exit 0
├─ collect files (staged / push / all / --from-ref)
├─ back up state (unless --no-backup)
├─ hide unstaged changes of partially staged files
├─ run tasks (graph order, parallel where possible, cache)
├─ git add files fixed by tasks (stageFixed)
├─ restore unstaged changes
├─ failure? → revert from backup (unless --no-revert)
├─ print report
└─ exit with task statussrc/
├─ cli/ # argument parsing, commands: (default) install, init, run, doctor, migrate, uninstall
├─ config/
│ ├─ discover.ts # find ward.config.ts → ward.{yml,yaml} → package.json; error on several
│ ├─ load.ts # pick the loader by format, imported lazily
│ ├─ load-ts.ts # native import() with Node type stripping
│ ├─ load-yml.ts # load YAML (yaml package)
│ ├─ load-pkg.ts # "ward" section of package.json
│ ├─ local.ts # merge ward.local.*
│ ├─ extends.ts # resolve extends: built-in presets, local paths, npm packages
│ ├─ schema.ts # validation + normalization to internal model
│ └─ define.ts # defineConfig() + public types
├─ git/
│ ├─ exec.ts # thin wrapper around `git` child process
│ ├─ paths.ts # git rev-parse --git-path hooks, repo root
│ ├─ files.ts # staged / push / all / from-ref file lists
│ ├─ state.ts # merge / rebase in progress detection
│ └─ backup.ts # backup, partial-staging hide/restore, revert
├─ hooks/
│ ├─ list.ts # all supported git hook names
│ ├─ stub.ts # stub template + marker
│ └─ install.ts # write/remove stubs, detect foreign hooks
├─ runner/
│ ├─ match.ts # glob / exclude → files (picomatch), symlink filter
│ ├─ command.ts # placeholder expansion, chunking long arg lists
│ ├─ exec.ts # spawn commands / call function tasks, stream output
│ ├─ graph.ts # dependsOn ordering, root / affected packages
│ ├─ cache.ts # per-task file hash cache
│ └─ run-hook.ts # orchestrates one hook run
├─ report/
│ ├─ summary.ts # timings, failure reason, fix hint
│ └─ github.ts # GitHub Actions annotations
├─ runtime/
│ └─ detect.ts # Node / Bun / Deno detection, runtime-specific bits
├─ presets/ # built-in presets, exported as @hexlabelposition/ward/presets
├─ doctor/ # hooksPath conflicts, foreign hook leftovers
├─ migrate/ # husky + lint-staged, lefthook, simple-git-hooks
└─ index.ts # public API: defineConfig, types
Ward is a JS package that runs on Node ≥ 24 (engines.node: ">=24"), Bun ≥ 1.1 and Deno ≥ 2. All three load .ts natively, so ward.config.ts needs no loader dependency. A Go binary is not planned for now.
The code targets the Node API surface that Bun and Deno implement, so one build runs everywhere. Runtime-specific behavior is isolated in runtime/ (detect via process.versions.bun / process.versions.deno):
- TS config: native
import()everywhere. Node only strips types (erasable syntax); Bun and Deno accept full TS. - Stub: generated for the runtime that ran install;
WARD_RUNTIMEoverrides it at run time. - Install on Bun:
bun installruns the rootpreparescript, same as npm.initdetectsbun.lock/bun.lockb. - Install on Deno: there is no
preparelifecycle and nonode_modules/.binby default, so the stub callsdeno run -A npm:@hexlabelposition/wardandinitadds adeno.jsontask (deno task prepare).initdetectsdeno.json/deno.lock.
.git/hooks is not committed, so each clone generates its own stubs via prepare. Repo stays clean: only the config is versioned.
The hooks directory is resolved with git rev-parse --git-path hooks - never hardcoded - so worktrees and submodules work.
ward (no arguments, run from prepare) writes a stub for every supported git hook, not just the ones in the config. The stub has no logic:
#!/bin/sh
# ward:managed v1
bin=node_modules/.bin/ward # git runs hooks from the repo root
[ "$WARD" = "0" ] && exit 0 # after a chained hook, if there is one
[ -f "$bin" ] || { echo "ward: $bin not found, skipping" >&2; exit 0; }
case "${WARD_RUNTIME:-node}" in # default = runtime that ran install
bun) exec bun "$bin" run pre-commit "$@" ;;
deno) exec deno run -A npm:@hexlabelposition/ward run pre-commit "$@" ;;
*) exec "$bin" run pre-commit "$@" ;;
esacBecause the config is read on every run, adding/removing hooks in the config needs no reinstall. When the stub format or the active-hooks cache gets out of date (new Ward version, config changed), ward run rewrites the stubs itself, so users never have to reinstall by hand.
# ward:managed v1- marker used byuninstalland for upgrade detection.- Calls the local binary directly, not
npx/bunx(much faster startup). The path is relative: git runs hooks from the root of the working tree, so nogit rev-parseis needed. - Missing binary (dependencies not installed yet) → warning and exit 0, so git is not blocked.
- Each clone writes its own stubs, so team members on different runtimes don't conflict.
Most hooks (e.g. post-checkout) will usually be empty. run must:
- Find config file (no heavy imports yet).
- Load config.
- If the hook is absent →
exit 0before loading runner, git, glob modules.
Lazy import() keeps cold start minimal.
Later optimization: .git/ward-hooks.json holds the list of active hooks; the stub checks it in shell and exits without starting Node. Invalidated by config mtime.
If MERGE_HEAD, rebase-merge/ or rebase-apply/ exists in the git dir, ward run exits 0 without running tasks. Commits created by git during a merge or rebase are not the user's working changes. The check uses the git dir of the worktree, so a merge in one worktree does not affect another. rebase-apply/ also covers git am. The config is not read, so even an invalid one does not block the merge.
| File | Loader |
|---|---|
ward.config.ts |
native import() (Node / Bun / Deno) |
ward.yml, .yaml |
yaml |
package.json |
JSON.parse, "ward" key |
Loaders return raw data; validation and normalization come after. A TS config must have a default export; syntax Node can't strip (enum, namespace, parameter properties) fails with the line and a hint. An empty ward.yml is an empty config; duplicate keys and several YAML documents are errors.
Discovery order: ward.config.ts → ward.yml / ward.yaml → package.json. If several sources exist → error, not a silent pick. Only the repo root is searched, never parent or package dirs: one config per repo. package.json counts only when it has a "ward" key. No config means no tasks: every hook is a no-op. ward run validates the whole config, not only the hook it runs, so an invalid config fails every hook: a typo like pre-comit would otherwise go unnoticed.
Merge order: extends packages (in listed order) → repo config → ward.local.*.
Function tasks and the task graph (dependsOn, root) are only available in the TS config; YAML and package.json hold plain data. The docs must say this explicitly.
defineConfig gives types and autocomplete; schema.ts validates every source at load time with clear errors (unknown hook, unknown option, bad glob). It lists every problem with its path in the config (hooks.pre-push[1]) and suggests close names; options from later versions fail as "not supported yet" instead of being ignored. A JSON Schema covers YAML and package.json.
All forms are normalized to one internal model (schema.ts; fields arrive with their features). The string and array forms become tasks named after their command:
type Hook = {
tasks: Task[]; // from string | string[] | { tasks: { name: task } }
parallel: boolean;
backup: boolean;
revert: boolean;
};
type Task = {
name: string;
run: string | ((ctx: { files: string[] }) => unknown);
glob?: string[];
exclude?: string[];
root?: string;
tags: string[];
stageFixed: boolean; // default true
symlinks: boolean; // default false
cache: boolean;
dependsOn: string[];
};extends is a list; entries are merged in order, then the repo config, then ward.local.*. Each entry is one of:
| Entry | Resolved as |
|---|---|
ward:<name> |
Built-in preset from src/presets/ |
| Config object | Used as is (TS config: import { ts } from "@hexlabelposition/ward/presets") |
./…, ../… |
Local config file, relative to the config that lists it |
| Package name | npm package resolved from the repo root via import.meta.resolve; default export (config object) or ward.yml in the package root |
Presets live in the main package, not in separate ward-preset-* packages: a preset is a few lines of config, so it adds almost nothing to package size, needs no extra install, and its version always matches Ward's. The trade-off - a preset change needs a Ward release - is fine for presets.
Shared company configs can't ship with Ward, so they come from a local path or an npm package. npm is preferred over a git URL: the version is pinned by the lockfile, runs are offline, private configs use the usual registry auth, the same resolution works on Node, Bun and Deno (npm: specifiers), and nothing is downloaded and executed behind the lockfile's back. Git-hosted configs may come later, YAML only.
| Source | How |
|---|---|
{staged_files} |
git diff --cached --name-only -z --diff-filter=ACMR |
{push_files} |
files changed by the pushed commits (pre-push stdin): git log <local> --not <remote sha> --remotes=<remote>, minus files gone from the pushed commit |
{all_files} |
git ls-files -z |
--from-ref |
git diff --name-only -z <ref>...HEAD |
Placeholders expand in one pass, so a file named {1}.ts is not expanded again. Each source is read from git once per run, when a task first uses it. {push_files} is only valid in pre-push: Ward reads the refs from stdin before the first task and gives every task a copy on its stdin.
A task's glob / exclude pick its files from the source (runner/match.ts, picomatch). A pattern without / matches the file name in any directory (*.ts), as in .gitignore; a pattern with / matches the path from the repo root (src/**/*.ts). Dotfiles match like other files. A task whose placeholders get no files is skipped, so eslint {staged_files} never runs on the whole project. A task with glob / exclude and no placeholder (tsc) runs only when a file of the hook matches: staged files in pre-commit, push files in pre-push; in other hooks it needs a placeholder (config error). Unbalanced brackets and patterns starting with ./ or / are config errors. picomatch is loaded only when the config has patterns.
Symlinks are dropped unless the task sets symlinks: true: a formatter would rewrite the file the link points to. A symlink is a file git stores with mode 120000 (staged, pushed or index mode, not lstat), so it works for files not on disk and on Windows without symlink support. Submodules (mode 160000) are never passed to tasks.
Problem: a file is partially staged; a formatter rewrites the whole file and you'd commit unstaged work or lose it.
Approach (same idea as lint-staged):
- Save a backup:
git stash create→ keep the hash (does not touch the working tree). Always on;--no-backup/backup: falseskips it for large repos. - Write a patch of unstaged changes for partially staged files:
git diff --binary. - Check out the index version of those files:
git checkout-index/git restore --worktree. - Run tasks.
git addfiles the tasks modified, except for tasks withstageFixed: false.- Re-apply the unstaged patch (
git apply --3way). - On task failure → restore from backup hash and report.
--no-revert/revert: falsekeeps task changes for inspection. Without a backup a full revert is not possible; only the unstaged patch is restored.
Edge cases to cover with tests: binary files, renames, deleted files, merge in progress, empty commit after formatting, non-ASCII paths, symlinks.
On install, if a hook file exists without the marker, Ward never overwrites it silently: users may not know the hook is there (git-lfs, an old husky setup, a hand-written script).
- Interactive (
npx wardin a terminal: stdin and stdout are a TTY): Ward lists the hooks and asks whether to keep them. Yes → rename to<hook>.pre-wardand chain it from the stub. - Non-interactive (
prepareunder most package managers, IDEs): the hook is left as is, Ward prints a warning with the command to chain it and exits 0, sonpm installdoesn't fail. --chain: chain without asking.--force: overwrite without asking; the old hook is lost. With--chain, only hooks that can't be chained (<hook>.pre-wardtaken) are overwritten.
A chained hook runs first with the same arguments; if it fails, git stops and Ward does not run. Hooks that read stdin (pre-push, post-rewrite) get a copy of it, and so does Ward. An existing <hook>.pre-ward is never overwritten. Directories in place of a hook are left as is.
If core.hooksPath is set, git ignores .git/hooks → print a clear warning and exit non-zero (unless --respect-hooks-path, which installs there instead). The warning names the value and its config scope and gives the fix: the matching git config [--global|--system|--worktree] --unset core.hooksPath, or --respect-hooks-path. --respect-hooks-path only installs into a directory inside the working tree or the git dir: a directory outside (~/.githooks) is shared with other repos, and the working tree root would get a file per hook. ward doctor reports the same, plus leftovers from husky, lefthook and simple-git-hooks.
ward uninstall removes only files with the marker (a symlink is never one) and moves each <hook>.pre-ward back to <hook>, unless <hook> is taken by a foreign hook - then both are left and Ward warns. It cleans the dir git runs hooks from and .git/hooks, since stubs stay there when core.hooksPath is set after install. Unlike install it is not a no-op in CI or outside a repo: it was asked for, so it fails instead of skipping silently.
- Commands run through the system shell, cwd = repo root or the task's
root. - Function tasks are called in-process with the matched file list.
- Placeholder expansion with chunking to stay under OS limits: 8000 characters on Windows (
cmd.exetakes 8191), 100 000 bytes elsewhere (Linux caps one argument, thesh -ccommand, at 128 KiB). A longer command runs several times in a row, each with the next files of its longest list, and stops at the first failure. - File paths are passed relative to the working directory, properly quoted.
- With
parallel: true, tasks run concurrently, respectingdependsOn. - Output is streamed; in parallel mode, prefixed with task name.
- Tasks can be skipped by tag:
WARD_SKIP_TAGS=slowor--skip-tag slow.
rootsets the task's working directory. Whenrootis a glob (packages/*), the task runs once per matching package that has changed files - the "affected packages".dependsOnorders tasks; a task is skipped when one of its dependencies fails.- A task with no matching files is skipped, so e.g.
tsconly runs when.tsfiles changed.
With cache: true, Ward stores content hashes of files that passed a task in .git/ward/cache.json, keyed by task name and command. On the next run, files with an unchanged hash are dropped from the task's file list; if none are left, the task is skipped. Changing the task invalidates its entries.
ward run <hook> --ci uses the same config:
- Files come from
--from-ref <ref>(diff against the base branch) or--all-files. - No autofix: tasks run, Ward prints
git diffof what they changed, restores the tree and fails if anything changed. - When
GITHUB_ACTIONS=true, failures are also printed as::error file=…,line=…::annotations.
ward (install) stays a no-op when CI is set (not 0 / false), outside a git working tree, or when git is not installed, so npm install in Docker/CI doesn't fail.
After each run Ward prints: status and duration per task, the reason a task failed (exit code, first error lines), and a hint on how to fix it (e.g. the command to run locally, or --no-verify for an emergency).
WARD=0→ the stub skips Ward without starting it;ward runcalled directly exits 0 too. A chained<hook>.pre-wardstill runs: it is not Ward's (--no-verifyskips everything).- Merge / rebase in progress →
runexits 0. WARD_SKIP_TAGS/--skip-tag→ skip tagged tasks.
yaml- YAML parsingpicomatch- globbing- Everything else: Node built-ins (
child_process,fs,crypto,util.parseArgs) - also available in Bun and Deno
- Node ≥ 24, Bun ≥ 1.1, Deno ≥ 2
- macOS, Linux, Windows (Git Bash runs
#!/bin/shstubs); all three in the CI matrix - Git ≥ 2.20
- A scripts folder with a per-language runner (as in lefthook). Plain commands already cover it:
run: python scripts/check.py. - A Go binary. Maybe later; for now Ward is a JS package for Node, Bun and Deno.