gitfault

Enrich thrown errors with git context — who wrote the line, what changed recently, what the code around it looks like — and print it to your terminal or post it to Slack. No account, no SaaS, no data leaves your machine unless you configure a Slack webhook yourself.

The anti-Sentry. Zero runtime dependencies — the core package shells out to the git binary directly instead of pulling in a wrapper library.

Install

npm install gitfault

Requires Node 18+ and a git repository (gitfault reads git blame / git log from the file that threw — it isn't useful outside a repo).

Quick start

import { attachGlobalHandlers } from 'gitfault/attach';

attachGlobalHandlers();

That's it. Any uncaught exception or unhandled rejection now prints an enriched report to stderr before the process exits, e.g.:

Error: kaboom
  at /repo/src/orders.js:42

Blame:
  Jane Doe · a1b2c3d · fix race condition in checkout

Source:
    37 | function processOrder(order) {
    38 |   validate(order);
    39 |
  > 42 |   throw new Error('kaboom');
    41 |
    42 | }

Recent commits:
  a1b2c3d fix race condition in checkout
  9f8e7d6 add order validation

Express / Fastify middleware

import { gitfaultHandler } from 'gitfault/attach';

// Express
app.use(gitfaultHandler());

// Fastify
fastify.setErrorHandler(gitfaultHandler());

The same handler works with both frameworks — it detects which one called it (Express passes a next callback, Fastify doesn't) and either forwards the error unchanged via next(err) or sends it via reply.send(err). Either way, the original error is never swallowed or replaced — enrichment is purely observational.

Sinks

Two ship out of the box: a terminal sink (default) and a Slack sink.

import { attachGlobalHandlers, createSlackSink, terminalSink } from 'gitfault/attach';

attachGlobalHandlers({
  sinks: [terminalSink, createSlackSink({ webhookUrl: process.env.SLACK_WEBHOOK_URL })],
});

createSlackSink posts a Block Kit message (error, file:line, blame, source snippet, and a commit link if a git remote is configured) to a Slack incoming webhook. It never throws or blocks the caller — failures are logged locally with console.error and swallowed. Repeated errors from the same throw site are rate-limited to one Slack message per minute by default.

createSlackSink({
  webhookUrl: 'https://hooks.slack.com/services/...', // or set GITFAULT_SLACK_WEBHOOK_URL
  rateLimitMs: 60_000, // 0 disables rate limiting
});

Write your own sink by matching the shape (enriched: EnrichedError) => void.

Configuration

Both attachGlobalHandlers and gitfaultHandler accept an EnrichConfig:

| Option | Default | Description | | --- | --- | --- | | cwd | process.cwd() | Directory to run git commands in | | contextLines | 5 | Lines of source shown above/below the throw site | | commitCount | 5 | Number of recent commits to fetch for the file | | timeoutMs | 2000 | Kill a git subprocess after this many ms | | ignore | [] | Strings (substring match) or RegExps — files matching skip git/source lookups entirely |

Plus, on attachGlobalHandlers only:

| Option | Default | Description | | --- | --- | --- | | sinks | [terminalSink] | Where enriched errors are sent | | exitOnUncaughtException | true | Call process.exit(1) after handling an uncaught exception, matching Node's default crash behavior | | exitOnUnhandledRejection | true | Same, for unhandled rejections |

Using the enrichment pipeline directly

Everything above is built on one pure function — no I/O side effects beyond the git/fs calls it explicitly makes, and it never throws:

import { enrich } from 'gitfault';

try {
  riskyThing();
} catch (error) {
  const enriched = enrich(error);
  console.log(enriched.blame, enriched.source, enriched.recentCommits);
}

enrich() returns an EnrichedError:

interface EnrichedError {
  name: string;
  message: string;
  stack: string | undefined;
  frames: StackFrame[];       // every parsed frame in the stack
  throwSite: StackFrame | null; // best guess at the frame that threw
  ignored: boolean;           // true if throwSite matched an `ignore` pattern
  blame: BlameInfo | null;
  recentCommits: CommitLogEntry[];
  source: SourceSnippet | null;
}

The lower-level pieces are exported too, in case you want to compose your own pipeline: parseStack, getBlame, getRecentCommits, getSourceSnippet, formatEnrichedError, buildSlackMessage.

Design notes

• Zero runtime dependencies. git is invoked directly via node:child_process; formatting uses hand-rolled ANSI codes, not chalk/boxen.
• Never crashes your app. Every git/fs lookup degrades to null/[] on failure — not in a git repo, file untracked, git binary missing, subprocess timeout, sink throwing — enrichment is best-effort.
• Stateless. No error grouping or deduplication across process restarts; the Slack rate limiter's memory lives only as long as the sink instance.

License

MIT