Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

Share the pre-commit hook across worktrees

David Zhang3597d2c0dfcc
diff --git a/.agents/skills/ratchet-files/SKILL.md b/.agents/skills/ratchet-files/SKILL.md
index 3d73da2..f15d16d 100644
--- a/.agents/skills/ratchet-files/SKILL.md
+++ b/.agents/skills/ratchet-files/SKILL.md
@@ -1,6 +1,13 @@
---
name: ratchet-files
-description: Ratchet source file size so every file stays small enough for an agent to read whole: find every file over a token budget, split oversized files by concept, and set up the pre-commit ratchet that stops them from growing. Use when a commit is blocked because a file is over the size budget, when asked to find or split oversized/long/god files, when a file you need to change is too large to read in one pass, or when asked to add a file-size limit or hook to a repository.
+description: >-
+ Ratchet source file size so every file stays small enough for an agent to read
+ whole: find every file over a token budget, split oversized files by concept,
+ and set up the pre-commit ratchet that stops them from growing. Use when a
+ commit is blocked because a file is over the size budget, when asked to find
+ or split oversized/long/god files, when a file you need to change is too large
+ to read in one pass, or when asked to add a file-size limit or hook to a
+ repository or repair commit-hook coverage across worktrees.
---
# Ratchet Files
@@ -72,7 +79,9 @@ Once they agree, set up everything the check needs:
manager its lockfile names, or npm if there is none. The check needs Node
even in a repository written in another language: with no `package.json`,
create one at the root holding only `"private": true` and what this setup
- adds, and make sure `.gitignore` covers `node_modules/`.
+ adds, and make sure `.gitignore` covers `node_modules/`. Choose dependency
+ versions compatible with the repository's supported runtime; the check
+ script's minimum Node version does not establish the runner's minimum.
- **Hook.** Run the script on every staged file with `node` (or `bun` where
the repository already runs its tools with it), appending `--max-tokens N`
for a budget other than the default. Add it beside the existing entries of
@@ -85,22 +94,52 @@ Once they agree, set up everything the check needs:
| pre-commit | `.pre-commit-config.yaml`, `repo: local` | `id: ratchet-files`, `name: source file size`, `entry: node scripts/check-file-size.mjs`, `language: system` |
| husky or a plain hook | the `pre-commit` script | `git diff --cached --name-only -z \| xargs -0 node scripts/check-file-size.mjs` |
- With no runner, add husky with lint-staged as dev dependencies, run
- `npx husky init`, replace the whole of `.husky/pre-commit` (it starts as
- `npm test`) with `npx lint-staged` or the package manager's equivalent, and
- add the lint-staged entry above. Husky installs the hook on each clone's
- package install.
+ Inspect `git config --show-origin --get core.hooksPath` and the existing
+ hooks before changing installation. A relative hooks path is resolved in
+ each checkout, but the config is normally shared: setting `.husky/_` in
+ one checkout does not generate that directory in a new worktree. Reuse an
+ existing runner only with a working installation path for linked worktrees.
+
+ With no runner, add lint-staged as an exact dev dependency and copy
+ [`scripts/install-git-hooks.mjs`](scripts/install-git-hooks.mjs) into the
+ repository's tool scripts. If this skill is committed in the repository,
+ use its bundled installer directly. Adapt the hook's check-script path and
+ package-install instruction to the repository, and invoke the installer
+ from the root package's `prepare` lifecycle, preserving existing prepare
+ work. Commit the installer; hooks must never depend on a global skill path.
+
+ The bundled installer owns shared-hook installation, repeat installs from
+ either checkout type, missing-dependency guidance, and preservation of
+ custom hooks. Reuse it rather than authoring another installer. Its hook
+ runs each committing checkout's installed lint-staged and config; each
+ worktree still needs dependencies. Never share build output to provide them.
+
+ Inspect any reported hook conflict before proceeding. When replacing a
+ repository-owned hook runner, preserve its other checks while migrating
+ its hooks-path setting and removing obsolete setup and dependencies. Do
+ not unset a user's custom setting or leave competing installers. Extend
+ the bundled installer's behavior checks when adapting its installation
+ logic: `node --test scripts/install-git-hooks.test.mjs` from this skill.
- **Exclusions.** Mark generated and vendored code `linguist-generated` or
`linguist-vendored` in `.gitattributes` instead of adding skip lists. The
script reads the staged `.gitattributes`, so stage it before rerunning
`--all`.
-- **Docs.** Document the budget, the opt-out pragma, and that a clone needs a
- package install for the hook, where the repository documents its other
- hooks; failing that, in a section of its README, creating one if needed.
+- **Docs.** Document the budget, the opt-out pragma, how package installation
+ enables hooks across worktrees, and that each committing checkout needs
+ dependencies, where the repository documents its other hooks; failing
+ that, in a section of its README, creating one if needed.
Commit the setup through the new hook, without `--no-verify`.
-Done when the setup commit passed the hook, and the installed hook refuses
-`git commit` both of a staged new source file over the budget (a `.js` file
-of more than four bytes per token of budget) and of a line added to a file the audit
-listed, printing the split rules. Unstage and discard both probes afterwards.
+Verify with real `git commit` attempts in disposable repository fixtures,
+using the committed installer, runner configuration, and size-check script.
+Install once, then create a linked worktree without rerunning installation
+there. Make its dependencies available and prove its own staged oversized
+new file is refused with the split rules while an under-budget commit
+succeeds and the main checkout stays unchanged. Also prove an existing
+oversized file cannot grow, a checkout without dependencies refuses with
+setup instructions, repeated installation from a linked worktree works, and
+custom hooks survive installation. Remove the fixtures afterwards.
+
+Done when these commit checks pass in both checkout types and the setup
+commit passed the new hook without bypassing it.
diff --git a/.husky/pre-commit b/.husky/pre-commit
deleted file mode 100755
index a926c36..0000000
--- a/.husky/pre-commit
+++ /dev/null
@@ -1,2 +0,0 @@
-#!/bin/sh
-npx lint-staged
diff --git a/README.md b/README.md
index 0b7fd4d..6aed07b 100644
--- a/README.md
+++ b/README.md
@@ -174,4 +174,4 @@ policy.
## Ratchet Files
-Source files are limited to 8,000 estimated tokens (bytes divided by four). The pre-commit hook runs `scripts/check-file-size.mjs` through lint-staged, so a clone must install the repository dependencies before commits. Existing oversized authored files are frozen at their current size; generated and vendored paths are excluded through `.gitattributes`. A file may use `@ratchet-files-ignore` in its first 10 lines only when splitting it would cost more than it saves, with the reason beside the pragma.
+Source files are limited to 8,000 estimated tokens (bytes divided by four). The pre-commit hook runs `scripts/check-file-size.mjs` through lint-staged. `bun install` runs `scripts/install-git-hooks.mjs`, which installs the hook once in the repository's shared hooks directory, so every linked worktree runs it; each checkout that commits needs its own `bun install`, and commits from one without dependencies are refused. Existing oversized authored files are frozen at their current size; generated and vendored paths are excluded through `.gitattributes`. A file may use `@ratchet-files-ignore` in its first 10 lines only when splitting it would cost more than it saves, with the reason beside the pragma.
diff --git a/bun.lock b/bun.lock
index 542c8a7..3b7be04 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,7 +5,6 @@
"": {
"name": "jevgrep",
"devDependencies": {
- "husky": "9.1.7",
"linguist-languages": "9.5.0",
"lint-staged": "17.6.0",
"oxfmt": "0.57.0",
@@ -188,8 +187,6 @@
"fast-wrap-ansi": ["[email protected]", "", { "dependencies": { "fast-string-width": "^3.0.2" } }, "sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q=="],
- "husky": ["[email protected]", "", { "bin": { "husky": "bin.js" } }, "sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA=="],
-
"ignore": ["[email protected]", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
"json-schema": ["[email protected]", "", {}, "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA=="],
diff --git a/package.json b/package.json
index ab1ca7f..dd5f6e4 100644
--- a/package.json
+++ b/package.json
@@ -29,7 +29,7 @@
"verify": "bun run check-types && bun run lint && bun run test && bun run test:installed",
"eval:swebench": "python3 evals/implementation/swebench/installed.py",
"test:native": "node scripts/test-native.mjs",
- "prepare": "husky"
+ "prepare": "node scripts/install-git-hooks.mjs"
},
"devDependencies": {
"oxfmt": "0.57.0",
@@ -37,7 +37,6 @@
"turbo": "2.10.3",
"typescript": "catalog:",
"linguist-languages": "9.5.0",
- "husky": "9.1.7",
"lint-staged": "17.6.0"
},
"engines": {
diff --git a/scripts/install-git-hooks.mjs b/scripts/install-git-hooks.mjs
new file mode 100644
index 0000000..048edcf
--- /dev/null
+++ b/scripts/install-git-hooks.mjs
@@ -0,0 +1,48 @@
+// Installs the pre-commit hook in the shared hooks directory, so every
+// worktree of this repository runs it without its own install. Run by prepare.
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const marker = "# Installed by ratchet-files";
+const hook = `#!/bin/sh
+${marker}
+# Branches that predate the ratchet have no checks to run.
+[ -f scripts/check-file-size.mjs ] || exit 0
+[ -x node_modules/.bin/lint-staged ] || {
+ echo "pre-commit: dependencies aren't installed in this checkout; run bun install" >&2
+ exit 1
+}
+exec node_modules/.bin/lint-staged
+`;
+
+const git = (...args) =>
+ execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+let common;
+try {
+ common = git("rev-parse", "--path-format=absolute", "--git-common-dir");
+} catch {
+ process.exit(0); // Exported source trees have no hooks to install.
+}
+
+let hooksPath = "";
+try {
+ hooksPath = git("config", "--get", "core.hooksPath");
+} catch {
+ // Unset: Git uses the common hooks directory.
+}
+if (hooksPath && hooksPath !== ".husky/_") {
+ console.warn(`core.hooksPath is ${hooksPath}; not installing the pre-commit hook.`);
+ process.exit(0);
+}
+
+const path = join(common, "hooks", "pre-commit");
+if (existsSync(path) && !readFileSync(path, "utf8").includes(marker)) {
+ console.warn(`${path} exists and is not ours; not replacing it.`);
+ process.exit(0);
+}
+mkdirSync(dirname(path), { recursive: true });
+writeFileSync(path, hook);
+chmodSync(path, 0o755);
+if (hooksPath === ".husky/_") git("config", "--unset", "core.hooksPath");