Pre-commit Hooks

A pre-commit hook runs vyb check --staged before each git commit. Violations are shown immediately, and the commit is aborted. This is the fastest feedback loop — the developer fixes issues in their editor before the code ever reaches CI.

Quick setup

vyb init --with-hooks

This writes .git/hooks/pre-commit and makes it executable.

Manual setup

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

Team-wide hooks with Husky

.git/hooks/ is not committed to the repository. For consistent hooks across the team, use Husky:

npm install --save-dev husky
npx husky install
npx husky add .husky/pre-commit "vyb check --staged"

Add to package.json so hooks are installed on npm install:

{
  "scripts": {
    "prepare": "husky install"
  }
}

Commit .husky/pre-commit:

git add .husky/pre-commit
git commit -m "chore: add vybdocs pre-commit hook"

Every developer who clones the repo and runs npm install automatically gets the hook.

Staged-only check

The --staged flag limits vyb check to lines in the git staging area. This is important for performance and to avoid flagging pre-existing violations in code the current commit doesn't touch:

vyb check --staged

Violations in unstaged files are ignored. Only the diff of staged changes is evaluated.

Bypassing the hook

In emergencies, bypass the hook:

git commit --no-verify -m "emergency fix"

This bypasses all pre-commit hooks. The commit will still fail vyb check in CI. Bypass usage is tracked in git reflog.

lint-staged integration

If you already use lint-staged, integrate vybdocs as a staged runner:

package.json

{
  "lint-staged": {
    "**/*.{ts,tsx,js,jsx}": [
      "vyb check --staged"
    ]
  }
}

Note: vyb check --staged evaluates the full staged diff, not individual files. When called by lint-staged, it still checks the entire staged changeset.

Performance

Pre-commit hook run times on typical projects:

Lines of diff	Run time
< 100 lines	~150ms
100–500 lines	~400ms
500–2000 lines	~800ms
2000+ lines	~1.5s

For large commits, vyb check --staged is still faster than running linters because it only evaluates changed lines, not full files.

---

Next: GitLab CI