husky-pre-commit-bypass
Use when a Husky hook drags files the change never touched into a commit or rejects it for unrelated code — a `.husky/pre-commit` running the repository formatter followed by `git add -A`, `git status
SKILL.mdplugins/react-frontend-sdlc/skills/husky-pre-commit-bypass/SKILL.md
GitHubHusky pre-commit hook and formatter drift
Profile keys consumed
make.formatmake.lintmake.lint_tscmake.test_unit_clientmake.test_unit_server
Every command below resolves through the profile's make map; skip a step with a recorded note
when its key maps to null.
Overview
The pre-commit hook runs the repository formatter and, in the React SPA shape, follows it with
git add -A — so a focused commit can swallow reformatting of files it never touched. The
compliant fix is to make the tree already formatted and already green before staging, so the
hook becomes a no-op. Skipping the hook is out of policy in every shape.
When to use
- The hook rewrote spec, source, or config files that the change does not touch.
git statusafter a failed commit shows modified files outside the intended scope.- The commit diff is much larger than the change, obscuring review.
- The hook fails on lint or unit tests and the failure is in unrelated code.
- Not for: a deliberate repository-wide formatting pass — there the sweep is the change.
Applicability by repository shape
- React SPA shape (feature modules under the source root, a bootable app, an aggregate CI
target): yes —
.husky/pre-commitruns the target mapped bymake.format, thengit add -A, then the targets mapped bymake.lintandmake.test_unit_client/make.test_unit_server;git add -Ais what pulls unrelated files in. - Next.js app shape (routed pages, no aggregate duplication gate): partial —
.husky/pre-commitruns a staged-files-only lint runner (so no sweep) plus a host-mode type check viamake.lint_tsc; the heavy format / lint / unit-test pass moved to.husky/pre-push. - Component-library shape (Storybook-first, no bootable app, published package): no —
.husky/ships nopre-commithook, and its format target is verify-only.
Procedure
Run the formatter as its own step, before staging anything — the target mapped by
make.formatin the React SPA and Next.js shapes; the component-library shape offers only a verify-only format check, so there is nothing to sweep there:make format # React SPA and Next.js shapes make format-check # component-library shape: verify onlygit status --porcelainDecide what to do with each file the formatter touched but the change did not:
- Pre-existing drift on the branch — land it as its own
style(#N): …commit first, so the feature commit stays readable. - Drift that belongs to nobody — restore it with
git restore <path>and let the branch that owns the file fix it.
- Pre-existing drift on the branch — land it as its own
Reproduce the rest of the hook locally, so nothing fails at commit time: run the targets mapped by
make.lintand bymake.test_unit_client/make.test_unit_server, skipping with a recorded note any key that maps tonull.make lint make test-unit-allStage only the intended files, confirm the set with
git diff origin/main --name-only, and commit normally. The hook now finds a formatted, green tree and changes nothing.Push to the feature branch explicitly — a bare
git pushfollows the configured upstream, which is oftenmain:git push origin HEAD:refs/heads/<feature-branch>
Common mistakes
- Reaching for a hook-skipping flag instead of fixing what the hook flags — the repositories forbid it, and the checks it skips are the same ones CI runs.
- Formatting and committing in one motion — always inspect
git status --porcelainin between. - Amending the sweep away after the fact rather than splitting it into a separate commit.
- Assuming the hook is identical everywhere — in the Next.js shape the expensive gate is on pre-push, so a clean commit can still be rejected at push time.
- Relying on a bare
git push— verify the target ref before pushing.