How the git clean command works

If a developer wants to remove untracked files from a git working tree, the easiest way to do it is with the git clean command.

The git clean command is heavily parameterized, so it won’t remove items such as the following:

• Historically tracked files.
• Files that are part of an existing commit.
• Files added to the index.
• New directories.
• Files listed in .gitignore.

A git clean requires force

Another git clean command limitation is that developers can’t use it unless they provide either the –force or –dry-run (-n) switch. (That’s two dashes on –force and –dry-run.)

If you issue a git clean command on its own, it fails and generates an error message similar to “no f’s given.”

Here’s the error message that results when you don’t use the force switch with the git clean command:

gme@ubuntu:~/git-clean-example$ git clean
fatal: clean.requireForce neither -i, -n, nor -f given; refusing to clean

Steps to delete untracked Git files

Follow these steps to properly delete and git clean untracked files in your local workspace:

1. Run git clean -n to see a dry run.
2. Run git clean -f to force untracked file deletion.
3. Use git clean -f -d to remove untracked directories.
4. Use git clean -f -x to remove untracked .gitignore files.
5. Add the -i switch to do an interactive git clean.

Example git clean commands

Because the clean operation permanently deletes files, Git wants you to first run the command with the -n option to force a dry run, like so:

gme@ubuntu:~/git-clean-example$ git clean -n
Would remove clean-cache.ini
Would remove clean-untracked.txt
Would remove clean-stash.html

If the files subject for deletion don’t cause any surprises, a developer can follow through with the git clean command by adding the –force switch (with two dashes):

gme@ubuntu:~/git-clean-example$ git clean --force
Removing clean-cache.ini
Removing clean-untracked.txt
Removing clean-stash.html

Remember that git clean only removes untracked files. To find out if a file is tracked or not, developers can issue the git status command from within the repository.

The git clean command only deletes certain files.

Remove untracked Git files

By default, git clean won’t touch directories or files listed in the .gitignore file.

However, the -d switch causes directories to be deleted, and the -x switch forces the deletion of ignored files. Here’s what that looks like:

gme@ubuntu:~/git-clean-example$ --force -x  -d
Would remove helloworld.class
Would remove new-directory/

Use git clean -fdx to remove ignored files and directories

Developers may see the above example truncated to simply git clean -fdx:

gme@ubuntu:~/git-clean-example$ -fdx
Would remove helloworld.class
Would remove new-directory/

The git clean vs stash commands

Developers should use the git clean command judiciously.

The whole point of a distributed version control system is to make sure you never lose changes. Deleting files before they’re ever tracked certainly runs contrary to the version control philosophy.

Instead of a git clean, developers might want to perform a git stash instead.

The git stash command allows developers to shelve changes temporarily and then pop or apply those changes back to the local worktree any time in the future.

The ability to git stash untracked files as well really makes it difficult to justify an aggressive git clean call.

Be careful when you use the git clean command to remove untracked Git files.