git clean

Description

The git clean command is used to remove untracked files from the working directory. Unlike git reset and git checkout, which operate on tracked or staged files, git clean specifically targets files that have not yet been added to the Git index. Untracked files are those created within the working directory but are not yet tracked. The example below shows the difference between tracked and untracked files:

git clean

mkdir test_directory
cd test_directory/
git init .
#Initialized empty Git repository in /Users/kev/code/test_directory/.git/
echo "tracked file" > ./test_tracked_file
git add ./test_tracked_file
echo "untracked" > ./test_untracked_file
mkdir ./test_untracked_dir && touch ./test_untracked_dir/file
git status
#On branch master
#No commits yet
#Changes to be committed:
       # (use "git rm --cached <file>..." to unstage)
                 #new file: test_tracked_file
#Untracked files:
        # (use "git add <file>..." to include in what will be committed) 
                 #test_untracked_dir/ 
                 #test_untracked_file

As a result of the example above, you will have a new Git repository in the test_directory directory, which contains a test_tracked_file added to the Git index. Additionally, a test_untracked_file is created, along with a test_untracked_dir. The example then calls git status, which displays output showing the internal state of tracked and untracked changes. The git clean command is then used to remove these untracked files.

Do not run git clean yet. The example below demonstrates the error it produces by default. Git requires a force option to run git clean to prevent accidental data loss. Once executed, you cannot undo git clean. It performs a hard file system deletion. You should make sure that you really want to delete the untracked files before running it.

git clean error

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

Common options and usage

The git clean command has various usages with different options.

git clean -n

git clean -n

The -n option performs a dry run of git clean. It shows the files that are going to be removed, but doesn’t remove them.

git clean -n example

git clean -n
#Would remove test_untracked_file

As you can see, it says that the test_untracked_file will be removed when the git clean command is executed.

git clean -f

git clean -f or --force

The --force option is required unless the clean.requireForce configuration option is set to false. It deletes untracked files from the current directory, except the untracked folders or files specified with .gitignore.

git clean --force

git clean -f
#Removing test_untracked_file

The output shows that the test_untracked_file has been deleted. At this point, git status will show that the test_untracked_file has been deleted and cannot be found. By default, git clean -f will operate on all the untracked files within the current directory. Additionally, a <path> value can be passed with the -f option that will remove a specific file.

If you want to remove any untracked directory, you can use the -d option that tells git clean to do so, as by default it will ignore directories.

git clean -f <path>

git clean -f <path>

You can also use the -dn combination.

git clean -dn

git clean -dn
#Would remove test_untracked_dir/
git clean -df
#Removing test_untracked_dir/

It first shows that test_untracked_file is up for removal. Then we execute a forced clean and receive output that test_untracked_dir is removed.

git clean -x

git clean -x

The -x option indicates git clean to also include ignored files. You should execute a 'dry run' first, before the final deletion. The -x option will act on all ignored files. This could be unintended things like ./.idea IDE configuration files.

git clean -xf

git clean -xf

The -x option can be passed and composed with other options. The example above is a combination with -f that will delete untracked files from the current directory as well as any files that Git usually ignores.

Interactive mode

The git clean command has an interactive mode that is activated by passing the -i option. In the example below we also use the -d option, in order to act over the test_untracked_dir. After activating the interactive mode, it will display a What now> prompt. This prompt will demand to select a command to apply to the untracked files. These commands are 6.

git clean -di

git clean -di
Would remove the following items:
test_untracked_dir/ test_untracked_file
*** Commands ***
1: clean 2: filter by pattern 3: select by numbers 4: ask each 5: quit 6: help
What now>

We are going to look through each command below.

1. Command 6 will explain the other commands.

git clean steps

What now> 6
clean - start cleaning
filter by pattern - exclude items from deletion
select by numbers - select items to be deleted by numbers
ask each - confirm each deletion (like "rm -i")
quit - stop cleaning
help - this screen
? - help for prompt selection

2. Command 1 will delete the mentioned items.

git clean step 1, clean

git clean -di
What now> 1
clean

3. Selecting command 2 will show a further prompt for filtering the list of untracked files.

git clean filter by pattern

git clean -di
What now> 2

After choosing command 2, we will need the *_file wildcard pattern, which will restrict the untracked file list to test_untracked_dir.

git clean steps

Would remove the following items:
test_untracked_dir/ test_untracked_file
*** Commands ***
1: clean 2: filter by pattern 3: select by numbers 4: ask each 5: quit 6: help
What now> 2
test_untracked_dir/ test_untracked_file
Input ignore patterns>> *_file
test_untracked_dir/

4. Like command 2, command 3 is for refining the list of untracked file names. Selecting this command will prompt for numbers matching an untracked file name.

git clean select by numbers

git clean -di
What now> 3

5. Command 4 will run on each untracked file and show a Y/N prompt for confirming the deletion.

git clean ask each

git clean -di
What now> 4
*** Commands ***
1: clean 2: filter by pattern 3: select by numbers 4: ask each 5: quit 6: help
What now> 4
Remove test_untracked_dir/ [y/N]? N
Remove test_untracked_file [y/N]? N

6. Selecting command 5 will quit the interactive session.

git clean quit

git clean -di
What now> 5

Practice