How to Permanently Remove Files from Git History (Without Breaking Your Repo)

Introduction

Sometimes you may need to remove sensitive data or large files from your Git history. This guide will walk you through two methods for permanently removing files from your Git history: BFG Repo-Cleaner and git-filter-repo. We'll also discuss safety considerations to help you perform these tasks without affecting your repository's integrity.

Method 1: Using BFG Repo-Cleaner

1. Step 1: Install BFG Repo-Cleaner

   BFG Repo-Cleaner requires Java. Make sure Java is installed on your system.

   Download BFG Repo-Cleaner from the official website.

2. Step 2: Clone Your Repository

   Clone your repository with the `--mirror` option to get a bare copy of the repository.

   git clone --mirror https://github.com/your-username/your-repo.git

3. Step 3: Run BFG Repo-Cleaner

   Run BFG Repo-Cleaner to remove the specified files. Replace `path/to/file` with the path of the file you want to remove.

   bfg --delete-files 'path/to/file' your-repo.git

   You can also remove files matching a pattern:

   bfg --delete-files '*.log' your-repo.git

4. Step 4: Clean and Repack the Repository

   After running BFG, you need to clean and repack the repository to finalize the changes.

   cd your-repo.git
   git reflog expire --expire=now --all && git gc --prune=now --aggressive

5. Step 5: Push Changes to

   Finally, push the changes to your remote repository.

   git push --force

Method 2: Using git-filter-repo

1. Step 1: Install git-filter-repo

   Install git-filter-repo by following the instructions in the official GitHub repository.

2. Step 2: Clone Your Repository

   Clone your repository without the `--mirror` option.

   git clone https://github.com/your-username/your-repo.git
   cd your-repo

3. Step 3: Run git-filter-repo

   Run git-filter-repo to remove the specified files. Replace `path/to/file` with the path of the file you want to remove.

   ggit filter-repo --path path/to/file --invert-paths

   You can also remove files matching a pattern:

   git filter-repo --path-glob '*.log' --invert-paths

4. Step 4: Push Changes to Remote

   Push the changes to your remote repository.

   git push --force

Safety Considerations

• Backup Your Repository: Always create a backup of your repository before performing history rewrites. You can create a backup by copying the repository or using `git clone --mirror`.
• Notify Your Team: Inform your team about the changes because rewriting history will change commit hashes. Everyone needs to re-clone the repository to avoid conflicts.
• Test in a Separate Branch: Before applying the changes to your main branch, test the process in a separate branch to ensure it works as expected.
• Review Changes: After running BFG or git-filter-repo, review the changes to ensure that only the intended files were removed.
• Force Push with Caution: Force pushing can overwrite history on the remote repository. Make sure you understand the implications and coordinate with your team.

By following this guide and taking the necessary precautions, you can safely and effectively remove files from your Git history.