Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt

Use this file to discover all available pages before exploring further.

Create a configuration file for your project. The generated config includes a $schema field so your editor can provide autocomplete and validation.
Most projects don’t need a config file. Fallow works out of the box by auto-detecting entry points and frameworks. Only create one if you need custom entry points, rules, or ignore patterns.
Fallow’s init command auto-detects your project setup and tailors the generated config accordingly:
  • TypeScript: Detects tsconfig.json and enables TypeScript-aware defaults
  • Monorepo: Detects workspace configurations (npm, yarn, pnpm) and includes workspace patterns
  • Frameworks: Detects installed frameworks (Next.js, Remix, Vite, etc.) and adds appropriate entry point patterns
fallow init

​
Options

FlagDescription
--tomlGenerate fallow.toml instead of .fallowrc.json
--hooksScaffold a pre-commit git hook that runs fallow on changed files. Alias for fallow hooks install --target git
--branch <REF>Fallback base branch for the hook when no upstream is set (requires --hooks, default: main)

​
Pre-commit hook

Use the hooks namespace to scaffold a git hook that runs fallow audit against the base branch before each commit: 
fallow hooks install --target git
fallow init --hooks remains available as a project-initialization shortcut. Fallow detects your hook manager and writes to the right location:
  1. Husky — adds to .husky/pre-commit
  2. Lefthook — adds to lefthook.yml
  3. Bare hooks — writes .git/hooks/pre-commit
The generated hook:
  • Includes a binary guard (command -v fallow) so commits still work when fallow isn’t installed
  • Resolves the base ref at commit time: git merge-base @{upstream} HEAD when an upstream is set, falling back to the configured branch (or main) otherwise. Feature branches forked from a non-default integration branch (next-release / hotfix / LTS) compare against the right base, not against their own remote tracking branch
  • Runs fallow audit --base "$BASE" --quiet, which combines dead-code, complexity, and duplication analysis
  • Defaults to gate=new-only, so inherited findings on touched files do not block the commit; only findings introduced by the changeset fail the gate. Set [audit] gate = "all" in fallow.toml to fail on every finding in changed files
  • Returns exit code 1 on verdict: "fail" (default audit semantics); no --fail-on-issues is needed
  • Prints git commit --no-verify as the bypass option in the success message
Want to gate Claude Code or Codex agent commits as well? Use fallow hooks install --target agent for the agent enforcement path. The two hooks are complementary: fallow hooks install --target git catches human commits, fallow hooks install --target agent catches agent commits.

​
Custom base branch

By default, the hook compares against the merge-base of the current branch’s upstream and HEAD, falling back to main when no upstream is set. Override the fallback with --branch: 
fallow hooks install --target git --branch develop

​
Gitignore

fallow init automatically adds .fallow/ to your project’s .gitignore. The .fallow/ directory contains machine-local data (parse cache, regression baselines, snapshots) that should not be committed.
  • If .gitignore exists and already contains .fallow/, nothing changes
  • If .gitignore exists without it, the entry is appended
  • If .gitignore doesn’t exist, it is created

​
Output

The generated config includes a $schema field for IDE autocomplete. Editors like VS Code will provide inline validation and suggestions automatically.
By default, creates .fallowrc.json: 
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "rules": {}
}
With --toml, creates fallow.toml.

​
See also

Configuration overview

Full reference for all configuration options.

Quickstart

Get started with fallow in under a minute.