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

> git clean -fdx wipes untracked and ignored files plus directories for a pristine tree. Reference for -n, -e, and the cache-clobbering danger on CI runners.

Source: https://latchkey.dev/learn/command-reference/git-clean-fdx  
Updated: 2026-06-25

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

```Terminal
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

| Flag | What it does |
| --- | --- |
| -f | Actually delete (required) |
| -d | Recurse into untracked directories |
| -x | Also remove ignored files |
| -n / --dry-run | Preview without deleting |
| -e <pattern> | Exclude paths from removal |

## 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

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

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt