git clean | Delete untracked files in Git

Table of Contents

introduction

Occasionally Git users will encounter a situation where many files that are not needed to be tracked are inside a working directory of a Git repository.

This can occur if files were accidentally copied to the same location, if build file names and extensions are not included in the .gitignore file, or for a variety of other reasons.

Regardless of how they got there, Git provides a quick and easy command to delete all untracked files in one fell swoop.

In this article, we’ll explain how to use the git clean command to remove untracked files from your Git working directory.

What is the git clean command?

God git clean The command allows you to efficiently clean up untracked files in your Git repo. It comes with a variety of command line flags to help you clean up untraceable files using different methods and in different situations.

What is an untracked file in Git?

In Git, an untracked file is a file in your repo that Git doesn’t yet know about. This is because git add has not yet been used on this file. Additionally, files ignored in the .gitignore file are not normally tracked and Git will not report them when you run Git status.

The simplest way to list files without Git tracking is with the git status command:

$ git status
On branch main

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	newfile.txt

From the git status output you can see that the file newfile.txt Found in the “Untracked Files” section.

fatal: clean.requireForce defaults to true and neither -i, -n, nor -f is given; Refuses to clean

By default, if you’re just running git clean Alone in your repo without flags, you will get this fatal error message fatal: clean.requireForce defaults to true and neither -i, -n, nor -f is given; Refuses to clean:

$ git clean
fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean

This is because there is a default Git clean configuration called clean.requireForce which prevents Git from deleting untracked files without the user specifying additional flags for the git clean command.

This protects the user from accidentally deleting all their files without tracking if they are just checking git clean.

Git clean no files no trace

If there are no untracked files in your current directory (or your project’s working directory as a whole), Git clean will show no output at all.

Dry run with git clean -n

The safest way to use the git clean command is to start with a dry run. This will show you exactly which files Git will delete, without doing anything you might regret.

Let’s imagine we have a brand new repository with one new untracked file called newfile.txt.

You can perform a dry run of git clean using the git clean –dry-run or git clean -n flag:

$ git clean -n
Would remove newfile.txt

If we add a second untracked file, both will appear in the git clean output:

$ git clean -n
Would remove newfile.txt
Would remove newfile2.txt

If we use the git add command to add newfile.txt For the Git staging area, this is now a tracked file and will no longer appear in the git clean dry run output:

$ git clean -n
Would remove newfile2.txt

Force clean with git clean –force

Now that we know what Git will delete by using the –dry-run or -n flag, we can be sure that only the untracked file newfile2.txt Will be removed when cleaning up Git.

This can be done using the git clean –force or git clean -f flag:

$ git clean -f
Removing newfile2.txt

Be careful when force-cleaning Git files as it may not be so easy to retrieve the contents of an untracked file after it has been removed.

Is Git clean recursive?

By default, git clean is not recursive and will only remove untracked files in the current directory. However, the git clean -d flag can be used to make git clean recursive. In this case all subdirectories of your nested repo will be checked for untracked files.

If you don’t want to use the -d flag, you can browse into a specific directory and run git clean inside it to target files in that directory.

Another option is to explicitly specify the directory to be cleaned in the form:

$ git clean -n <path-to-directory-1> <path-to-directory-2>

Multiple directories can be cleaned at the same time as in the example above.

Interactive mode of Git clean with git clean -i

There is a cool option with Git clean that not many users are aware of – interactive mode.

Git clean’s interactive mode provides you with an optional command-line interface to specifically tell Git which untracked files to clean.

The interactive mode of Git clean is enabled using the git clean -i flag:

$ git clean -i
Would remove the following items:
  newfile.txt        newfile2.txt       test/newfile4.txt
*** Commands ***
    1: clean                2: filter by pattern    3: select by numbers    4: ask each             5: quit                 6: help
What now>

First, it lists the untracked files that Git can remove – not that interactive mode will recursively list all untracked files within nested subdirectories, even if -d The flag is not specified. Also, note that you don’t need to specify the power -f flag when running git clean interactively.

The prompt then presents six options to choose from:

1. Clean: Clean the listed untracked files
2. Filter by Pattern: Selectively ignore cleanup files that match certain patterns
3. Select by numbers: Select specific files to clean by name and number
4. Ask Anyone: Repeat through all untracked files and ask y/N if each one should be deleted
5. stop
6. help

You can type these numbers after the What now> Prompt and pressure to perform the specified action. We won’t go through all the operations here, but they are pretty self-explanatory. You can always use a dry run -n The flag together with the interactive flag -i until you get used to it.

Clean ignored files with git clean -x

By default, git clean will not touch any untracked files that are ignored in .gitignore file. However, you can change this by using the git clean -x flag:

$ git clean -x -i

This can be useful to quickly get rid of ignored build files that are contained in the .gitignore file and can be annoying to delete.

If you want to delete only untracked files, and no others, you can capitalize the X as follows:

$ git clean -X -i

Please note that we have provided the -i Mark as protection so you control exactly what gets deleted, however if you’ve done this a few times and know it’s safe, you can use -f Flag instead.

Does git clean delete files?

Yes, git clean deletes untracked files based on the flags provided when running the command. As mentioned, if no flags are provided git clean throws an error by default, and using the dry run -n flag will list files to be deleted without actually removing them.

Does git clean remove cache?

No git clean will not touch the repository. If you want to remove your hidden items, you can use git stash clear.

Can you cancel git clean?

For the most part, there is no good way to recover files that have been deleted without Git tracking. So you should be very careful when removing untracked content in general, as this is one of the few ways to lose work with Git.

Git clean config clean.requireForce

Git has many configuration settings that are initially set to sane default values ​​for user convenience or protection. Git stores local configuration settings in a file .git/config and user-level Git configurations in ~/.gitconfig file.

If you want to disable Git’s built-in protection for the git clean command, you can set to add the following settings adjustment to the git configuration file:

clean.requireForce = false

However, this is not recommended as it can lead to accidental file deletion – please be careful when changing the default clean.requireForce Git configuration.

How do I clean up Git?

So in conclusion, the Give a clean command Usually used by doing a dry run with -n flag, or simply using the interactive mode -i Flag immediately.

Once you’re sure that the resulting action, based on Git’s output, won’t accidentally remove anything unintended, you can restart Git clean with -f flag to actually perform the deletion.

We’ve covered various scenarios and command line options in this article, which should be all you need to get started with git clean command!

next steps

If you’re interested in learning more about how Git works under the hood, check out our Baby Git guide for developers, which dives into the Git code in an accessible way. We wrote it for developers who are curious to learn how Git works at the code level. To that end, we’ve documented the first version of Git’s code and discussed it in detail.

We hope you enjoyed this post! Feel free to email me at jacob@initialcommit.io with any questions or comments.

References

1. https://git-scm.com/docs/git-clean