How to remove untracked files with git clean

The clean command is one of Git's many "undo" tools. (Take a look at our First Aid Kit video series for other commands and workflows to undo mistakes.)

Compared to reset or revert, which are also classic undo commands, git clean is different: it targets untracked files that haven't been added to version control yet. This includes files in local directories that aren't listed in your .gitignore file.

When to use the git clean command

Let's say you've programmed yourself into a dead end and want to start over with a clean working copy. git reset --hard is a classic command in this situation - but it will only discard changes in tracked files (i.e., any file that is already under version control).

To get rid of new / untracked files, including those in your local directories or cloud-synced folders, you'll have to use git clean!

Usage Examples and Options

Let's take a look at an example scenario:

$ git status
On branch master

Changes not staged for commit:
  (use "git add ..." to update what will be committed)
  (use "git restore ..." to discard changes in working directory)
      modified:   error.html

Untracked files:
  (use "git add ..." to include in what will be committed)
      img/iconFacebook.png
      login.html
      docs/README.md

Whatever options and parameters you provide: using git clean will only affect untracked files in the repository - in our example img/iconFacebook.png, login.html, and docs/README.md - and leave anything else untouched.

Starting with a "Dry Run"

Before you use git clean to delete untracked files, you should remember an important detail: untracked files, by definition, aren't included in version control - and this means that when you delete them, you will not be able to restore them from Git's history!

This is why the first step when approaching git clean is to make use of its "dry run" functionality using the "-n" flag:

$ git clean -n
Would remove img/iconFacebook.png
Would remove login.html
Would remove docs/README.md

"Dry run" means that Git will not actually perform any deletions, but it only tells you which files it would be removing. If this list looks correct, you can proceed without the safety catch.

Deleting Files with the -f Option

To actually allow git clean to delete files in your working copy, you'll have to use the "force" option:

$ git clean -f

If you want to only delete untracked files in a certain subdirectory of your project, you can additionally specify a path:

$ git clean -f folder/subfolder

By default, folders themselves will no be deleted. If you want to include them, you can use the "-d" flag:

$ git clean -fd

In some situations, you might also - in addition to untracked files - want to delete any ignored files that match a specific pattern. An example use case for this could be when you want to clean out a folder that contains build artifacts. Using the "-x" flag allows you to include ignored items:

$ git clean -fx

Interactive Mode

For more granular control, you can use the interactive mode by adding the "-i" flag:

$ git clean -i

This will present you with a list of options to select from, allowing you to choose which files to remove.

Learn More

• Check out the chapter Undoing Things in our free online book
• More frequently asked questions about Git & version control