Reduce Git Repository Size with git-filter-repo

Measure a bloated Git repository, find the large blobs still stored in history, and remove them with git-filter-repo on a disposable clone. When individual paths are not worth preserving, you can keep a recent commit window instead. Verify the smaller .git folder locally before you decide whether to publish rewritten history. To move selected paths into another repository while keeping their history, use move content from one Git repo to another instead of --invert-paths stripping.

A large working tree and a large Git history are different problems. Deleting a large file from the current version does not remove copies stored in older commits, so the repository can remain large and clones can stay slow. Replace REPO_URL and paths such as backups/ or path/to/large-file.zip with your own remote and file names.

Quick answer: why is my Git repository so large?

This tutorial focuses on the common case: large unwanted files remain in Git history and make clones and the .git object database larger than necessary.

Use this flow when you are not sure whether history rewriting is required:

┌──────────────────────────────┐
│ Git repository is too large  │
└──────────────┬───────────────┘
               ▼
┌────────────────────────────────────────┐
│ Measure .git and run --analyze first   │
└───────────────────┬────────────────────┘
                    ▼
┌────────────────────────────────────────┐
│ Are the large objects still reachable? │
└────────────┬───────────────────┬───────┘
           No│                   │Yes
             ▼                   ▼
┌─────────────────────┐  ┌─────────────────────────────┐
│ Repack with git gc  │  │ Must the large files stay?  │
└─────────────────────┘  └──────────┬───────────┬──────┘
                                 Yes│           │No
                                    ▼           ▼
                       ┌──────────────────┐  ┌──────────────────────────┐
                       │ Git LFS or object│  │ Know the unwanted paths? │
                       │ storage          │  └──┬────────────────┬──────┘
                       └──────────────────┘  Yes│                │No
                                                ▼                ▼
                                      ┌─────────────────┐  ┌───────────────────────┐
                                      │ git-filter-repo │  │ Keep recent commits?  │
                                      │ --invert-paths  │  └───┬─────────────┬─────┘
                                      └─────────────────┘   Yes│             │No
                                                               ▼             ▼
                                                   ┌────────────────────┐  ┌─────────────────┐
                                                   │ Baseline + recent  │  │ Current snapshot│
                                                   │ commit window      │  │ only            │
                                                   └────────────────────┘  └─────────────────┘

Check how large the repository is

Change into your repository, then measure the on-disk size of the object database:

du -sh .git

The df and du command reports human-readable totals for directories such as .git.

116M    .git

Check how many Git objects are stored and how much space the packed objects use:

git count-objects -vH

count: 0
size: 0 bytes
in-pack: 32
packs: 1
size-pack: 115.04 MiB
prune-packable: 0
garbage: 0
size-garbage: 0 bytes

du -sh .git shows filesystem usage. git count-objects -vH reports object counts and packed size inside Git. Local .git size is not always identical to the storage number shown by GitHub or GitLab.

Will git gc reduce the repository size?

git gc reclaims unreachable objects and improves packing. It cannot delete a large file that is still reachable from a branch or tag.

If large unwanted blobs are still referenced by old commits, rewrite history. If you already made objects unreachable, git gc may reclaim local disk space.

To show why git gc is not enough when large files are still reachable, run a normal garbage collection and measure again:

git gc

Measure .git again after garbage collection:

du -sh .git

In a test where .git was about 116M before git gc, it stayed at 116M because every large blob was still reachable. Repacking cannot remove reachable history. Do not treat git gc --aggressive or immediate pruning with --prune=now as the first fix for historical bloat. See the git prune command if you need to understand when immediate pruning is appropriate.

Find what is making the Git repository large

This cleanup uses git-filter-repo. Check that it is installed:

git filter-repo --version

If the command is missing, install it. On RHEL and Fedora, use dnf with sudo:

sudo dnf install git-filter-repo

On Debian and Ubuntu, use apt:

sudo apt update && sudo apt install git-filter-repo

On macOS with Homebrew:

brew install git-filter-repo

Run analysis on a fresh clone of REPO_URL. Analysis does not rewrite history:

git clone REPO_URL repo-cleanup

Change into the new clone before you analyze it:

cd repo-cleanup

Run analysis without rewriting history:

git filter-repo --analyze

Git writes reports under .git/filter-repo/analysis/. Useful files include:

• blob-shas-and-paths.txt — blob IDs, unpacked/packed sizes, and paths associated with each blob
• path-all-sizes.txt — paths ranked by accumulated size
• directories-all-sizes.txt and extensions-all-sizes.txt — directory and extension totals
• renames.txt — rename hints when a blob appears under multiple paths

A trimmed excerpt from blob-shas-and-paths.txt might look like this:

  64c2e34f...   31457280   31466895 builds/release.iso
  9765d214...   26214400   26222415 backups/db-dump-v1.sql
  29d136f5...   26214400   26222415 backups/db-dump-v2.sql
  ee18d9fa...   20971520   20977935 [artifacts/archive.zip, builds/vendor-bundle.zip]
  c02091db...   15728640   15733455 builds/application.bin

The numeric columns show unpacked and packed size in bytes; the final column shows the path or paths associated with the blob.

Typical offenders are database dumps, ZIP archives, ISO images, generated binaries, and vendor artifacts committed by mistake.

Back up and coordinate before rewriting history

Rewriting history changes the commit IDs in the cleaned repository. Branches, tags, and commit or tag signatures can also be affected. After the rewrite is published, the safest option for collaborators is to delete their old clone and clone the repository again. Advanced users can rebase or reset existing work carefully, but they must not merge the old history into the rewritten history.

Work on a fresh disposable clone, not your everyday working copy. Keep a mirror backup until the cleanup is verified:

git clone --mirror REPO_URL repo-backup.git

Keep only recent Git history

Path filtering works when you know which unwanted files or directories caused the bloat. If you no longer need any old commit-by-commit history, you can instead keep a recent time window. The cleaned branch starts with one baseline snapshot, followed by the ordinary commits made after your cutoff date.

This method removes every older version, including deleted files whose old paths you may not know. It also keeps the first recent commit readable as a normal diff. Making the first recent commit a root commit would preserve the final files, but that commit would appear to add the entire repository.

Run these steps only in the disposable clone. Record the current branch tree before changing any commits:

ORIGINAL_TREE=$(git rev-parse main^{tree})

Choose the cutoff in ISO 8601 format. Include the offset so the boundary does not depend on the machine's local timezone:

CUTOFF='2026-01-01T00:00:00+00:00'

Find the oldest first-parent commit after the cutoff:

FIRST=$(git rev-list --first-parent --reverse --since="$CUTOFF" main | sed -n '1p')

Inspect that boundary before continuing:

git show --no-patch --format='%H%n%aI%n%s' "$FIRST"

Stop if FIRST is empty or names a commit you did not intend to retain. Once the boundary is correct, record its parent and the parent's tree:

PARENT=$(git rev-parse "${FIRST}^")

TREE=$(git rev-parse "${PARENT}^{tree}")

Create a root commit from that tree. This is the baseline immediately before the retained commits begin:

BASE=$(printf '%s\n' 'Repository baseline before retained history' | GIT_AUTHOR_DATE="$CUTOFF" GIT_COMMITTER_DATE="$CUTOFF" git commit-tree "$TREE")

Replay the cutoff window onto the new baseline:

git rebase --rebase-merges --committer-date-is-author-date --onto "$BASE" "$PARENT" main

Rebase stops if a retained commit conflicts. Resolve the conflict only when you understand why it occurred; otherwise abort with git rebase --abort and return to the disposable clone's original state.

Compare the final tree with the value recorded before the rewrite:

test "$(git rev-parse main^{tree})" = "$ORIGINAL_TREE"

A zero exit status means the current files, paths, modes, and blob contents are identical. Count what remains and inspect the rewritten boundary:

git rev-list --count main

git log --reverse --oneline main | sed -n '1,5p'

Only after the tree comparison and project tests pass should you expire the disposable clone's reflogs and repack it:

git reflog expire --expire=now --all

git gc --prune=now

This rewrites every retained commit ID because each commit ultimately points to the new baseline. Old commit links, signatures, pull-request diffs, and blame history before the cutoff no longer apply. Keep the mirror backup until the rewritten remote and a fresh clone have both passed verification.

Remove large files from Git history with git-filter-repo

All examples below assume you are inside a fresh disposable clone such as repo-cleanup.

Remove one file from every commit

--invert-paths means remove the listed paths instead of keeping only them:

git filter-repo --path path/to/large-file.zip --invert-paths

Remove a directory from history

Pass a trailing slash when you want every file under that directory removed:

git filter-repo --path backups/ --invert-paths

Remove multiple files or directories

List every path to drop in one command:

git filter-repo --path backups/ --path builds/release.iso --invert-paths

After removing backups/, builds/release.iso, and both historical names of a renamed vendor bundle, .git dropped from about 116M to about 16M in testing.

Remove every blob above a size limit

When many unrelated large files are present, you can remove blobs above a size threshold instead of listing every path:

git filter-repo --strip-blobs-bigger-than 50M

This is useful when many large files slipped into history, but it can remove blobs you did not review individually. Prefer explicit --path filters when you need precise control.

git-filter-repo removes the origin remote as a safety measure so you do not accidentally push rewritten history to the wrong place. That is expected.

If the large file was renamed or moved

git-filter-repo does not follow historical renames automatically. If analysis shows the same blob under two paths, include every historical name:

git filter-repo --path artifacts/archive.zip --path builds/vendor-bundle.zip --invert-paths

Review renames.txt and path-all-sizes.txt for older names or locations before filtering.

Verify the repository after filtering

Run analysis again after the rewrite:

git filter-repo --analyze

Measure size again:

du -sh .git

16M     .git

Check packed object totals after the rewrite:

git count-objects -vH

count: 0
size: 0 bytes
in-pack: 13
packs: 1
size-pack: 15.01 MiB

Confirm the unwanted paths no longer appear in reachable history:

git log --all --oneline -- backups/db-dump-v1.sql

An empty result confirms that the pathname no longer appears in the reachable history being checked. Also review the new --analyze reports to confirm the unwanted large blobs are no longer part of the rewritten history. For a path that had older names, check every historical pathname:

git log --all --oneline -- artifacts/archive.zip builds/vendor-bundle.zip

Confirm the current tree still contains every file the project needs, then run your build or tests. A smaller .git folder is not success if you deleted required artifacts.

Publish the rewritten history safely

Consider merging or closing open pull or merge requests before replacing history. Rewritten commit IDs can invalidate their diffs and comments, and provider-specific PR or MR refs may continue referencing the old history.

git-filter-repo removes origin on purpose. After local verification, re-add the remote you intend to replace:

git remote add origin REPO_URL

When you rewrote the branches and tags that should exist on the remote, push them back with force and prune refs that disappeared during filtering:

git push --force --branches --tags --prune origin

--force is required because existing remote refs still point at the old commit IDs. --prune removes destination refs covered by the push refspecs when their corresponding local refs no longer exist, so stale remote branches and tags are not left pointing to the old history.

If some protected refs reject the push while others succeed, the remote can be left with a mixture of old and rewritten history.

The required push strategy depends on which refs you rewrote. The command above fits the common case where you filtered the same branches and tags you plan to keep. It is not a universal recipe for every host or every cleanup.

GitHub

GitHub may take time to recalculate repository size after a force push. Forks, pull request refs, and cached objects can retain old data until GitHub garbage-collects them.

For comprehensive sensitive-data cleanup, GitHub's official procedure may use git push --force --mirror origin because that case aims to replace every writable ref. Protected or read-only refs can still reject the push and need provider-side handling. See GitHub: removing sensitive data from a repository.

GitLab

GitLab can retain objects behind internal refs even after you rewrite normal branches. Use GitLab's repository cleanup or purge workflows when storage metrics do not drop after a successful local rewrite. See GitLab: reducing repository size.

Hosting providers may keep internal refs that still reference old objects. A cleaned local clone and provider-reported repository storage are not always the same number immediately. Do not merge old history back into the rewritten default branch after the push.

When should you use Git LFS instead?

Use Git LFS when large binary files legitimately belong in the project but normal Git object storage is a poor fit. Examples include media assets, machine-learning models, and versioned binary deliverables.

Do not use LFS merely to hide accidental historical bloat. LFS storage is billed and managed separately from .git history. When migration to LFS is the actual goal, see git lfs migrate in the Git LFS documentation.

Removing secrets is a different problem

If you discover a password, token, or private key in history:

1. Revoke or rotate the secret immediately.
2. Remove or redact it from history.
3. Coordinate cleanup of forks, clones, and provider caches.

Deleting the file from Git does not make an exposed secret safe again. Follow your provider's incident guidance, such as GitHub: removing sensitive data.

Prevent the repository from growing again

• Add generated artifacts, dumps, and build output to .gitignore.
• Store backups and release binaries in artifact or package repositories.
• Use Git LFS only where large binaries truly belong in version control.
• Reject oversized blobs in CI, pre-commit, or pre-receive hooks.
• Run git filter-repo --analyze periodically on repositories that tend to accumulate binaries.
• When old history has no operational value, retain a dated baseline and a recent commit window instead of carrying every historical blob indefinitely.

Common problems

git-filter-repo vs BFG vs filter-branch

Final verification checklist

Before you rewrite history:

• A mirror or other recovery copy exists
• Collaborators know a force push or re-clone may be required
• Large objects and paths are identified, including renamed paths

After filtering:

• Unwanted paths no longer appear in git log --all -- <path>
• .git size and git count-objects -vH look reasonable
• The project still builds or tests cleanly
• Required branches and tags are handled on the remote
• Provider storage has been rechecked when the host still reports old size
• Future large artifacts are excluded or moved to LFS or artifact storage

Summary

Measure .git with du and git count-objects -vH, then use git filter-repo --analyze to find large reachable blobs. Remove known paths with --invert-paths, strip reviewed oversized blobs, or replace old ancestry with a baseline plus a recent commit window. Verify the current tree and the smaller repository locally before you re-add origin and coordinate a force push.

git gc alone cannot remove blobs that commits still reference. Git LFS, provider cleanup tools, and prevention rules handle different parts of the problem.

References

• git-filter-repo documentation
• git-filter-repo installation notes
• git-filter-repo FAQ
• git count-objects documentation
• git gc documentation
• Git LFS
• GitHub: removing sensitive data from a repository
• GitLab: reducing repository size