Git clean

1. Description
2. Common options and usage
3. Interactive mode

Description

The git clean is an undo command, which completes other commands like git reset and git checkout. However, unlike the other commands that operate on files already added to the Git tracking index, the git clean command runs on untracked files. Untracked files are those created within the working directory but are not yet added to the tracking index. The example below shows the difference between tracked and untracked files:

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 then creates a test_tracked_file added to the Git index. Besides, an test_untracked_file is created, and an test_untracked_dir. The example then calls git status which displays output pointing on the internal state of tracked and untracked changes. The git clean command is executed to show its predetermined aim.

At this point, you should not execute the git clean command. The example below demonstrates what errors it may produce. Initially, Git is globally configured to require a "force" option to initiate for the git clean. Once executed, you cannot undo git clean. When it is fully executed, it will create a hard file system deletion. You should make sure that you really want to delete the untracked files before running it.

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.

-n

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

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.

-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 -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>
-d include directories

You can also use the -dn combination.

git clean -dn
#Would remove test_untracked_dir/

git clean -df
#Removing test_untracked_dir/

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

git clean -x

The -x option indicates git clean to also include ignored files. You have better 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

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 has an interactive mode that is activated while passing the -ioption. 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
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.

   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.

   1: clean

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

   2: filter by pattern

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

   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.

   3: select by numbers

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

   4: ask each
   
   *** 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.

   5: quit

7.