Skip to content

Incremental Cache

behave-lint supports incremental caching to speed up repeated lint runs. When enabled, only files that have changed since the last run are re-linted. Unchanged files reuse cached diagnostics.

How It Works

  1. On each run, behave-lint computes a SHA-256 hash of every .feature file's content.
  2. If the hash matches a previous run and the configuration hasn't changed, the cached diagnostics are reused — rule execution is skipped entirely for that file.
  3. If the hash doesn't match (file modified) or the config changed (different rules, severities, etc.), the file is re-linted and the cache is updated.

The cache is stored as a JSON file in the cache directory (.behave-lint-cache/ by default).

Configuration

CLI Flags

# Enable cache (default when not using --fix)
behave-lint features/

# Disable cache for this run
behave-lint --no-cache features/

# Clear cache before running
behave-lint --clear-cache features/

Configuration File

[tool.behave-lint]
cache = true
cache-dir = ".behave-lint-cache"

Environment Variables

Variable Default Description
BEHAVE_LINT_NO_CACHE 0 Set to 1 to disable cache.
BEHAVE_LINT_CACHE_DIR .behave-lint-cache Cache directory path.

Cache Invalidation

The cache is automatically invalidated when:

  • File content changes — any modification to a .feature file produces a different hash.
  • Configuration changes — the cache stores a hash of relevant config fields (select, ignore, profile, group, severity overrides, rule params, fail_on). Changing any of these invalidates all entries.
  • Cache version mismatch — if the cache format changes between releases, old caches are ignored.

Limitations

  • Auto-fix mode — the cache is automatically disabled when using --fix or --unsafe-fixes, since fixes require rule execution to collect FixEdit objects.
  • Cross-file rules — diagnostics from cross-file rules (e.g. BC005 duplicate-feature-names) are never cached, since they depend on other files' contents. When a cross-file rule is enabled, all files are still parsed on every run so the project model is complete; the cache only skips single-file rule execution.
  • Cache size — the cache grows with the number of unique file versions. Use --clear-cache periodically or add the cache directory to .gitignore.

Statistics

Cache hits and misses are reported when using --statistics:

Statistics: 13 diagnostics (0 error, 6 warning, 7 info), 10 files,
50 rules, 21.4 ms. Cache: 8 hits, 2 misses.