How to use the git clean Command

The git clean command is used to remove untracked files from the local working directory, the folder on your local machine where your project resides. Files are “untracked” if they are present in your working directory but have not yet been added to the Git index. This means that Git doesn’t know or care about them, and they only live locally on your machine.

The clean command deletes these untracked files, making it especially useful after a build or compile process to ensure a clean working state.

This guide will cover the essentials and advanced usage of git clean, ensuring you can maintain a tidy and efficient development environment.

Basic usage of git clean

Warning: git clean is a potentially destructive operation, as it will permanently delete files from your working directory. Always make sure that you do not need the files you're about to remove.

• Preview changes with dry run: Before running git clean, it's a good practice to perform a “dry run” to first see which files would be removed, before actually deleting them.

To see all the untracked files that git clean would remove run the command with the --dry-run flag:

```
git clean --dry-run
```

Commonly Used Options and Flags

• Removing untracked files: To remove untracked files (not directories), you can use:

  git clean -f

  The -f flag stands for "force" and is required by git clean to confirm the operation.

• Cleaning directories recursively: To extend the cleanup to include directories as well as the subdirectories and files that reside within those directories, use the d option in conjunction with -f:

  git clean -fd

  This command recursively removes untracked files and directories from the working directory.

• Cleaning ignored files: Often, you might want to remove files that are ignored by Git. The x option does this:

  git clean -fx

  Use this with caution, as it will remove all ignored files, potentially including dependencies, user-specific project settings, build outputs, logs, and other artifacts that you might want to keep.

  For a list of all the files in your local project that Git is currently ignoring you can run:

  git status --ignored

  or like before, run the clean command with the dry run flag:

  git clean -fx --dry-run

  This will show you all of the ignored files that would be removed using git clean -fx.

• Recursive Clean: To clean ignored files recursively, you can simply combine d with the x flag. The git clean command is recursive by default when the d option is used.

Advanced usage and options

• Cleaning specific paths: To limit the cleanup to specific files or directories, you can specify paths as arguments:

  git clean -fd <path>

  This will recursively remove untracked files in the specified directory.

• Using patterns: You can also use patterns to match files or directories to clean:

  git clean -fd "<pattern>"

  For example if we ran git clean -fd "*.log" it would recursively remove all files ending with .log in the directory and subdirectories.

• Interactive clean: The interactive mode (i) allows you to selectively clean files by presenting a list from which you can choose from:

  git clean -fdi

  This will perform an interactive cleaning of untracked files and directories in your working directory, allowing you to select which files or directories to delete. The -f stands for force, -d includes directories in the operation, and -i initiates the interactive mode. Here’s an example of how the console output might look when you run this command:

  $ git clean -fdi Would remove the following items: build/ output.log temp-notes.txt *** Commands *** 1: clean 2: filter by pattern 3: select by numbers 4: ask each 5: quit 6: help What now>

  At this point, you’re prompted to choose an action. Here are the options you might take:

  • 1 (clean): This will immediately clean (delete) all listed items.

  • 2 (filter by pattern): Allows you to enter a pattern to limit the items shown.

  • 3 (select by numbers): Lets you specify items to clean by their listed numbers.

  • 4 (ask each): Git will prompt you for each item, asking if you want to clean it.

  • 5 (quit): Exits the interactive clean mode without deleting anything.

  • 6 (help): Displays a help message explaining each command.

  If you choose 4 (ask each), for instance, the output might proceed like this:

  `What now> 4 Remove build/? [y/N] y Remove output.log? [y/N] n Remove temp-notes.txt? [y/N] y

  Removing build/ Skipping output.log Removing temp-notes.txt`

  In this scenario, you’ve chosen to delete build/ and temp-notes.txt but keep output.log.

  Each file or directory is handled according to your response, ensuring that you have full control over what gets removed from your working directory. This interactive process helps prevent accidental deletion of important files.

Dealing with potential issues

• git clean not working: If git clean seems not to work, ensure you're using the force option (f). Git requires this flag to prevent accidental deletion of important files.

• git clean is not removing directories or files: Make sure you're including the d option for directories and x for ignored files. Specifying paths or using patterns can also help target specific items.

Precautions and safety measures

• Always use git clean -n to preview what will be removed.

• Consider using git stash to save changes temporarily before cleaning.

• Remember, git clean affects only untracked files. It won't modify tracked files or your staging area.

git clean vs. Other Git Commands

• git reset: Resets the staging area to match the last commit but does not affect untracked files.

• git checkout: Can be used to discard changes in the working directory but, like reset, does not remove untracked files.

For further information on the git clean command see the official git documentation.