# git clean: Usage, Options & Common CI Errors

> git clean removes untracked files from the working tree. Reference for -n, -f, -d, -x, and the "would clobber" and safety errors that matter in CI.

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

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

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

| Flag | What it does |
| --- | --- |
| -n / --dry-run | Show what would be removed |
| -f / --force | Actually delete (required) |
| -d | Also remove untracked directories |
| -x | Also remove ignored files |
| -e <pattern> | Exclude paths from cleaning |

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

```.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: Usage, Options & Common CI Errors?

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

---

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