ifchange

Lint for cross-file dependencies. Rename an env var in your deploy config, forget the code that reads it? ifchange catches it in the diff. 128 file extensions, 50+ languages. Robust and fast.

How it works:

• Mark related code sections with LINT.IfChange / LINT.ThenChange comments.
• When a guarded section changes in a PR or commit, every referenced file must change too, or the build fails.

Rust implementation of Google's IfThisThenThat (IFTTT) linting pattern. TypeScript implementation: ebrevdo/ifttt-lint.

Install · Usage · Directive Syntax · CI / Automation · Performance · Supported Languages

Install

curl -fsSL https://raw.githubusercontent.com/slnc/ifchange/main/install.sh | sh
cargo install ifchange        # Rust / crates.io
npm install -g @slnc/ifchange # Node.js / npm
pip install ifchange          # Python / PyPI

Pre-built binaries for Linux, macOS, and Windows available on GitHub Releases.

Build from source:

cargo install --path .

Usage

1. Fence related sections with directives:

# deploy/app.yml
# LINT.IfChange
env:
  DATABASE_URL: postgres://prod:5432/myapp
  REDIS_URL: redis://prod:6379
# LINT.ThenChange(src/config.py#env)

# src/config.py
# LINT.Label(env)
DATABASE_URL = os.environ["DATABASE_URL"]
REDIS_URL = os.environ["REDIS_URL"]
# LINT.EndLabel

2. Rename an env var in the YAML, forget to update config.py, run ifchange:

git diff HEAD~1 | ifchange

error: deploy/app.yml:2 -> src/config.py#env: target section has no matching changes in diff

found 1 error (1 lint)

You can wire this into a pre-commit hook or CI action to run automatically.

3. More options:

ifchange changes.diff                              # pass a file
ifchange --no-lint                                 # scan only: validate directive syntax
ifchange --no-lint -s ./src                        # scan a specific directory
git diff HEAD~1 | ifchange --no-scan               # lint only: skip syntax scan
ifchange -i '**/*.sql' -i 'config.toml#db' f.diff  # ignore files or labeled sections

--ignore uses glob patterns (*, ?, **) and matches both full relative paths and basenames.

Exit codes: 0 ok, 1 lint errors, 2 fatal error.

Directive Syntax

Directives go at the start of a comment line. Full syntax reference: docs/DIRECTIVES.md.

LINT.IfChange / LINT.ThenChange

IfChange opens a guarded section. ThenChange closes it and lists the files that must co-change.

Simplest case, whole-file target:

# deploy/app.yml
# LINT.IfChange
env:
  DATABASE_URL: postgres://prod:5432/myapp
  REDIS_URL: redis://prod:6379
# LINT.ThenChange(src/config.py)

If env changes, src/config.py must also be modified somewhere in the diff.

With labels, narrow the requirement to a specific section:

# deploy/app.yml                             |  # src/config.py
# LINT.IfChange("env")                       |  # LINT.Label("env")
env:                                         |  DATABASE_URL = os.environ["DATABASE_URL"]
  DATABASE_URL: postgres://prod:5432/myapp   |  REDIS_URL = os.environ["REDIS_URL"]
  REDIS_URL: redis://prod:6379               |  # LINT.EndLabel
# LINT.ThenChange(src/config.py#env)         |

Multiple targets:

# deploy/app.yml
# LINT.IfChange("env")
env:
  DATABASE_URL: postgres://prod:5432/myapp
# LINT.ThenChange([
#   "src/config.py#env",
#   "docs/env-reference.md",
# ])

Absolute paths (repo-root-relative)

A leading / resolves from the repo root, not the filesystem root. This works regardless of where you run ifchange within the repo. The repo root is detected by walking up from CWD looking for .git, .hg, .jj, .svn, .pijul, .fslckout, or _FOSSIL_:

# deploy/app.yml (anywhere in the repo)
# LINT.IfChange
env:
  DATABASE_URL: postgres://prod:5432/myapp
# LINT.ThenChange(/src/config.py#env)

/src/config.py resolves to <repo-root>/src/config.py. Without the leading /, paths are relative to the source file's directory.

Directory targets

A trailing / marks a directory target (like .gitignore conventions). ThenChange(lib/) means "if this block changes, at least one file anywhere under lib/ must also change in the diff." Matching is recursive.

# src/api.py
# LINT.IfChange
SCHEMA_VERSION = 3
# LINT.ThenChange(generated/)

If SCHEMA_VERSION changes, at least one file under generated/ (e.g. generated/models.py, generated/sub/types.py) must also appear in the diff.

Rules:

• ThenChange(lib/) (trailing slash) = directory target, recursive matching
• ThenChange(lib) where lib is a directory = error with suggestion to add /
• Labels are not supported for directory targets (ThenChange(lib/#label) is an error)
• Directory must exist on disk during scan validation
• If the directory was deleted (not on disk), lint reports an error (same as deleted file targets)

Directory targets can be mixed with file targets:

# LINT.ThenChange(generated/, docs/schema.md)

Self-references

Point to a label in the same file with #label (no filename):

# deploy/app.yml
env:
  DATABASE_URL: postgres://prod:5432/myapp
  # LINT.IfChange
  REDIS_URL: redis://prod:6379
  # LINT.ThenChange(#redis)

# ...

# LINT.Label("redis")
redis:
  host: prod
  port: 6379
# LINT.EndLabel

Cross-references

When two or more files reference each other, only changes within an IfChange section trigger validation, not changes elsewhere in the file.

Best practice

Source of truth points at derived files. Bidirectional fencing only when both sides are live code.

CI / Automation

Run it as a pre-commit hook, or as a GitHub Action. See examples/.

GitHub Action

- uses: slnc/ifchange@v1

Pre-commit hook

repos:
  - repo: https://github.com/slnc/ifchange
    rev: v0.1.0
    hooks:
      - id: ifchange        # requires ifchange in PATH
      - id: ifchange-pypi   # OR: auto-downloads binary via PyPI

Performance

Wall-clock time to lint a 30k-line diff or scan all directives in a synthetic 5000-file repo (21 language types, 12-core x86_64) vs the original TypeScript implementation.

Versioning

• We follow semver.
• Stability guarantees.
• During 0.x, minor versions may include breaking changes.

Supported Languages

Special files: Dockerfile{,.*}, .gitignore, go.mod

Recommended AGENTS.md / CLAUDE.md

  - When two code sections need to change in sync, use ifchange comment directives to enforce it.

  ### Example

  ```yaml
  # deploy/app.yml
  # LINT.IfChange
  env:
    DATABASE_URL: postgres://prod:5432/myapp
    REDIS_URL: redis://prod:6379
  # LINT.ThenChange(src/config.py#env)

# src/config.py
# LINT.Label(env)
DATABASE_URL = os.environ["DATABASE_URL"]
REDIS_URL = os.environ["REDIS_URL"]
# LINT.EndLabel

</details>

## [Architecture](docs/ARCHITECTURE.md) · [Contributing](docs/CONTRIBUTING.md) · [Versioning](docs/VERSIONING.md) · [License (MIT)](LICENSE)