How to git clean untracked files example

Benefits of git clean & untracked files

Before we get too deep into this topic, I want to set the record straight.

This article is on the ‘git clean’ command, which is used to delete untracked files from the local working tree. Often, when DevOps professional talk about a ‘git clean’, they often want to squash commits and rebase master to a branch or a branch to master. However, if your focus is to remove untracked files with the ‘git clean’ command, you’ve come to the right place.

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 limitations

By default, the ‘git clean’ command won’t remove:

• historically tracked files;
• files that are part of an existing commit;
• files added to the index;
• new directories; and
• files listed in  .gitignore.

Another ‘git clean’ command limitation is that developers can’t use it without providing either the –force or –dry-run (-n) switch. If you issue a ‘git clean’ command on its own it will fail and generate an error message similar to “no f’s given.”

Here’s the error message that happens when the force switch isn’t used with the git clean command:

[email protected]:~/git-clean-example$ git clean
fatal: clean.requireForce neither -i, -n, nor -f given; refusing to clean

How to use the ‘git clean’ command:

Follow these steps to properly ‘git clean’ files:

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; and
5. Add the -i switch to do an interactive ‘git clean’.

‘Git clean’ examples

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

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

[email protected]:~/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 will only delete certain files.

‘Git clean’ untracked files

By default, ‘git clean’ won’t touch directories or files listed in the .gitignore file. But the -d switch will cause directories to be deleted, and the -x switch will force the deletion of ignored files:

[email protected]:~/git-clean-example$ --force -x  -d
Would remove helloworld.class
Would remove new-directory/

‘Git clean -fdx’

Developers will often see the above example truncated to simply ‘git clean -dfx’:

[email protected]:~/git-clean-example$ -fdx
Would remove helloworld.class
Would remove new-directory/

‘Git clean’ vs stash

Developers should use the git clean command judiciously. The whole point of a DVCS tool is to make sure you never lose changes, but deleting files before they’re ever tracked certainly goes contrary to the version control philosophy.

Instead of a 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.