Tutorial: Safely Reducing the Size of a Git Repository

Before starting any of these procedures, make sure to backup your repository.

Tutorial: Safely Reducing the Size of a Git Repository

Prerequisites:

• A local Git repository.
• Backup the repository before making changes.
• Optional: Install tools like BFG Repo-Cleaner.

Step 1: Basic Repository Cleanup

1.1. Run Git Garbage Collection
Start by running the Git built-in garbage collection command, which can help clean up unnecessary files and optimize the repository.

cd /path/to/your/repo
git gc --aggressive --prune=now

• --aggressive: More thorough cleanup.
• --prune=now: Removes objects that are no longer needed.

1.2. Clean Reflogs
Reflogs record when the tips of branches and other references were updated in the repo. They can consume space, especially in large projects.

git reflog expire --expire=now --all

Step 2: Identify and Remove Large Files

2.1. Find Large Files
Use a script to find large files in your repository’s history.

git rev-list --objects --all |
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' |
sort -n -k 3 |
tail -n 10

This command will list the top 10 largest objects in the repo.

2.2. Remove Large Files Using BFG
If you find large files that should not be in the repository, use BFG Repo-Cleaner, which is faster and simpler than git filter-branch.

First, download and run BFG:

java -jar bfg.jar --strip-blobs-bigger-than 100M /path/to/your/repo

2.3. Alternative: Use git filter-branch
If you prefer not to use BFG, you can manually remove large files with git filter-branch:

git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch PATH_TO_LARGE_FILE" \
  --prune-empty --tag-name-filter cat -- --all

Replace PATH_TO_LARGE_FILE with the path to the file you wish to remove.

Step 3: Clone the Repository Afresh

After cleaning up the history, it might be beneficial to clone the repository afresh to start with a new, smaller .git directory.

cd ..
git clone --mirror /path/to/old/repo new-repo
cd new-repo
git reflog expire --expire=now --all
git gc --aggressive --prune=now

Step 4: Replace Old Repository

Once you are satisfied with the new repository’s state, you can replace the old repository:

mv /path/to/old/repo /path/to/old/repo-old
mv new-repo /path/to/old/repo

Final Notes

• After performing these actions, especially if you changed the history, you will need to force-push to any remotes and inform collaborators to re-clone the repository.
• Always ensure you have backups and confirm that no critical data is lost during the cleanup.

This tutorial will guide you through reducing the size of your Git repository effectively and safely. Remember, these changes affect the repository’s history, which can impact collaborative workflows.