git clean: deleting untracked files

git clean deletes the files git knows nothing about from your working directory: build artifacts, temporary files, an archive you unpacked in the wrong place.

The difference from git restore matters here. Restore brings modified files back to the shape they have in the history: git has something to put in their place. Clean deals with files that were never in the history at all, and there is nothing to put back. It simply deletes them from disk.

So the order is always two steps. First you look at the list:

$ git clean -n
Would remove archive.zip
Would remove notes-copy.txt

-n (the same thing as --dry-run) changes nothing and only prints what would go. Read the list, agree with it, repeat with -f:

$ git clean -f
Removing archive.zip
Removing notes-copy.txt

The -f flag is required. Without it git refuses:

$ git clean
fatal: clean.requireForce is true and -f not given: refusing to clean

That is a deliberate guard against a stray Enter.

Flags that widen the reach

By default the command touches files only. Directories come in with -d:

$ git clean -nd
Would remove archive.zip
Would remove build/
Would remove notes-copy.txt

Everything hidden by .gitignore is left alone by default. The -x flag lifts that exemption:

$ git clean -ndx
Would remove .env
Would remove archive.zip
Would remove build/
Would remove node_modules/
Would remove notes-copy.txt

This is the point to slow down. The list now holds .env with your local passwords and node_modules with every dependency, which is exactly what .gitignore covers and what you normally need to work. git clean -fdx brings the project directory to the state of a fresh clone; sometimes that is precisely what you want before a build from scratch, but .env will have to be rebuilt by hand afterwards.

To decide file by file, there is the interactive mode -i:

$ git clean -i
Would remove the following items:
  junk1.txt  junk2.txt
*** Commands ***
    1: clean                2: filter by pattern    3: select by numbers
    4: ask each             5: quit                 6: help
What now>

Common mistakes

The big one: what git clean deletes does not come back. Neither git reflog nor git restore will help. Those files were never in a commit or in the index, and not a single copy of them is left in the .git directory. Git undoes almost everything, but this is one of its few irreversible commands, alongside git reset --hard.

The second mistake is forgetting where you are standing. The command works from the current directory downwards, so git clean -fdx in the root of the repository takes out far more than the same command inside a subdirectory. The habit of running -n first and reading the list covers both mistakes at once.

Where this is in the book

How clean differs from restore and why .gitignore holds it back is covered here: Chapter 4. Inspect, undo, ignore.