Git Clean

The git clean is an undo command. It cleans the working directory by removing files that are not under version control.

The git clean command completes other commands like git checkout and git reset. However unlike the other commands it operates just on untracked files.

The untracked files are the files that have been created inside the working directory but have not yet been added to the staging area. The following example tells the difference between tracked and untracked files:

$ mkdir tracked_directory 
$ echo "tracked content text" >> ./tracked_directory/ttracked_file.txt
$ git add tracked_file.txt
$ mkdir untracked_directory 
$ echo "untracked content text" >> ./untracked_directory/untracked_file.txt
$ git status
On branch new_branch
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   tracked_file.txt

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

The above example use git status command, which shows the internal state of tracked and untracked modifications.

At this phase, if you run the git clean command, you will get a fatal error. The example above shows what the generated error looks like :

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

Git has a safety mechanism that is setup up globally to claim that git clean command to be passed "force" flag to execute.

Note: Be careful with the git clean command. Once executed, you cannot undo it. When it is executed, it deletes files permanently. Make certain to be sure that you really want to remove the untracked files before executing the command.

Git clean common usage and options

The git clean command has different usages using several options. The following sections show different git clean use cases.

Displaying files that will be deleted

The -n option will perform a tryout or a "dry run" of git clean. It will output which files are going to be deleted without removing them.

It's a good practice to try a dry run of git clean before executing the effective git clean command that will permanently remove files.

To use the -n option, run the following command:

$ git clean -n
Would remove untracked_file.txt

The above output shows which files are concerned about deletion when the effective git clean command is executed.

Note: It's highly recommended always to use the -n option of git clean command to see which files and directory will be impacted before running the effective deletion.

Initiating the deletion

The -f or --force option initiate the effective deletion of untracked files from the current directory, but it will not remove the untracked files or folders included in the .gitignore file.

The --force option is necessary for the deletion of untracked files unless the clean.requireForce configuration is set to false.

To use the -f option, run the following command:

$ git clean -f
Removing untraked_file.txt

The command above outputs the files that are deleted.

If you want to remove a specific file, the value can be passed with the -f option to the git clean command as follows:

$ git clean -f untracked_file_2.txt

Removing an untracked folder

The option -d indicates to the git clean command to delete any untracked directories. By default, the git clean command ignores directories during the deletion.

To use the -d option, run the following command:

$ git clean -dn 
Would remove untracked_directory/
$ git clean -df 
Removing untracked_directory/

In the above command, before running the forced clean, we executed a dry run using the -dn option combination to see which directories will be removed. The output of the forced clean displays the directories that have been removed.

Removing ignored files

The -x option tells the git clean command to include any ignored files. The -x option will work on all ignored files. It could be unintentional folders of files like ./.idea IDE configuration files. So it will be preferable to execute a dry run first, before the effective deletion.

To use the -x option, run the following command:

$ git clean -nx
$ git clean -xf 

The above command is a combination between -x and -f that deletes untracked from the current directory and ignored files.

Git clean interactive mode

The -i option is used to open the interactive mode of the git clean command. After initiating the interactive mode, it will show a 'what now>' prompt with 6 choices to select.

In the following example, we will use in addition to -i option, a -d option to include untracked directories.

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

The above command output a prompt and invite us to select one of the 6 choices. We will explain each choice.

1. Command 6 help: will explain 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 5 quit will exit the interactive mode

    What now> 5
    Bye.
   

3. Command 2 filter by patter will show a further prompt for filtering the untracked files list. In the following example, we will use the *.txt wildcard pattern, which will limit the untracked file list to just untracked_directory

    What now> 2
    untracked_directory/  untracked_file.txt
    Input ignore patterns>> *.txt
    untracked_directory/
   

4. Command 1 clean will remove the designated items.

    What now> 1
    Removing untracked_directory/
    Removing untracked_file.txt
   

5. Command 4 ask each will ask for each untracked item a confirmation to remove

    What now> 4
    Remove untracked_directory/ [y/N]? N
    Remove untracked_file.txt [y/N]? N
   

6. Command 3 select by numbers is like command 2. It will restrict the list of untracked items names using a corresponding number for each untracked item.

    What now> 3
      1: untracked_directory/    2: untracked_file.txt
    Select items to delete>>