Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 78 ยท The Basic Workflow

git clean in Depth

Learn git clean: dry runs with -n, removing untracked files and directories, ignored files with -x and -X, interactive mode, pathspecs and the safety net you do not have.

Every project accumulates debris: build output, scratch files, editor backups, files left behind after you switched branches. git status lists the untracked ones, but it cannot remove them. git clean can. It is also one of the few Git commands that deletes files for good: untracked files were never committed, so there is no reflog, no stash and no commit to bring them back from.

That is why the whole lesson is built around one habit: look before you delete. You will learn the dry run, the flags that widen or narrow what is removed, interactive mode, and how to limit a clean to one folder.

What counts as untracked

Git sorts the files in your working tree into three groups: tracked (in the last commit or the index), untracked (not known to Git) and ignored (matched by .gitignore). git clean works only on the second group by default. Tracked files are never touched, even if you changed them.

flowchart LR
  A["Working tree files"] --> B["Tracked<br/>never removed"]
  A --> C["Untracked<br/>removed by git clean -f"]
  A --> D["Ignored<br/>removed only with -x or -X"]

git clean only looks at untracked files, and at ignored ones only when you ask.

Dry run first: -n

Git refuses to delete anything unless you pass -f (or -i). This is controlled by the setting clean.requireForce, which is true by default. The flag -n (--dry-run) shows what would be removed, without removing it.

Bash A dry run, then the real clean

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Notice three things in the output. Plain git clean refused and told you to use -f. The dry run listed draft.txt and notes.tmp as Would remove ..., but not the build folder: by default git clean only removes untracked files, and leaves untracked directories alone. The real run printed Removing ... for the same two files, and build/ is still there.

Make the dry run a reflex. Type git clean -n, read the list, then press the up arrow and change -n to -f.

Directories: -d

To remove untracked directories as well, add -d. The dry run shows directories with a trailing slash.

Bash Removing untracked directories with -d

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Without -d nothing is listed, because both untracked paths are directories. With -d they appear as build/ and cache/, and -fd removes them with everything inside. The tracked src/ folder survives.

There is one more subtlety: a directory that contains its own .git folder (a nested repository) is skipped even with -d. You must pass -f twice (git clean -ffd) to remove it. This protects, for example, a cloned dependency that someone dropped into your tree.

Ignored files: -x and -X

Two capital-and-lowercase flags control ignored files, and mixing them up is the classic mistake:

Flag Removes Typical use
(none) untracked files that are not ignored tidy scratch files, keep build output
-x untracked files and ignored files return to a pristine checkout
-X only ignored files delete build output, keep your scratch work
Bash Lowercase -x versus uppercase -X

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The plain run lists only todo.txt. The -x run adds build/ and main.o. The -X run lists just those two ignored entries and spares todo.txt. A common workflow is git clean -ndX followed by git clean -fdX to wipe build artifacts without touching hand-written files. Be careful with -x: a local .env file with secrets or configuration is usually ignored and will vanish too.

Limiting the scope

Everything above works on the whole tree from where you run it (including subfolders). Give git clean pathspecs after -- to limit it, and -e to protect patterns for one run.

Bash Pathspecs and -e exclusions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

A pathspec after -- narrows the clean to that folder. -e keep.tmp adds an exclude pattern, using the same syntax as .gitignore, so the dry run skips src/keep.tmp. The last command removed only docs/draft.tmp; the two src files are still reported as untracked.

Interactive mode: -i

When the list is long and you want to pick, -i opens a small menu: clean everything shown, filter by pattern, select by number, ask for each file. It needs a terminal to type answers, so here is the menu as a read-only transcript:

CONSOLE
$ git clean -i
Would remove the following items:
  draft.txt  notes.tmp
*** Commands ***
    1: clean                2: filter by pattern    3: select by numbers
    4: ask each             5: quit                 6: help
What now> 4
Remove draft.txt [y/N]? n
Remove notes.tmp [y/N]? y
Removing notes.tmp

Interactive mode is the safest way to clean in a messy tree because you confirm each path. It also does not need -f.

git clean is rarely used alone. These neighbours cover the other halves of "get my tree back to a known state":

  • git restore . (or git checkout -- .) discards changes to tracked files. git clean handles untracked ones. See Undoing Things: Restore, Reset and Amend.
  • git reset --hard plus git clean -fd is the "make it look exactly like HEAD" pair. The reset resets tracked files; the clean removes the rest. Read reset in Depth first so you know what the reset destroys.
  • git stash -u saves untracked files in a stash instead of deleting them, so nothing is lost (Stash).
  • .gitignore is the better answer to "this keeps showing up": ignore the pattern instead of cleaning it each time (.gitignore).
  • A global safety setting: git config --global clean.requireForce true is already the default, so do not turn it off.

There is no undo. Files removed by git clean do not go to a recycle bin and are not in the reflog. If you are unsure, move the files away or run git stash -u first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command shows what git clean would delete without deleting anything?

    -n (--dry-run) prints 'Would remove ...' lines and changes nothing. -f performs the deletion, -d adds directories and -x adds ignored files.
  2. 2. You run git clean -f in a repository that has an untracked folder build/ containing files. What happens to build/?

    By default git clean removes untracked files only. Add -d to remove untracked directories.
  3. 3. You want to delete build output that is listed in .gitignore but keep your untracked hand-written notes. Which flag do you use?

    Uppercase -X removes only ignored files. Lowercase -x removes ignored and non-ignored untracked files, which would delete your notes too.
  4. 4. Why can't you recover files deleted by git clean from the reflog?

    Untracked files are not stored in Git's object database. Once deleted from disk there is nothing to restore, which is why you run a dry run first.

Summary

  • git clean deletes untracked files; tracked files are never touched.
  • Git refuses to run without -f (or -i). Always start with git clean -n and read the list.
  • -d includes untracked directories; -ff is needed for nested repositories.
  • -x adds ignored files to the clean; -X cleans only ignored files.
  • Limit the scope with pathspecs after -- and protect files with -e pattern; use -i to confirm each path.
  • Deleted untracked files cannot be recovered. Consider git stash -u when in doubt.

Next: Branches