Using Git Clean To Remove Unwanted Files

Git clean

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 -X option 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 -d option 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:

[email protected]:  /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:

Git clean interactive options

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”:

[email protected]:  /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.

[email protected]:  /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)
Let our Managed Hosting team configure your servers while you work on building your brand!
CM
Christopher Maiorana Content Writer II

Christopher Maiorana joined the InMotion community team in 2015 and regularly dispenses tips and tricks in the Support Center, Community Q&A, and the InMotion Hosting Blog.

More Articles by Christopher

Comments

It looks like this article doesn't have any comments yet - you can be the first. If you have any comments or questions, start the conversation!

Was this article helpful? Let us know!