Git Clean: Safely Remove Untracked Working-Tree Content

Advanced

Learner goal

By the end of this lesson, you should be able to predict what `git clean` considers removable, preview a cleanup safely, distinguish untracked files from ignored files, use directory and pathspec controls deliberately, and explain why Git normally requires force before deleting untracked content.

What `git clean` removes

The official Git documentation defines `git clean` as removing files that are not under version control from the working tree. By default it removes untracked files, but it does not recurse into untracked directories unless `-d` is supplied when no pathspec is given. Ignored files are not included unless an option explicitly asks for them.

git status --short --untracked-files=all
git clean -n

`-n`/`--dry-run` reports what would be removed without removing it. Treat this as the mandatory inspection step before a destructive cleanup.

Create an untracked file in a disposable repository.?git clean -n

Why `-f` is normally required

Git normally protects against accidental deletion by refusing `git clean` unless force is enabled. The default `clean.requireForce` setting is true. A plain `git clean -d` therefore refuses to delete content when `-f` is absent.

git clean -d -n
# After reviewing the dry-run output:
git clean -d -f

Untracked directories and `-d`

When no pathspec is supplied, `-d` allows `git clean` to recurse into untracked directories. Without `-d`, an untracked directory is not removed merely because it contains removable untracked files. This is a safety boundary: a directory cleanup can remove more content than a single-file cleanup.

git clean -n
git clean -n -d

Create an untracked directory containing a disposable file.?git clean -n -d

Ignored files: `-X` versus `-x`

Ignored files are normally left alone. `-X`/`--only-ignored` changes the selection to remove only ignored files. `-x` instead removes ignored files as well as ordinary untracked files. These options are intentionally different: `-X` narrows the selection to ignored content, while `-x` broadens it.

git clean -n -d -X
git clean -n -d -x

Create both an ignored file and an ordinary untracked file.?git clean -n -d -X

Limit the cleanup with a pathspec

A pathspec can narrow the paths affected by `git clean`. This is useful when only one directory or path needs cleanup. When a pathspec is supplied, the `-d` rule about recursing into untracked directories does not apply in the same way: matching untracked directories can be affected by the pathspec.

git clean -n -- build/
git clean -n -- scratch.tmp

Use `--` to separate options from pathspecs when you want the boundary to be explicit, especially when a path could otherwise be mistaken for an option.

A safe cleanup workflow

For a real cleanup, reason in this order: identify what is untracked or ignored, preview the exact selection, narrow it with a pathspec when possible, decide whether directories should be included, and only then add force. The preview is evidence; the destructive command should be the smallest command that matches that evidence.

git status --short --untracked-files=all
git clean -n -d -- build/
# If the preview is exactly what you intend:
git clean -d -f -- build/

The working tree contains disposable untracked content.?Review the dry-run output before the forced command.

What `git clean` does not do

`git clean` does not undo modifications to tracked files. It is not a replacement for `git restore`, `git reset`, or `git revert`. It also does not remove files merely because they are ignored unless `-X` or `-x` is used. The command operates on working-tree paths selected by its options and pathspecs.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official source boundary

This lesson is based on the official Git `git-clean` documentation and its documented interaction with ignore rules. No third-party documentation is used for the command semantics.