Skip to content
Fallow home
All docs pages

Docs home

fallow audit-cache

Find the subcommands, output fields and exit codes of fallow audit-cache, which removes and prunes the caches of the audit base analysis.

fallow audit-cache removes the caches that fallow audit keeps for the analysis of the base.

For the concepts, read Changed code.

Synopsis

fallow audit-cache [OPTIONS] <COMMAND>

Under --gate new-only, fallow audit analyzes the base in a temporary checkout. It keeps two caches:

  • one checkout of the base for each project root, in the system temp directory
  • the result of each base analysis, in .fallow/cache/audit-base-v<N>/ in the project

Each audit run also removes the cache entries that are older than 30 days, and keeps only the newest 32 result files. The FALLOW_AUDIT_CACHE_MAX_AGE_DAYS environment variable and the audit.cacheMaxAgeDays config key set the age. 0 turns off the age rule. The subcommands do the same work when you run them.

Subcommands

SubcommandDescription
removeRemove reusable audit caches owned by an explicit project root
pruneApply the audit cache cleanup policy and report every entry

remove

fallow audit-cache remove [OPTIONS]
OptionDescription
--dry-runPrint what would be removed without touching the filesystem
--yesConfirm removal in non-interactive environments

remove needs the global option --root <PATH>, and removes each cache of that project. Without a terminal, it needs --yes. An entry that a running audit locks stays, and the command exits with code 2.

prune

fallow audit-cache prune [OPTIONS]
OptionDescription
--dry-runPreview decisions without touching the filesystem
--max-age-days <N>Age threshold in days for this invocation. Overrides FALLOW_AUDIT_CACHE_MAX_AGE_DAYS and the audit.cacheMaxAgeDays config field (default 30).

prune removes the entries that are too old, the entries whose project root does not exist, and the files that no entry owns. It does not remove an entry of another project that exists. --root is optional and defaults to the current directory. The age comes from --max-age-days, then FALLOW_AUDIT_CACHE_MAX_AGE_DAYS, then audit.cacheMaxAgeDays, then the default of 30 days.

Options

This command has no options of its own.

The global options are in these groups: Project, Output, Scope, Baselines, Gates, Duplication, Type-aware, Performance.

The subcommands accept the global options --root, --format and --quiet.

Output

audit cache prune (threshold 30d from default) in /tmp/x/t/
  kept         12f3c4c67ca1fffb.bin  676 B  aged 0d
  kept         4c87a98449d69531.bin  676 B  aged 0d
  kept         5cb50815c05eb1c1.bin  676 B  aged 0d
  kept         6a62088ae02f0515.bin  676 B  aged 0d
  kept         a73de36fcd19a721.bin  676 B  aged 0d
would reclaim 0 B across 0 of 5 entries

The first line gives the age threshold, its source and the directory that prune scans. Each entry has a line with the decision, the name, the size and the age. The last line gives the bytes that the run removes.

With --format json, prune gives these top-level fields:

FieldContent
kind"audit-cache-prune". remove gives "audit-cache-remove".
schema_version, commandThe version of this output format and the command.
root, scan_rootThe project root and the directory that prune scans.
dry_runtrue with --dry-run.
max_age_days, max_age_sourceThe age threshold and its source: flag, env, config or default.
entriesOne object for each entry: path, pass (owned, legacy, foreign or snapshot), disposition (removed, kept, skipped or failed), reason (for example aged-out, fresh, owner-live or over-capacity), age_days, size_bytes, owner_root.
found, removed, kept, skipped, failedThe counts. removed, kept, skipped and failed together are found.
deregisteredThe checkouts that the run removed from the git worktree list.
completetrue when no entry was skipped or failed. Use this field in scripts.
reclaimed_bytesThe bytes that the run removed, or would remove with --dry-run.

The remove output has root, dry_run, found, would_remove, removed, skipped and complete. The JSON output reference has each field.

Exit codes

CodeMeaning
0The command ran. prune also exits with 0 when it skips an entry: read complete.
2Invalid input, for example remove without --root. remove also exits with 2 when a running audit locks an entry.

Exit codes has the codes that all commands share.

Examples

# Show what prune removes, and change nothing
fallow audit-cache prune --dry-run

# Remove the entries that are older than 7 days
fallow audit-cache prune --max-age-days 7

# Show which caches of one project remove takes
fallow audit-cache remove --root ./my-project --dry-run

# Remove the caches of one project without a prompt
fallow audit-cache remove --root ./my-project --yes