How to remove untracked files with git clean
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.)
revert, which are also classic undo commands,
git clean is different: it targets untracked files that haven't been added to version control, yet.
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. files that already are under version control).
To get rid of new / untracked files, you'll have to use
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)
(use "git add ..." to include in what will be committed)
Whatever options and parameters you provide: using
git clean will only affect untracked files - in our example
login.html - and leave anything else untouched.
The Git Cheat Sheet
No need to remember all those commands and parameters: get our popular "Git Cheat Sheet" - for free!
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!
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
"Dry run" means that Git will not actually perform any deletions, but it only tells you which files would be deleted. If this looks correct, you can proceed without the safety catch.
Deleting Files with the
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. 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
Always Use "Dry Run" First
No matter what combination of options you need to use for your particular use case: it's always a good idea to first perform a "dry run" with the "-n" flag!