Add --dirty flag to detect all uncommitted working directory changes

[PaulRBerg]

Context

Biome currently has two flags for filtering files based on VCS state:

Flag	Behavior
--staged	Files staged for commit (uses working directory content)
--changed --since=<ref>	Files with committed changes between branches

There's a gap: no way to check all uncommitted working directory changes (both staged and unstaged) without piping from git:

git diff --name-only HEAD | xargs biome check

Proposal

Add a --dirty flag (or --modified) that checks all files with uncommitted changes:

biome check --dirty
biome lint --dirty

This would be equivalent to files returned by git diff --name-only HEAD (staged + unstaged changes vs HEAD).

Use Cases

1. Local development on main: When working directly on the main branch, --changed --since=main finds nothing (HEAD = main). A --dirty flag would catch all local modifications.

2. Quick pre-push check: Verify all modified files before pushing, regardless of staging state.

3. Simpler pre-commit hooks: Instead of:

   git diff --name-only HEAD | xargs biome check

   Just use:

   biome check --dirty

---

Note

This is related to #3608 which discussed that --staged checks staged files but uses working directory content (not the actual staged content). This proposal is orthogonal—it's about detecting which files to check, not what content to check.

---

Converted from #8447

[tt-a1i]

This would be a nice quality-of-life improvement. The current workaround with git diff --name-only HEAD | xargs biome check has edge cases too:

• Filenames with spaces or special characters can break
• Empty output (no changes) causes xargs to run biome with no arguments
• Need to handle deleted files (which would error since they don't exist)

A native --dirty flag would handle all of this cleanly. The implementation could probably reuse most of the existing --changed logic since it's essentially --changed --since=HEAD.

[PaulRBerg]

What do you think about this proposal, @ematipico?

I find myself needing it all the time - to feed the dirty changelog to Claude/Codex CLI.

In #8447 (comment), you hinted that you like it, but there are some things you want to discuss first.

[ematipico]

The original proposal doesn't address how the new flag will behave:

• local development VS CI (biome ci)
• when --changed and/or --staged are provided via CLI
• when it should be used. We have recipes with git hooks, is there a use case there?

The proposal should cover them.

Also, why the name--dirty and not another name? Is there some other work of art we can use for inspiration? Other tools use the name --allow-dirty, however when these tools don't receive --allow-dirty, they exit with an error. Is there some overlap here?

---

What I'm trying to say is that the original proposal didn't have all the material (requirements) for the implementation.

[PaulRBerg]

• I might be missing something but I don't know why it should have differently in CS vs locally. In both environments, if git is available, there can be uncommitted/unchanged changes. This new flag would cover both.
• Passing both --dirty and --changed OR both --dirtyand--staged` should result into an error because the user's intention is not clear when they pass both flags.
• When it should be used internally? I'm not sure. I'm an occasional contributor to Biome.

why the name--dirty and not another name?

Isn't this how Cargo refers to uncommitted changes?

In any case, no strong preference on the name.

[bennyhobart]

just pinging this thread; feels like a nice utility for my workflow, let me know if you'd like a pr

[PaulRBerg]

Ended up rolling my own biome-lint-dirty Bash script which I added to a justfile:

# Lint only uncommitted changes (staged + unstaged)
# Note: delete when Biome adds support for this: https://github.com/biomejs/biome/discussions/8465
[group("checks"), script("bash")]
biome-lint-dirty:
    set -euo pipefail

    files=()
    while IFS= read -r -d '' file; do
        files+=("$file")
    done < <(
        git -c diff.renames=false diff --name-only -z --diff-filter=ACMRTUXB HEAD -- \
            '*.ts' '*.tsx' '*.js' '*.jsx' '*.json' '*.css'
        git ls-files --others --exclude-standard -z -- \
            '*.ts' '*.tsx' '*.js' '*.jsx' '*.json' '*.css'
    )

    if [ ${#files[@]} -eq 0 ]; then
        echo "No uncommitted JS/TS/JSON/CSS files to lint."
        exit 0
    fi

    na biome lint --no-errors-on-unmatched "${files[@]}"
alias bld := biome-lint-dirty

[shishkin]

My suggestion would be to default --changed without --since to check both staged and untracked files. At least that is what I expected --changed to do before reading the docs ;)

[PaulRBerg]

Me too