Git Clean: Preview Untracked Files Before Deleting Them

A build leaves a directory full of generated files, and git status shows a collection of untracked paths. Before you run git clean, find out exactly what it would remove. An untracked file can be a disposable build artefact, but it can also be the only copy of a note, local configuration file or unfinished work.

Git's clean command removes untracked files from the working tree. Start with a dry run, preserve anything you need outside the repository, and limit the cleanup to a known disposable path. This guide follows the Git 2.45 clean reference; it does not assume every untracked file can be rebuilt.

Understand what Git will consider

A tracked file is in Git's index. An untracked file is not; it may never have been committed. Ignore rules can keep untracked files out of ordinary status output, but ignoring a file does not make it unimportant or provide a backup. A local .env file, for example, may hold settings you need and should not be published in a commit.

By default, git clean skips ignored files. Adding -x changes that: it includes ignored files as well as other untracked files. Adding -X instead selects only ignored files. The distinction is case-sensitive. Neither option is a general promise that the selected files are safe to delete. See the Git clean options and Git's ignore rules.

A tracked file with local edits is a different problem. git clean is not a way to undo those edits; inspect them with git status and git diff and decide how to preserve them. Likewise, a file already tracked by Git is not made untracked simply by adding it to .gitignore.

First, inspect the working tree

From the intended repository, run:

git status --short --branch

Check that you are in the right project and branch, and look for untracked paths marked ??. Status can summarise untracked directories rather than listing every file inside. Inspect their contents before deciding they are disposable. Ignored files need separate attention; git status --ignored can show ignored paths too. The status reference explains the output and ignored-file options.

Copy anything valuable to a safe location outside the repository and verify the copy. That includes credentials, personal data, test results and files that are expensive or impossible to recreate. A Git history cannot be relied on to restore content that was never tracked. If you are uncertain about a file's purpose, leave it in place and ask the project maintainer.

Preview before removing anything

From the repository root, preview untracked files and directories under the current directory:

git clean -nd

-n is the dry run: Git reports what it would remove without deleting it. -d includes untracked directories in this broad preview. The output can name a directory as a whole, so inspect any listed directory before approving it. By default, ignored files are not included. The manual also notes special protection for nested Git repositories; do not add extra force flags to bypass it casually.

Suppose the dry run lists scratch.txt and build-output/. The first could be a note and the second could be generated output. Open or otherwise inspect both before making a decision; their names alone do not establish their value. If you need the note, move or back it up, then run the preview again.

Limit a cleanup to a disposable directory

If the project documents build-output/ as regenerable and you have checked its contents, scope the dry run to that path:

git clean -n -- build-output/

The -- separates options from the path. With a path specified, Git considers matching untracked entries recursively, so -d is not needed for this scoped example. Replace build-output/ with the exact path you have checked. If the directory is ignored, the default preview may be empty; do not assume an empty preview proves the folder contains nothing.

For an ignored build directory, inspect the broader effect explicitly:

git clean -nX -- build-output/

-X selects ignored files only. Read the full output and inspect the actual directory; ignored files can include local settings or assets as well as generated output. If the output includes anything you need, stop and preserve it. A preview is specific to the options, path and working-tree state at the time it is run.

Only after that review, use the corresponding command without -n and with -f to perform the deletion:

git clean -fX -- build-output/

This example removes matching ignored untracked content under that path. For the earlier non-ignored preview, the matching execution would be git clean -f -- build-output/. Do not swap -X for -x: lowercase -x would also include non-ignored untracked content. -f authorises removal; it does not create a backup or a recycle-bin guarantee.

If files or ignore rules change after the preview, run the same dry run again and reassess before executing. Avoid broad commands such as git clean -fdx unless you have explicitly examined and accepted their much wider scope.

Confirm the result and rebuild

Run the same dry run again and check the directory and git status. An empty result means that command currently finds no matching removable paths; it does not prove the whole working tree is clean. Use the project's documented build or setup command to recreate disposable output and check that it succeeds.

If a needed file was removed, stop generating or deleting more files and look for a verified backup or another copy. Git may restore a version that was committed, but it cannot recover untracked content from a commit that never contained it. The useful habit is to make the preservation decision before running the destructive command.

References

• Git project: git-clean, version 2.45 — dry runs, force, path selection and ignore options.
• Git project: git-status, version 2.45 — untracked and ignored-file reporting.
• Git project: gitignore, version 2.45 source — ignore patterns and tracked files.