git clean: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

git clean deletes untracked files so your working tree matches the repo exactly.

Clean is great for resetting a dirty runner workspace, but it permanently deletes files, so always dry-run first.

What it does

git clean removes files that Git is not tracking. It does not touch tracked files (use restore/reset for those) and requires -f to actually delete anything.

Common usage

git clean -n                  # dry run: list what would be deleted
git clean -fd                 # delete untracked files + dirs
git clean -fdx                # also delete ignored files
git clean -fd -e .env         # but keep .env

Options

Common errors in CI

fatal: clean.requireForce defaults to true; refusing to clean without -i, -n or -f - clean will not run without one of those. Beware -x on runners: it deletes .gitignored caches (node_modules, build output), which can wipe a restored cache.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation