Git Course 0%

git clean

Advanced Git CLI Dangerous ≈ 5 min

Summary: git clean -fd deletes untracked files and directories from your working tree. Git never recorded them, so nothing can bring them back. git clean -nd shows what would go, and is the form to run first, every time.

Dangerous — this is the one Git command whose damage no reflog, branch or remote can undo.

What it does

Removes files in the working tree that Git is not tracking. By default it leaves ignored files alone and refuses to run without -f, both of which are safety features.

Why it exists

Build output, editor droppings, test artefacts and half-finished experiments accumulate as untracked files. Clean removes them in one step, which is genuinely useful before packaging a release or reproducing a problem from a known-clean tree.

When to use it

  • Clearing build output before a clean rebuild.
  • Removing files an aborted operation left behind.
  • Making the working tree match the repository exactly, when you are certain nothing untracked matters.

When not to use it

  • When you have not read the dry run.
  • With -x, unless you have specifically decided that ignored files, which include .env files and virtual environments, should go too.
  • As a way to "reset everything": that is git reset --hard, and it is a different command with different consequences.

Syntax

Form Effect
git clean -n Dry run: list untracked files that would be removed
git clean -nd Dry run including directories
git clean -f Remove untracked files
git clean -fd Remove untracked files and directories
git clean -ndx / -fdx Also include ignored files
git clean -i Interactive: choose what to remove
git clean -fd <path> Limit to a path

-f is required because clean.requireForce defaults to true. That default is deliberate; do not turn it off.

Examples

Always start with the dry run:

Terminal
$ git clean -nd
Would remove scratch.txt
Would remove tmp/

See what -x would add:

Terminal
$ git clean -ndx
Would remove .env
Would remove scratch.txt
Would remove tmp/

.env appears only with -x, because it is ignored. That single line is the difference between tidying up and deleting your local configuration.

Then, if the list is right:

Terminal
$ git clean -fd
Removing scratch.txt
Removing tmp/

Expected result

The listed files and directories are gone from disk, and git status no longer mentions them. Tracked files are untouched, whatever their state.

Common mistakes

  • Running -f before -n. The dry run is free and is the entire safety mechanism.
  • Adding -x casually. Ignored files are ignored because they are local: credentials, environment files, dependency folders.
  • Assuming it is recoverable. It is not: Git never had these files.
  • Using it to discard tracked changes, which it does not do. That is git restore.
  • Running it in the wrong directory, which is why limiting it to a path is worth doing when you can.

How to undo or recover

There is no Git recovery. Possible sources, in order of likelihood: your editor's local history (IntelliJ's Local History, VS Code's Timeline), your operating system's trash if a tool moved rather than deleted, and a backup. Plan on none of them working.

In VS Code

Discard All Changes in the Source Control view offers to delete untracked files, and asks for confirmation naming the count.

In IntelliJ IDEA

Untracked files appear in the Commit tool window; deleting them there goes through Local History, which makes recovery possible. That is a real advantage over the command line for this particular operation.

git status lists untracked files before you remove them · git stash -u parks untracked files instead of deleting them · git restore for tracked files · .gitignore to stop the clutter appearing.

Lessons that use this command

The dangerous commands list · .gitignore.

Key terms

Untracked Ignored .gitignore Working tree

Related