How To Remove Local Untracked Files From The Current Git Working Tree?

An Untracked File is a file that exists in our repository but has never been added to the staging area(or index). An untracked file is a file that has never been part of a commit. Git does not track any changes of an untracked file. Note that untracked files are not part of the version control, and Git cannot restore them once they are deleted from the repository.

The Git Clean command helps us in removing untracked files. There are a lot of different options available with this command. Let's learn how to remove local untracked files from our Git Repository.

Git Clean Dry Run

As mentioned above, once deleted, an untracked file cannot be restored. A dry run allows us to view the untracked files that will be removed when the actual command is executed. Git Clean command with the -n or --dry-run option will perform a dry run. It outputs the file names that will be removed. Note that it will not affect or delete any untracked files.

git clean -n
git clean --dry-run

For example, consider a Git repository with two untracked files(demo1.txt and demo2.txt). If we dry run the Git Clean command, we will get the following output.

git clean --dry-run

Output:

Would remove demo1.txt
Would remove demo2.txt

As we can see in the output, Git tells that demo1.txt and demo2.txt would be removed if we run Git Clean without the -n option.

Git Clean with -f option

The -f option is short for --force. This option allows us to execute the Git Clean command and delete files. An untracked file, once deleted, cannot be recovered. So Git adds this safety feature and uses the -f flag for confirmation.

According to Git Documentation, the -f option will delete untracked files even when the Git configuration variable clean.requireForce is not set to false. It is a good practice to always include this option with the Git Clean command when you want to remove untracked files.

git clean -f
git clean --force

For example, if our repository contains two untracked files(demo1.txt and demo2.txt), then the git clean -f command will delete these two files and return the following output.

Output:

Removing demo1.txt
Removing demo2.txt

Git Clean with -d option

A simple Git Clean command will only delete untracked files. It will not remove any untracked directories. The -d option allows us to delete untracked directories as well. Make sure to use the -f option as well.

git clean -f -d
git clean -fd	# equivalent to the above command

If an untracked directory is a Git Repository or a Submodule, we must use the -f option twice.

git clean -ffd

Note that the -d option is irrelevant if a path is passed to the Git Clean command. In such cases, it removes all untracked files matching the file path.

For example, consider a repository with one untracked file(demo.txt) and an untracked directory(New Folder). If we dry run the Git Clean command with just the -f flag, then it returns the following output.

git clean -f --dry-run

Output:

Would remove demo.txt

To remove both the untracked file and the untracked folder, then we need the -d option.

git clean -fd

Output:

Removing demo.txt
Removing New folder/

Git Clean with -x and -X option

Git Clean has the -x and -X options to delete ignored files. The difference between them is that -X will only delete ignored files, but -x will remove both ignored and un-ignored files.

git clean -f -X # only ignored files
git clean -f -x # both ignored and un-ignored files

For example, consider a repository with two untracked files(demo1.txt and demo2.txt). The demo2.txt file is an ignored file. Let's compare the dry run outputs of -x and -X options.

git clean -f -X -n 
git clean -fXn # equivalent

Output:

Would remove demo2.txt

git clean -f -x-n 
git clean -fxn # equivalent

Output:

Would remove demo1.txt
Would remove demo2.txt

As we can see, -X option only removes demo2.txt(ignored file) but the -x option removes both demo1.txt and demo2.txt.

Conclusion

The Git Clean command helps us remove untracked files and folders from our repository. We have discussed the most frequently used options with the Git Clean command. The use of these options is summarized below.

-n or --dry-run will output the names of the files that will be removed. It will not remove or delete any files.
-f will remove or delete files. Always include this option with the Git Clean command.
-d is used to remove untracked directories in addition to the untracked files. If you wish to remove submodules, use the -f option twice.
-X will remove only ignored files.
-x will remove both ignored and un-ignored files.

In most cases, the following combination of the options gets the job done. It will delete all untracked files(ignored and un-ignored) and all untracked folders.

git clean -fdx