How to clean untracked files in Git

This guide will walk you through the process of cleaning all untracked files, including how to handle ignored files, specific directories, and more. Understanding how to use git clean will help you maintain a tidy repository by removing untracked files and directories that are not tracked as part of your version control.

What are untracked files?

Untracked files are those that exist on your local file system but have not yet been added to Git’s index. These files are not being tracked by Git, meaning any changes to them are not recorded in your repository’s history.

You can see which files are untracked in your local directory by running:

git status

This command will list all of the untracked files in your current repository.

Understanding git clean

git clean is a command used to remove untracked files from the working tree, the current collection of files and directories on your local machine.

It’s important to note that git clean only affects untracked files, meaning it does not modify files that have been added to the index or have been committed. This command leaves the repository's Git history untouched.

Basic usage of git clean

To start, here’s how you can use git clean to remove untracked files from your working tree:

1. Preview what will be removed: Before actually deleting files, it’s wise to see what will be cleaned. This can be done with:

   Terminal

   git clean -n
   
   

   The -n flag will initiate a dry run, and list all the files that would be removed if the command was executed without actually deleting them.

2. Remove untracked files:

After you have executed a dry run with the -n flag, you can delete all untracked files in your working directory, using:

git clean -f

The -f flag stands for "force," which will forcibly remove all of the untracked files in your repository.

Use with caution, as this operation is difficult to undo and should be considered permanent.

Extending functionality with additional options

• Cleaning directories: To remove untracked directories in addition to untracked files, you can include the -d option:

  Terminal

  git clean -fd
  
  

  This will remove any untracked directories in addition to the other untracked files in your repository.

• Handling ignored files: Normally, git clean will not remove files specified in .gitignore. To remove both ignored and untracked files, use the -x option:

  Terminal

  git clean -fx
  
  

  Alternatively, to remove only the ignored files while keeping the other untracked files, use the -X option:

  Terminal

  git clean -fX
  
  

More selective cleaning strategies

• Exclude specific files or directories: If you want to exclude certain files or directories from being removed, use the --exclude option:

  Terminal

  git clean -f --exclude="pattern"
  
  

  Replace "pattern" with the actual file pattern you wish to keep.

• Cleaning specific directories: To focus the cleaning process on a specific directory, navigate to that directory or specify its path:

  Terminal

  git clean -fd path/to/directory
  
  

  This will only remove the untracked files in the specified directory, leaving the rest of your repository untouched.

Safety and recovery

It’s important to understand that git clean is irreversible. Once you remove untracked files using this command, they are permanently deleted from your local system. To avoid accidental data loss:

• Always use git clean -n to preview what will be deleted.
• Consider committing or stashing changes you wish to keep before running git clean.
• Use the --exclude option to keep important files or directories.

git clean troubleshooting

If you find that git clean isn’t removing certain untracked files, it’s likely because they are either ignored or still marked as tracked by Git. Ensure that:

• The files are not listed in .gitignore or globally ignored. If you want to delete ignored files use the -x option.
• The files have not been included in previous commit histories. git clean only deletes untracked files, so if they have already been committed they will not be affected.

For further reading on cleaning untracked files see the official Git documentation.