Git Clean: Remove Untracked Files

Safely clean your working directory with git clean.

When working with Git, your project directory can become cluttered with files that are not tracked by version control—such as compiled binaries, logs, temporary files, or backup copies. Over time, these untracked files can pile up and make it hard to keep your workspace organized. Fortunately, Git provides a powerful and flexible command for this exact purpose: git clean.

In this article, we'll explore what git clean does, how to use it safely, and some best practices to keep your workspace tidy and productive.

What Are Untracked Files?

Before we dive into git clean, let's clarify what untracked files are. In Git, your working directory can contain:

  • Tracked files: Files that are already being managed by Git and are part of your commits.
  • Untracked files: Files that are not staged for commit and not present in the repository’s history. These might be newly created files, build artifacts, or other miscellaneous files.

You can see a list of your untracked files by running:

git status

You'll notice a section titled Untracked files: listing files and folders not included in your commits.

What Does git clean Do?

The git clean command is designed to remove untracked files and directories from your working directory. This makes it a valuable tool for getting rid of build artifacts, logs, or other temporary files without affecting any code tracked by Git.

Important: git clean does not remove tracked files, changes staged for commit, or changes in your index.

Basic Usage

The simplest way to use git clean is:

git clean -n

This will show you what would be removed, without actually deleting anything. The -n (or --dry-run) flag makes it safe to evaluate the potential impact.

To actually delete the files, use:

git clean -f

The -f (or --force) flag tells Git to forcefully delete the untracked files. Without -f, Git will refuse to do anything as a safety precaution.

Common Options

1. Remove Untracked Directories

By default, git clean only removes untracked files, not directories. To include directories, use -d:

git clean -fd

Or, to preview:

git clean -nd

2. Remove Only Ignored Files

Suppose you want to remove only the files that are listed in your .gitignore. You can use the -X flag:

git clean -fX
  • -X: Remove only ignored files.

Alternatively, to remove all untracked files, including ignored and not-ignored, use:

git clean -fx
  • -x: Remove all untracked files, including ignored ones.

3. Interactive Mode

For more control, use interactive mode:

git clean -i

This presents a menu where you can select files and directories to remove.

Typical Use Cases

Here are some common reasons to use git clean:

  • Before a fresh build: Clean up previous build results to prevent build system inconsistencies.
  • Removing temporary files: Wipe out .log, .tmp, and other workspace clutter.
  • Resetting your working directory: Combine with git reset --hard to get a truly clean slate.

Best Practices

  1. Always run a dry run. Use git clean -n to preview what will be deleted.

  2. Don’t use git clean -fx lightly. This can remove all untracked files, even those you may not intend to delete (including important configuration files or data intentionally untracked).

  3. Use .gitignore wisely. Files and directories you want Git to ignore permanently should be listed in .gitignore. This can minimize accidental deletion with git clean.

  4. Be careful with scripts. If you automate cleaning with scripts, confirm the flags used match your intentions.

Quick Reference Table

Command Description
git clean -n Preview files to be deleted (dry run)
git clean -f Delete untracked files
git clean -fd Delete untracked files and directories
git clean -fx Delete all untracked files (ignored + not ignored)
git clean -fX Delete only ignored files
git clean -i Run in interactive mode

Conclusion

When used thoughtfully, git clean is an invaluable tool for maintaining a clutter-free and organized working directory. Always preview changes before deleting files, and leverage .gitignore to avoid surprises. With these best practices, you can keep your development workflow smooth and efficient.

Happy Coding! 🚀

Back to All Articles