Biome VCS Integration: useIgnoreFile and --changed
The vcs section tells Biome to read your .gitignore and to support running only on changed or staged files.
VCS integration is what makes --changed and --staged work and lets Biome respect .gitignore. It is two or three lines of config.
What it does
Setting vcs.enabled to true with clientKind "git" turns on git integration. useIgnoreFile true makes Biome honor .gitignore. defaultBranch sets the base for --changed. Once enabled, the --changed and --staged CLI flags work.
Common usage
{
"$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true,
"defaultBranch": "main"
}
}Options
| Key | What it does |
|---|---|
| enabled | Turn VCS integration on |
| clientKind | The VCS client; currently "git" |
| useIgnoreFile | Honor .gitignore (and .ignore) when selecting files |
| defaultBranch | Base branch used by --changed |
| --changed (CLI) | Process only files changed against the base |
| --staged (CLI) | Process only git-staged files |
In CI
For --changed to work on a runner, the checkout must include enough git history to diff against the base branch; a shallow checkout (fetch-depth: 1) can break the comparison. Set fetch-depth: 0 or fetch the base ref so Biome can compute the diff.
Common errors in CI
"--changed needs the VCS integration to be enabled" means vcs.enabled is missing or false. A --changed run that processes everything (or nothing) usually means a shallow clone with no base ref; deepen the checkout. If .gitignore entries are ignored, set vcs.useIgnoreFile to true.