When working with any set of files, whether it is for programming, document writing, or otherwise, you may notice all sorts of extra files appear from time to time in your working directory, or you may need to temporarily create additional files for some specific purpose. Sometimes these are temporary auto-save files, ghost files created by your operating system, build files, log files, etc. And you don’t want these files getting mixed up with your critical project files. The easiest way to remove these extra files is to never bring them into Git in the first place. For this, you can use an “excludes” or “gitignore” file. But if these files are already created and you want to systematically remove them, Git clean is a great way to do it.
Git clean will literally clean your Git project, removing any files in your working directory that are not being tracked by Git. This means files you have added to Git will remain untouched but any additional files will be deleted. Of course, this command can be destructive, so this article will show you how to use the command safely and avoid any unintended data loss.
Useful Options
The following list of options is not exhaustive, but provides some helpful tweaks that may be useful in getting you the desired action:
-n, --dry-run- Dry run, show a list of files that would be removed but do not remove them.
-i,--interactive- Proceed with file deletion interactively. Go through each file individually and approve of deletions file by file.
-X- The
-Xoption will only delete files ignored by Git. This is a good way to keep any files you may have created manually. If you’re unsure what “ignored by Git” means check out our full guide on -d- By default, Git clean will not delete files from untracked directories. The
-doption will tell Git clean to apply recursively into untrack directories. (Note: this option can be nullified by providing a<path>to the command.
Your First Clean
The first time you run the git clean command you may trigger an error:
fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean
This means that your Git configuration has the “force” requirement set to true. In effect, this means you must use a force -f option to run a Git clean or update your configuration.
You can go ahead and use the force option to proceed with the clean:
git clean -f
Or, you can use the -i (interactive) or -n (dry run) options. (More on these options below.)
Alternatively, you can update your Git configuration file to set the force requirement to false:
[clean] requireForce = false
With the above variable you will be able to run git clean without triggering an error.
Git Clean Dry Run
Before you attempt to clean anything you might to a “dry” run, or test, just to see what would be cleaned if you were to proceed with the command.
git clean -n
And you would get an output similar to the one below:
chris@server: /tmp/git-clean-test$ git clean -n Would remove garbage-file
The line “Would remove garbage-file” indicates that running a git clean would remove a file called “garbage-file”.
Interactively Select Files
Git clean also comes with an interactive mode that guides you through each file to make sure you don’t accidentally remove something you may need. If you want to check your files as a cautionary step before deleting anything then this is a good option for you.
git clean -i
You will see an interactive output that looks similar to this:
Clean a Specific Directory
Git clean can also operate on a specific directory. In this example, imagine you want to clean a directory called “scratch-files”:
chris@server: /tmp/git-clean-test$ git clean scratch-files/ Removing scratch-files/
Notice that Git removed the entire directory. Any untracked files in the upper level working directory would be untouched.
chris@server: /tmp/git-clean-test$ git status On branch master Untracked files: (use "git add <file>..." to include in what will be committed) garbage-file nothing added to commit but untracked files present (use "git add" to track)
