How to delete untracked Git files
The git clean command removes all untracked files from the Git working directory. Which untracked Git files to remove can be controlled through the git clean command’s three important flags or switches:
- The -f flag forces untracked files to be removed. Directories and ignored files are left alone.
- The -d flag forces will remove untracked git directories
- The -x flag removes untracked files that map to .gitignore entries
Remove untracked Git files with caution
Be 100% sure you are aware of the implications of issuing the git clean command and removing untracked files before issuing the command:
- Deleted untracked Git files cannot be recovered. The recycle bin is bypassed.
- The git clean command may delete important property or configuration files
- Always do a dry run first before you remove untracked Git files
- For maximum control, use the git clean interactive mode to identify exact files to delete
- Sometimes a git stash accomplishes a given use case better than a git clean
The git clean vs git reset or rebase commands
Sometimes when a developer wants to clean up their branch history or simplify their git commit history, they investigate the git clean command.
To clean branches, amend Git commits or sanitize a commit history, better options include:
- The git rebase command
- The git squash command
- The git stash command
- An aggressive Git garbage collection
This tutorial on how to clean branches and commit histories may be more helpful if simply cleaning up the local git repository is the goal.
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.
By being heavily parameterized, 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.
A git clean requires force
Another git clean command limitation is that developers can’t use it without providing either the –force or –dry-run (-n) switch. (Two dashes on –force and –dry-run)
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:
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:
- Run git clean -n to see a dry run;
- Run git clean -f to force untracked file deletion;
- Use git clean -f -d to remove untracked directories;
- Use git clean -f -x to remove untracked .gitignore files; and
- 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.
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 (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.
Remove untracked Git files
By default, git clean won’t touch directories or files listed in the .gitignore file.
However, the -d switch will cause directories to be deleted, and the -x switch will force the deletion of ignored files:
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 will often see the above example truncated to simply git clean -dfx:
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 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 to remove untracked Git files.