git clean -fdx: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git clean -fdx removes every untracked and ignored file and directory, leaving only tracked content.

When a reused runner workspace must be truly pristine, -fdx is the hammer. It is also a foot-gun: the -x flag deletes .gitignored caches, so use it deliberately.

What it does

git clean -fdx force-deletes untracked files (-f), descends into untracked directories (-d), and also removes ignored files (-x). The result is a tree containing only tracked, checked-out content.

Common usage

git clean -fdxn               # DRY RUN first - list what dies
git clean -fdx
git clean -fdx -e .env        # but keep .env
git clean -fdx -e node_modules

Options

Common errors in CI

There is no error to catch - that is the risk. -x removes restored caches like node_modules and build output, which can blow away a cache-restore step and slow the build. Always run -fdxn first, and use -e to protect anything a later step depends on.

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