Git clean allows you to undo changes in Git by removing untracked files from your working directory. Unlike other undo commands, git clean only works on untracked files.
Once you execute git clean, you can't undo it; git clean deletes the files from your working directory without an option to restore them. Make sure that you don't want these files anymore before running git clean.
As a reminder, untracked files are files that exist in your working directory but haven't been tracked in Git's index through git add.
Git Clean Practice
To give removing files using git clean a try, start a new empty Git repository. Then follow the steps outlined below:
- Create three files,
Test.txt,Test2.txt, andTest3.txtin your working directory - Run
git statusto see the status of the repo and verify that all three files are currently untracked
- Run the
git cleancommand to remove all untracked files from your working directory:
$ git clean
Whoops! That didn't work as expected. The files are still there and you'll receive an error:
$ fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean
Forcing the Git Clean Command
Luckily for us, Git is careful and doesn't want you to accidentally lose any of your progress. It is configured to not let you empty out your files by default, so you need to pass a force option -f for this command to work. This is a safety mechanism. For actually deleting the files, you'll need to pass the -f option. Otherwise, Git will not do it and instead show you the error you saw above.
Run a Git Clean Test Before Deleting
Let's take Git's warning seriously and not delete too quickly. Before deleting any files, it's generally better to check what Git is going to delete, just to make sure. git clean offers an option to do that by setting the -n flag in the command. This will tell you which files would be removed if you ran the command properly instead. Let's take a look:
$ git clean -n
Your output, considering the previous example, will look like below:
Would remove Test.txt
Would remove Test2.txt
Would remove Test3.txt
Okay, that looks like what you expected. So let's now actually run git clean with the -f flag:
$ git clean -f
The output you receive from this command looks like this:
Removing Test.txt
Removing Test2.txt
Removing Test3.txt
When you see that output, the files will have been removed from your working directory. Go ahead and check whether you can find them anywhere! Hint: you won't. Since git clean really obliterates your untracked files, make sure to use it only when you know what you're doing.
Git Clean Options
The git clean command can be used in different ways depending on the option flag you use it with. Let's look at each of them in more detail.
Force: -f or --force
The --force option initiates the deletion process of untracked files from your working directory:
$ git clean -f
Note: This command will not remove untracked folders and neither untracked files recorded in .gitignore.
You can pass a <path> value after the -f option to remove a specific file:
$ git clean -f <path>
Test: -n
The -n option will perform a test of git clean:
$ git clean -n
It will show you the untracked files that running the command would remove. The output will read as Would remove <file> rather than actually removing the file. It's a safety that can let you know beforehand if you missed any important file that you might have otherwise unknowingly deleted. It's best to use this command before actually deleting any files.
Directories: -d
You can use the -d option to remove untracked directories. By default, git clean will otherwise ignore directories.
Note: Running git clean -d without any other flag will fail with the same error as when you run git clean without any flag.
If you want to preview the untracked directories before deleting them, you will need to add the -n option as previously described:
$ git clean -dn
This command with both the -d and the -n flags will have the same effect as described in the part about the -n option, only that it will also include the untracked directories.
Finally, if you really want to delete untracked directories, you will need to add the -f flag:
$ git clean -df
Combining the -d option with the -f option will delete any untracked directories, including any untracked files.
Ignored Files: -x
The -x option used with the git clean command is used to remove ignored files:
$ git clean -x
Again, you will need to combine the -x option with -f for the deletion to actually take place. If you do, Git will remove all untracked files from the working directory, including any files that are ignored by Git.
Interactive Mode: -i
The command also includes an Interactive Mode that you can activate by passing the -i flag along with the command. Below, you will start your interactive session with the -d option so that it also includes your untracked directories. Run the command below in your working directory:
$ git clean -di
Doing so will open up a prompt on your command line that is now waiting for your input:
In the screenshot, you can see that there are some untracked files and untracked directories in this example folder. You can also see that you've entered into an interactive shell session. Now you have six options to choose from. Let's take a closer look at them:
6 - Help
You can type 6 or h to see the help option. This can show you what the other options are and how to use them. You can press enter to go back to the menu.
1 - Clean
You need to type 1 or c to choose the clean option. It will delete the selected untracked files and directories at once.
2 Filter
Type 2 or f to choose the Filter by pattern option. Doing so, the CLI will display an additional prompt that takes your input so you can filter the list of untracked files.
The prompt will show Input ignore patterns>>, and you can use patterns to exclude files and directories from the removal process. For example, using _.txt will prevent files ending with .txt from being deleted. After you are done, you can press Enter to go back to the menu.
3 - Select By Number
To choose the select by number option, type 3 or s. The interactive mode will show you the untracked files and directories with numbers next to them, and you can delete each one you want by selecting its number.
4 - Ask Each
The ask each option, type 4 or a, will iterate over each untracked file and display a y/N prompt asking whether you want to delete it. It will look like the image shown below:
5 - Quit
Type 5 or q to choose the quit option, which will end the interactive session.
As you can see, running git clean with the interactive mode can make your deletion process a little safer, because you can pick and choose which files to delete, and take it step-by-step.
Note: The interactive mode is a feature that comes with many Git commands. If you enjoy getting to know Git like this, read more about Interactive Staging.
To learn more about git clean, check out the Git Clean documentation.
Summary: What Does Git Clean Do?
- You can undo changes in Git using the
git cleancommand. git cleanremoves untracked files from your working directory.- Unlike other undo commands,
git cleanonly works on untracked files.
Git Clean Options
- Force: `-f` or `--force`
- Test: `-n`
- Directories: `-d`
- Ignored Files: `-x`
- Interactive Mode: `-i`
- 6: Help
- 1: Clean
- 2: Filter
- 3: Select By Number
- 4: Ask Each
- 5: Quit