Pre-commit Code Review

You’ve written code. Before you commit, you want to know if it has patterns that cause problems in production. This guide shows you how to use Unfault for that check.

The Quick Version

unfault review --uncommitted

This reviews only your changed files (staged, unstaged, and untracked). You see a summary of what Unfault found and where to look.

For detailed output with suggested fixes:

unfault review --uncommitted --output full

What Unfault Looks For

Unfault doesn’t check syntax or style. It looks for operational patterns:

Missing safeguards: HTTP calls without timeouts, retries without limits, caches without bounds
Error handling gaps: Empty catch blocks, swallowed exceptions, missing error propagation
Resource issues: Unbounded concurrency, connection leaks, blocking calls in async code
Observability gaps: Missing correlation IDs, no structured logging, absent tracing

These are the patterns that work fine in development and cause incidents in production.

Reading the Output

The default output gives you a summary:

Looks good overall, with a couple spots that deserve a closer look.

At a glance
  · 2 calls without timeouts - could hang if a service is slow
  · 1 empty catch block - errors might vanish silently

────────────────────────────────────────────────────────────────────────────────
847ms - python / fastapi - 3 files
Tip: use --output full to drill into hotspots.

Use --output full to see exactly where the issues are and what to do about them:

unfault review --uncommitted --output full

This shows each finding with:

File and line number
What was detected
Why it matters
A suggested fix (when applicable)

Focusing Your Review

By Dimension

If you’re working on a specific concern:

# Only stability issues (timeouts, retries, error handling)
unfault review --uncommitted --dimension stability

# Only performance issues (blocking calls, resource usage)
unfault review --uncommitted --dimension performance

# Multiple dimensions
unfault review --uncommitted --dimension stability --dimension correctness

By Severity

When there are many findings, focus on high severity first. The summary groups findings by severity, and --output full shows severity for each finding.

Making Decisions

Not every finding needs action. Here’s a framework:

High severity in code you wrote

Worth addressing before commit. These are patterns with real production impact.
Medium severity in code you wrote

Consider the context. If the code is on a critical path, address it. If it’s a script or tool, maybe not.
Low severity

Informational. Good to know, rarely blocking.
Findings in files you didn’t change

Existing patterns. Note them if relevant, but they’re not your responsibility in this PR.

Integrating with Your Workflow

Git Hook

Add a pre-commit hook that runs Unfault:

#!/bin/sh
unfault review --uncommitted --output concise
EXIT_CODE=$?

if [ $EXIT_CODE -eq 5 ]; then
  echo ""
  echo "Unfault found patterns worth reviewing."
  echo "Run 'unfault review --uncommitted --output full' for details."
  echo "Commit anyway with --no-verify if this is intentional."
  exit 1
fi

exit 0

Make it executable:

chmod +x .git/hooks/pre-commit

With AI Agents

If you’re using an AI coding assistant, add to your AGENTS.md:

Before committing changes that involve external services, error handling,
or resource management, run:

    unfault review --uncommitted --llm

Address high-severity code-level findings before committing.

See Use with AI Agents for more detail.

Common Patterns

”I know this is fine”

Sometimes Unfault flags something that’s intentional. A few options:

Add a comment explaining why the pattern is acceptable here
Configure an exception in unfault.toml for this specific case
Just commit - Unfault is advisory, not mandatory

”There are too many findings”

If Unfault reports many findings in existing code:

# Focus on just your changes
unfault review --uncommitted --dimension stability

# Or limit the count
unfault review --uncommitted --top 10

The goal is actionable feedback, not comprehensive audits.

”I want to fix everything”

Resist the urge. Pre-commit review is for catching issues in your changes. Broader cleanup belongs in dedicated refactoring work.