Remove Untracked Files Safely with git clean

git clean removes untracked files from your working directory. It's the command you reach for after a build, generator, or experiment leaves junk in the repo. Always run with -n (dry run) first — that's the safety dance that keeps you from deleting work you forgot to commit.

Tested on git 2.43+.

When to Use This

• Cleaning up build artifacts that didn't get gitignored
• Removing test fixtures created by a script
• Wiping a folder before a fresh code generator run
• Cleaning up after a failed merge that left orphan files

Don't use this when you have uncommitted work in untracked files (commit or stash first) or when you can't tell if a file is junk or important (use -n and read the list carefully).

Code

# Dry run — show what WOULD be deleted (do this first, every time)
git clean -n
 
# Include untracked directories in the dry run
git clean -nd
 
# Actually delete untracked files (NOT directories)
git clean -f
 
# Delete untracked files AND empty/untracked directories
git clean -fd
 
# Also delete gitignored files (DANGEROUS — wipes node_modules, .next, etc.)
git clean -fdx
 
# Interactive mode — git asks for each file
git clean -i

The flags are cumulative: -f (force, required to actually delete), -d (directories), -x (include gitignored), -X (only gitignored).

Usage

The safe cleanup workflow:

# 1) See what's there
$ git status
On branch main
Untracked files:
  scripts/dump.json
  build/output.tmp
  experiments/notes.md
 
# 2) Dry run to see exactly what clean would do
$ git clean -nd
Would remove scripts/dump.json
Would remove build/output.tmp
Would remove experiments/notes.md
 
# 3) Read the list. Do you want to keep any of them?
#    Yes? Save them somewhere or git add them.
#    No? Run for real.
 
$ git clean -fd
Removing scripts/dump.json
Removing build/output.tmp
Removing experiments/notes.md

The dry-run-then-real pattern is the muscle memory you should build. Always.

A dangerous example: full reset including gitignored files.

# This nukes node_modules, .next, .env.local — everything not tracked.
# Useful for "nuke from orbit" troubleshooting. Read the dry run carefully.
$ git clean -nfdx
Would remove .env.local
Would remove .next/
Would remove node_modules/
Would remove dist/
 
# Confirmed? Run for real:
$ git clean -fdx

Pitfalls

• git clean -f is required to actually delete anything by default. Without -f, git refuses, telling you to add -f or set clean.requireForce = false. The friction is intentional.
• -x is the foot-gun. It deletes gitignored files like .env.local, node_modules, build outputs. Run git clean -nfdx first to preview every time.
• Submodules are not cleaned by default. Use -f -f (yes, two -f flags) to clean inside submodules.
• Files in subdirectories require -d. Without -d, only top-level untracked files get cleaned. Untracked directories survive.
• git clean cannot be undone. There's no reflog for deleted files. Once they're gone, they're gone. Always dry-run.
• Interactive mode (-i) is great for cautious cleanup. It walks you through each file and lets you pick. Slower, but safer for ambiguous cases.

Related Snippets & Reading

• Useful git stash Patterns — alternative when you want to keep changes around
• Recover a Deleted Branch with reflog — for accidents elsewhere (clean cannot be undone)
• git clean official docs — full reference