git clean: Usage, Options & Common CI Errors

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.

Related guides

git reset: Usage, Options & Common CI Errorsgit reset moves HEAD and optionally the index and working tree. Reference for --soft, --mixed, --hard, and ho… git restore: Usage, Options & Common CI Errorsgit restore discards working-tree changes or unstages files. Reference for --staged, --source, --worktree, an… git stash: Usage, Options & Common CI Errorsgit stash saves uncommitted changes aside and restores a clean tree. Reference for push, pop, -u, list, and t… git rm: Usage, Options & Common CI Errorsgit rm removes files from the working tree and the index. Reference for --cached, -r, -f, and the "has staged…