Efficiently Truncating Git Repository History Using Grafts and Filter-Branch

Introduction

In large-scale software development projects, Git repositories can accumulate extensive historical commits, such as over 19,500 commits, 500+ branches, and tags spanning several years. While this history aids in tracing code evolution, it increases repository size, impacting cloning, pushing, and daily operation efficiency. When teams decide to retain only history from a specific point (e.g., January 1, 2010) and archive earlier data, a reliable method is needed to truncate repository history while preserving branch and tag integrity. Based on core Git concepts, this article explores the combined use of grafts and git filter-branch, a widely accepted efficient approach, particularly suited for complex repository structures.

Core Mechanism: Grafts and Filter-Branch

Git's grafts mechanism allows temporary modification of commit parentage without rewriting commit objects. By specifying the SHA-1 hash of the new root commit in the .git/info/grafts file, its parent can be set to empty, hiding earlier history in log views. For example, if the target new root commit hash is 4a46bc886318679d8b15e05aea40b83ff6c3bd47, create a graft with:

echo "4a46bc886318679d8b15e05aea40b83ff6c3bd47" > .git/info/grafts

This takes effect immediately; checking with git log --decorate shows the commit marked as "grafted", with subsequent history intact but earlier commits no longer visible. However, grafts are temporary and do not permanently alter repository data. To solidify this change, run git filter-branch -- --all, which rewrites commit history across all branches and tags, making the new root commit the permanent starting point. After rewriting, all commit IDs change, so all collaborators must synchronize to the new repository to avoid merge conflicts. This process may be time-consuming; it is advisable to test on a copy first.

Operational Steps and Validation

Before truncation, always back up the original repository. First, identify the target new root commit, ensuring it is an ancestor of all branches to be retained. After creating the graft file, use git log or graphical tools to verify history truncation as expected. For instance, run git log --oneline --graph --all to visualize branch structures. Once confirmed, execute git filter-branch -- --all for permanence. Afterwards, remove the graft file and run git gc --prune=now to clean up unreferenced objects, reducing repository size. Note that old tags may still point to removed commits and require manual deletion or updating.

Comparison with Alternative Methods

As supplements, other methods like shallow cloning (git clone --depth) can quickly create history-limited copies but are unsuitable for modifying existing repositories. For example, git clone file:///path/to/repo --depth=10 clones only the last 10 commits, saving space but preventing full history pushes. Rebase methods (e.g., git rebase --onto) truncate by creating orphan branches and replaying commits, but may introduce conflicts requiring manual resolution. For instance, scripts use git checkout --orphan temp $1 to create a new branch, then rebase, but complex merge histories can cause errors. In contrast, the grafts approach is more direct, especially for multi-branch environments, as it handles all references at once.

Considerations and Best Practices

Truncating history is a destructive operation and must be handled with care. In team settings, communicate in advance and plan migration windows to avoid data loss. Use git fsck --unreachable to inspect objects slated for deletion, ensuring no critical data is affected. For Git versions, ensure 1.7.2.3 or higher to support relevant features. If the repository includes submodules or complex workflows, additional steps may be necessary. Overall, combining grafts and filter-branch offers a controlled way to optimize repository history, balancing performance and traceability needs.