Global flags

Control the project root, config, output format, scope, cache, and CI gates the same way on every fallow command. Reference for the shared CLI flags, including workspace, changed-workspaces, score, trend, and snapshot options.

These flags work the same way across fallow commands, so you learn them once. They set the project root, the config, the output format, the scope, the cache, and the CI gates. Some commands reject a flag that has no meaning for them.

Reference

The --dupes-* flags apply to combined mode. When you do not set one, fallow uses the config value. Each one works like the fallow dupes flag with the same name.

Save destinations

The save flags (--save-baseline, --save-regression-baseline, --save-snapshot) and the report flags (--output-file, --sarif-file) write only inside these directories:

• the project root
• its Git work tree, when the working directory is also inside that tree
• the CI workspace: GITHUB_WORKSPACE and GitLab CI_PROJECT_DIR, when they are set
• RUNNER_TEMP
• the system temp directory

Before the analysis runs, fallow resolves the file that each flag writes, and resolves symlinks first. A path outside these directories, for example ../outside.json, exits 2. The check also applies to the default destinations: .fallow/snapshots for a bare --save-snapshot, and the config file for a bare --save-regression-baseline. A committed .fallow or config symlink therefore cannot move the write. A relative path still resolves against the working directory.

The CI workspace keeps a GitHub Action job working that checks out into a subdirectory (actions/checkout with path: app) and sets root: app. The job runs from the workspace, which is outside the Git work tree of the root.

An existing character device or named pipe is always allowed, because a write to it creates no file. So -o /dev/null, --sarif-file /dev/stdout, and process substitution keep working. When stdout is a regular file, /dev/stdout resolves to that file, and the directory rule applies to it. On Windows, NUL writes to the null device, in any case and with an optional colon, and so does \\.\NUL. A name with an extension, such as NUL.txt, stays a normal file name.

Fallow checks the resolved path again right before each write, and does not follow a symlink at the last path component. This makes the window for a swapped path smaller, but does not remove it for an intermediate directory. On Windows, the last check and the open are two steps.

When the default cache directory .fallow resolves outside these directories, for example through a committed symlink, the run does not use the cache and prints one note on stderr. The run does not fail. FALLOW_CACHE_DIR, cache.dir, and --no-cache do not change.

The MCP save_baseline, save_regression_baseline, and save_snapshot parameters return a tool error for the same paths.

Parse error gate

By default, a source file that fallow cannot parse does not change the exit code. The parser also rejects valid syntax that is newer than the parser, so the gate is off by default. To fail the run on such a file, pass --fail-on-parse-error or set failOnParseError: true in the config.

When the gate is on and a file has a source-parse-degraded diagnostic, the run exits 1 in every output format. The gate_outcomes["parse-error"] entry has a files array. Each entry names a file and its parser error count. The human output prints one line per file.

• health --report-only shows the verdict and does not fail.
• fallow audit checks every file that it parsed, not only the changed files. A file that was already unparseable therefore fails every audit with the gate on, also with --gate new-only. The audit verdict does not include this gate. Read gate_outcomes for the exit reason.
• The GitHub Action and the GitLab template fail the job when the gate fails. They have no input for this gate: set the config key, or pass the flag in args or FALLOW_ARGS.

An older fallow version rejects failOnParseError as an unknown key. When you commit the key, also set minimumVersion.

Baseline growth gate

--baseline and --fail-on-stale-baseline pass when a change adds a finding and saves the baseline again in the same commit. --fail-on-baseline-growth stops this. It compares each loaded baseline with the same file at a base ref:

• A key that the base file does not have is growth. The run exits 1 and lists each new key per category on stderr.
• A renamed file gives a new key, so it counts as growth.
• In a dead-code baseline with line-free keys ("identity": "dc1"), one more occurrence of a key also counts as growth. A moved line does not. The dupes and health baseline keys did not change.
• A baseline that the base ref does not have is a new baseline. The gate passes and prints a note.
• A base ref that git cannot resolve exits 2, for example in a shallow clone. Fetch the full history (fetch-depth: 0 on GitHub Actions).
• A default base that resolves to HEAD exits 2, because a comparison with HEAD cannot fail. This happens on a branch that tracks its own pushed copy. Pass --baseline-base origin/main in CI.

Without --baseline-base, the gate uses the fallow audit base: --changed-since (alias --base), then FALLOW_AUDIT_BASE, then the merge-base with the upstream or the remote default branch.

The gate applies to the dead-code, dupes and health baselines, to the three baselines of the bare run, and to --dead-code-baseline, --dupes-baseline and --health-baseline of fallow audit. health --report-only and the review brief do not run the gate and say so on stderr. A command that loads no baseline rejects the flags.

A commit can rewrite a dead-code baseline from an earlier release into the line-free form. When the base file has no identity and the head file is dc1, the gate translates each old key to its new key and compares by key and count. A commit that removes one finding and adds another in the same rewrite therefore still fails. Some old keys have no safe translation, for example keys with a line or bare package names. The gate compares the categories with such keys by their entry count.

JSON output reports the verdict as gate_outcomes["baseline-growth"]. observed is the number of new keys and threshold is 0.

fallow dead-code --baseline fallow-baselines/dead-code.json \
  --fail-on-baseline-growth --baseline-base origin/main

Path scope

To get findings for one file or directory only, pass a path as the first argument. The bare fallow command and these commands accept it: check, dupes, health, audit, security, fix, list and similar-code.

fallow src/components
fallow health src/api/client.ts
fallow fix src/legacy

Fallow still builds the graph of the whole project, so cross-file facts such as reachability, re-export chains and importer counts stay correct. Fallow narrows only the reported findings to the file or directory. fix plans and applies only the fixes that touch files in scope.

Repository-root paths in CI formats

CI platforms resolve file paths against the repository root. GitHub annotations, CodeClimate reports in GitLab, and inline review comments reject or misplace paths that are relative to another directory.

When --root points at a subdirectory of a git repository (a monorepo package like packages/app/), fallow writes repository-root-relative paths in the CI formats: github-annotations, github-summary, codeclimate, pr-comment-github, pr-comment-gitlab, review-github, and review-gitlab. Fallow detects the offset between --root and the git toplevel and adds it in front of each path automatically, so annotations land on the correct lines.

• In containerized or vendored checkouts, the git toplevel can differ from the CI workspace. Use --report-path-prefix to override the detected offset.
• An empty string (--report-path-prefix '') disables the offset and gives --root-relative paths again.
• --annotations-path-prefix is the old name of --report-path-prefix. Fallow still accepts it as an alias, with the same behavior.

For supplied diffs (--diff-file, --diff-stdin, FALLOW_DIFF_FILE), fallow works in the other direction. It detects if the paths in the diff are repository-root-relative or --root-relative, and filters findings to match. A diff that parses but touches no analyzable files (deletion-only, binary-only, or empty) filters the report to zero findings. Only when fallow cannot place the paths of a diff at all does it fall back to the full-scope report, with a warning.

Request outcomes

--changed-since, a supplied diff and --sarif-file ask a run to narrow its report, or to write a file next to it. When the run cannot apply one of them, it continues and the exit code does not change. --format json tells you the result of each request in a root object, keyed by request name. gate_outcomes uses the same shape for the gate results of the run:

{
  "kind": "dead-code",
  "request_outcomes": {
    "changed-since": {
      "status": "not-applied",
      "affects": "scope",
      "requested": "origin/main",
      "reason": "not-a-repository",
      "message": "--changed-since 'origin/main' was ignored because not a git repository, so this report covers the whole project instead of the changed files. Run fallow from inside the repository, or drop --changed-since."
    },
    "diff-filter": {
      "status": "applied",
      "affects": "scope",
      "requested": "--diff-file pr.diff",
      "scope_size": 18
    }
  }
}

The object also lists the requests that the run applied. An absent request_outcomes means that the run received no request. It never means that nothing failed.

Expect new keys, status values and affects values in later releases. Read a name, a status or a class that you do not recognize as one more request and one more outcome. Do not read it as an error, and never as applied or as scope. Select on affects and not on a list of names, because a request added later has its own class. A diff that parsed but names no analyzable file reports applied with scope_size: 0, because the run applied the filter over an empty scope.

A request that the run did not apply also prints a warning on stderr. Fallow records the entry in the envelope with or without --quiet, so a script can rely on the envelope.

• fallow audit has no request_outcomes object. It exits 2 when its --base does not resolve, and it never widens the report.
• fallow security records sarif-file as applied with the path it wrote. You can then tell a run that wrote the document from a run that asked for none. If the write fails, the run exits 2 with an error document, so no envelope has that entry as not applied.
• fallow flags and fallow suppressions have only the changed-since entry, because neither applies a diff filter.

Formats other than json show the object as one line:

A request that narrows the report can apply over an empty scope. The line then adds a clause: the report is clean because nothing in it was analyzable. The clause also tells you to check the diff or the ref that you gave the run.

The GitHub Action and the GitLab template expose the affects: "scope" requests that the run could not apply. The Action uses a job output, and the template writes a dotenv variable. Both also print a warning on an empty scope. See CI integration.

Loaded config disclosure

When fallow loads a config file (auto-discovered or from --config), it prints one line to stderr:

loaded config: /repo/.fallowrc.json

In a monorepo with more than one config, this line tells you which .fallowrc.json fallow uses. Fallow does not print the line when:

• --quiet is set
• --format is anything other than human (json, sarif, compact, markdown, codeclimate, gitlab-codequality, pr-comment-github, pr-comment-gitlab, review-github, review-gitlab, badge, github-annotations, github-summary)

To see the resolved config with extends merged, use the fallow config subcommand.

Examples

# Analyze a project in a different directory
fallow dead-code -r /path/to/project

# Use a specific config file
fallow dead-code -c configs/fallow-strict.json

# JSON output with no progress messages
fallow dead-code -f json --quiet

# Limit parallelism to 4 threads
fallow dead-code --threads 4

# Scope to a single workspace package
fallow dead-code -w @myorg/ui

# Scope to whichever workspaces changed since origin/main (CI primitive)
fallow --changed-workspaces origin/main

# Show timing breakdown
fallow dead-code --performance

# Group issues by CODEOWNERS ownership (see Grouped output below)
fallow dead-code --group-by owner

# Health score in combined mode
fallow --score

# Save a snapshot and track trends
fallow --save-snapshot
fallow --trend

# Let a trusted config file extend an HTTPS URL
fallow dead-code --allow-remote-extends

# Match a health baseline per function, not per file and category
fallow health --save-baseline .fallow/health-baseline.json --baseline-mode identity
fallow health --baseline .fallow/health-baseline.json --baseline-mode identity

# Add TypeScript checker evidence, and fail when it is incomplete
fallow dead-code --type-aware --type-aware-project tsconfig.json --type-aware-require complete

# Keep one run syntactic when the config turns type-aware analysis on
fallow dead-code --no-type-aware

Per-analysis production mode

With the per-analysis production flags, you can turn on production mode for one analysis and keep the other analyses on the full tree. Bare combined runs (fallow with no subcommand) and fallow audit accept three of these flags:

# Treat health as production-only, leave dead-code and dupes in full-tree mode
fallow --production-health

# Audit changed files with production-only health
fallow audit --base main --production-health

The matching environment variables FALLOW_PRODUCTION_DEAD_CODE, FALLOW_PRODUCTION_HEALTH, and FALLOW_PRODUCTION_DUPES accept the same values as FALLOW_PRODUCTION (true, false, 1, 0, yes, no, on, off). The production config field also accepts a per-analysis object:

{
  "production": {
    "deadCode": false,
    "health": true,
    "dupes": false
  }
}

Fallow uses this order of precedence, from highest to lowest:

1. CLI flags (--production, --production-{dead-code,health,dupes})
2. Per-analysis env var (FALLOW_PRODUCTION_HEALTH, and the others)
3. Global env var (FALLOW_PRODUCTION)
4. Config (production: { ... } or production: true)

The legacy boolean form (--production, production: true, FALLOW_PRODUCTION=true) did not change and still applies to every analysis.

With a subcommand other than audit, fallow rejects the per-analysis CLI flags (for example, fallow dead-code --production-health gives an error). In that case, use the bare command or the per-analysis env vars.

Grouped output

With --group-by, each team or package sees its own issues. The flag splits all issues into labeled groups. It works with the analysis subcommands, and with the formats that can show groups. fallow flags ignores it.

With --format json, the output shape changes to a grouped envelope:

{
  "kind": "dead-code-grouped",
  "grouped_by": "owner",
  "total_issues": 12,
  "groups": [
    { "key": "@frontend-team", "total_issues": 8, "unused_files": [], "unused_exports": [] },
    { "key": "@backend-team", "total_issues": 4, "unused_exports": [] }
  ]
}

Each finding goes to the group of its file. A fact about the whole project stays on the root. For example, unused_load_data_keys_global_abstain: true is on the root when the unused-load-data-key rule could not run safely for the project.

The opt-in prop-drilling, thin-wrapper, and duplicate-prop-shape findings are in their groups, but they do not count toward total_issues. In human and markdown output, the group header names them next to the issue count, for example src (0 issues; 3 health signals: 3 duplicate prop shapes).

For --group-by section, each group also has an owners array with the default owners of the section:

{
  "kind": "dead-code-grouped",
  "grouped_by": "section",
  "total_issues": 6,
  "groups": [
    {
      "key": "billing",
      "owners": ["@core-reviewers", "@alice", "@bob"],
      "total_issues": 2,
      "unused_exports": []
    },
    {
      "key": "notifications",
      "owners": ["@core-reviewers", "@alice", "@bob"],
      "total_issues": 1,
      "unused_exports": []
    }
  ]
}

owner puts all sections that share a lead reviewer into one group. section keeps the [Section] headers as group keys, and these keys stay the same when reviewers change.

Incremental caching

Fallow caches parsed file data between runs, so later runs are faster. On the second run, fallow parses only the changed files and loads the rest from the cache.

The cache works in three steps:

1. Fallow hashes each file with xxh3, a fast non-cryptographic hash.
2. If the hash matches the cached version, fallow skips the parse.
3. Fallow builds the module graph from the cached data and the newly parsed data.

fallow dead-code --performance

 Discovery     12ms   (142 files)
 Parsing       48ms   (23 parsed, 119 cached)
 Resolution    15ms
 Analysis       8ms
 Total         83ms

To parse all files again, use --no-cache. This helps after large refactors, or when you debug unexpected results.

fallow dead-code --no-cache

To move the persistent cache out of .fallow/cache.bin, set cache.dir in the project config or FALLOW_CACHE_DIR in the environment. When you set both, the env var wins.

FALLOW_CACHE_DIR=/tmp/fallow-cache fallow dead-code

See also