Pre-commit Hooks

A pre-commit hook runs archgate check --staged before each commit, so architecture violations are caught on the developer’s machine — before they ever reach a pull request. Because --staged checks only the files in the git staging area, the hook stays fast enough for everyday use.

This guide shows the native git-hook approach plus the two common hook managers. For the full flag reference, see the CLI pre-commit guide at cli.archgate.dev.

Why --staged

archgate check --staged restricts evaluation to git-staged files:

• A project with hundreds of source files but three staged files checks only those three.
• Rules whose files globs match nothing in the staging area are skipped entirely.
• Typical pre-commit checks complete in under a second.

When a rule fails, the command exits with code 1 and the commit is blocked. Violations print to stderr with the ADR ID, rule name, file path, and line number, so you can locate and fix them immediately. Re-stage with git add and commit again.

Note

Use --staged for hooks and the unscoped archgate check (or --base) for CI. The staged scope keeps the local hook fast; CI checks the full diff.

Native git hook

No extra tooling required — git looks for an executable at .git/hooks/pre-commit:

macOS / Linux

Create the hook and make it executable:

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/sh
archgate check --staged
EOF
chmod +x .git/hooks/pre-commit

Windows (PowerShell)

Git for Windows runs hooks through its bundled shell, so a POSIX sh script works. Create the file with a shebang and no .ps1 extension:

@'
#!/bin/sh
archgate check --staged
'@ | Set-Content -NoNewline .git/hooks/pre-commit

Caution

.git/hooks/ is not version controlled, so a native hook lives only on the machine that created it. To share a hook across the team, use a hook manager (below) and commit its config, or point core.hooksPath at a tracked directory.

Hook managers

Hook managers store hook configuration in a committed file, so every clone of the repo gets the same hooks. Both managers below run archgate check --staged exactly as the native hook does.

Lefthook

Lefthook is a fast, cross-platform git hooks manager. Add the check to lefthook.yml:

lefthook.yml

pre-commit:
  commands:
    adr-check:
      run: archgate check --staged

Then install the hooks:

lefthook install

Husky

Husky is a popular git hooks tool for Node.js projects. Add the check to the pre-commit hook:

.husky/pre-commit

archgate check --staged

Ensure the hook is executable:

chmod +x .husky/pre-commit

Running alongside other hooks

Pre-commit hooks usually run several checks. Each command runs independently, and the commit is blocked if any exits non-zero. With Lefthook:

lefthook.yml

pre-commit:
  commands:
    lint:
      run: npm run lint
    typecheck:
      run: npm run typecheck
    adr-check:
      run: archgate check --staged

Useful flags

The check command takes the same flags here as elsewhere; these are the ones relevant to hooks. The complete list lives in the CLI reference.

Flag	Purpose
--staged	Check only git-staged files — required for pre-commit
--verbose	Show passing rules and timing — helpful when debugging why a hook is slow
--adr <id>	Check rules from a single ADR — useful for isolating one rule while debugging
--json	Emit JSON — for piping to custom reporting scripts

Layer your defenses

Pre-commit hooks are the earliest enforcement point a human controls, but they can be bypassed with --no-verify. Keep the CI gate as the authoritative backstop, and let editor plugins enforce ADRs during AI-assisted coding.

Related

CI integration The authoritative merge gate with archgate/check-action.

Migration guide Adopt Archgate into an existing repository.

CLI pre-commit reference Full flag and behavior documentation.