Before looking at internal mechanics, let’s build a clear picture of why garbage collection exists at all, and what problem it’s specifically solving.

Every Git Object Is Permanent, By Default, Forever

To understand garbage collection, you first need to understand a foundational fact about how Git stores data: every commit, every version of every file, and every intermediate structure Git creates is stored as an individual, permanent object, and none of these objects are ever automatically deleted the moment they stop being needed. Amend a commit, and the original, now-superseded commit doesn’t vanish — it simply becomes harder to find, while its data continues sitting in storage. Delete a branch, as covered in earlier material on Git refs, and the commits that branch pointed to don’t disappear either, at least not right away. Left alone indefinitely, a genuinely active repository would accumulate an ever-growing pile of these orphaned, no-longer-referenced objects.

What “Garbage” Actually Means in This Context

In Git’s own precise terminology, an object becomes unreachable — informally, plain “garbage” — the moment nothing in the repository, no branch, no tag, no other ref, and nothing recorded in the reflog, leads back to it anymore through any chain of parent-commit or content references. An unreachable object isn’t inherently broken or invalid; it’s simply data nothing currently points to, sitting in storage, taking up space, without contributing anything a normal Git operation would ever encounter or need. Garbage collection is the process specifically responsible for finding this unreachable data and, under the right conditions, reclaiming the space it occupies.

Two Distinct Jobs Bundled Into One Process

It’s worth being precise that “garbage collection” in Git actually bundles together two related, but genuinely distinct, jobs. The first is compaction: taking many small, individually stored objects and repackaging them together into a single, far more efficient, compressed file. The second is pruning: actually removing objects that have become unreachable and have remained that way long enough to be considered safe to discard. Compaction happens far more frequently and aggressively than pruning, precisely because compaction never actually deletes any reachable data — it only reorganizes it more efficiently — while pruning is a genuinely destructive operation that Git approaches with deliberate caution.

Why Git Doesn’t Simply Delete Superseded Data Immediately

It’s worth pausing on why Git was designed this way in the first place, rather than simply removing an object the instant nothing points to it anymore. The answer connects directly to Git’s broader philosophy around safety and recoverability: nearly every operation that makes an object unreachable — amending a commit, rebasing, deleting a branch — is also an operation people occasionally perform by mistake, or later regret. If unreachable data vanished the moment it lost its last reference, a huge category of routine, everyday mistakes would become instantly, permanently unrecoverable. By deliberately separating “no longer referenced” from “actually deleted,” Git buys itself, and everyone using it, a real, practical window in which an honest mistake can still be undone before it becomes permanent.

An Everyday Illustration of Objects Becoming Unreachable

Consider a developer who commits three times on a feature branch, then realizes the middle commit contains a mistake and decides to squash it into the first commit before pushing. That squash operation, familiar from earlier material on interactive rebase, creates brand-new commit objects representing the combined history, while the three original commits — still fully intact, still fully valid Git objects — simply stop being referenced by the branch, which now points at the newly created sequence instead. Nothing about this operation actually deletes anything directly; it simply changes what the branch ref points to, leaving the original three commits as immediate candidates for the unreachable classification this chapter has been describing.

Garbage collection touches several distinct storage structures inside Git, each playing a specific role in how objects are kept, compacted, or eventually removed.

Loose Objects: The Simplest, Least Efficient Form

Immediately after you create a commit, Git stores it, along with any new file content it introduced, as a set of individual files — one per object, each named after that object’s own content hash. These are called loose objects. They’re simple and quick to create, but genuinely inefficient at scale: each one carries its own small storage overhead, and storing many closely related versions of a file as entirely separate, individually compressed objects wastes significant space compared to storing just their differences from one another.

Packfiles: The Compact, Efficient Form

A packfile is a single, larger file that consolidates many objects together, storing most of them not as full, independent copies but as compact deltas — differences relative to a similar object already in the pack. This delta compression is often dramatically more space-efficient than loose objects, especially for a repository with a long history of many small, incremental changes to the same files. Garbage collection’s compaction step is primarily about taking a repository’s accumulated loose objects and folding them into packfiles like this.

The Reachability Graph as the Deciding Structure

At the center of the entire process sits Git’s reachability graph — conceptually, every commit connected to its parent commits, every commit connected to the tree and file content it represents, and every ref pointing at the starting commit of one of these chains. Garbage collection determines what to keep by starting at every current ref, including everything preserved in the reflog for its own grace period, and walking backward through this graph, marking everything it reaches along the way. Anything never touched during that walk is, by definition, unreachable, and becomes eligible for the pruning process covered fully in the Internal Working chapter.

GitHub’s Server-Side Architecture Around Repository Storage

Beyond what plain Git does on a single machine, GitHub operates its own large-scale storage infrastructure across millions of repositories simultaneously, layering additional operational tooling on top of standard Git’s own garbage collection mechanics — scheduling, load balancing across its own systems, and monitoring repository health at a scale far beyond what any individual developer’s local machine needs to consider. Understanding that GitHub’s own automation is built on the same underlying reachability and packing concepts described here, just orchestrated across a vastly larger, shared infrastructure, is key to understanding how the same core mechanism scales from a single laptop to one of the world’s largest hosting platforms.

Multi-Pack Indexes and Further Efficiency at Scale

As a repository accumulates many separate packfiles over time, even looking things up across all of them efficiently becomes its own small engineering problem worth solving directly. Modern Git supports maintaining a single, consolidated index spanning multiple packfiles at once, letting an object lookup check one unified structure rather than searching through each individual pack’s own index one at a time. This is a genuinely separate, complementary optimization on top of ordinary packing and compaction, aimed specifically at keeping lookup performance fast even once a repository’s history has grown large enough to be spread across many distinct packfiles rather than just one or two.

Commit-Graph Files as a Further Layer of Optimization

Alongside packfiles themselves, Git also supports maintaining a separate, specialized structure that precomputes and caches key facts about the commit history’s own shape — which commits are ancestors of which others, and how far back a given commit sits in the overall history. This structure exists specifically to speed up operations that would otherwise require repeatedly walking large portions of the commit graph directly, and its own upkeep is frequently folded into the same routine maintenance processes that handle ordinary compaction, reflecting a broader, ongoing pattern where Git’s maintenance tooling increasingly bundles several related, complementary optimizations together rather than treating each one as an entirely separate, manually managed concern.

Let’s open the hood and trace exactly what happens internally, step by step, when garbage collection actually runs.

Step One: Determining Reachability

Garbage collection begins by enumerating every current ref in the repository — every branch, every tag, HEAD, and anything else in the standard ref namespace covered in earlier material — along with every entry still within the reflog’s own retention window. From each of these starting points, Git walks backward through parent-commit links and content references, building a complete set of every object genuinely reachable from the repository’s current state. This walk is the computational heart of the entire process; everything that follows depends on having correctly and completely identified this reachable set first.

flowchart TD
    A["Enumerate all refs\n+ reflog entries"] --> B["Walk backward through\nparent and content links"]
    B --> C["Mark every object\nreached along the way"]
    C --> D{"Object marked\nreachable?"}
    D -->|Yes| E["Kept; eligible for\nrepacking into packfiles"]
    D -->|No| F["Unreachable; enters\ngrace period before pruning"]
    F --> G{"Grace period\nexpired?"}
    G -->|No| F
    G -->|Yes| H["Permanently removed\non next prune"]
    

Step Two: Repacking Reachable Objects

Once the reachable set is known, Git repackages this data into one or more new, more efficient packfiles, applying delta compression to shrink the overall storage footprint wherever similar objects allow it. Older packfiles, and any loose objects that were just consolidated, are then typically replaced by this new, more compact representation. This entire step deals exclusively with data already confirmed reachable, meaning it carries essentially zero risk of data loss — it’s purely a matter of storage efficiency, not survival.

Step Three: Handling the Unreachable Remainder

Objects that weren’t touched during the reachability walk are handled very differently from the reachable set. Rather than being deleted immediately, Git applies a configurable grace period — by default measured in weeks — during which an unreachable object remains in storage, untouched, specifically to protect against the possibility that some other, currently-in-progress operation might still need it, or that a person might realize a deletion was a mistake and want to recover the data through the reflog or another recovery mechanism covered in earlier material.

Step Four: Actual Pruning, Once the Grace Period Passes

Only once an unreachable object has remained unreachable continuously for longer than this configured grace period does a subsequent garbage collection run actually remove it permanently from storage. This is a deliberately conservative, two-stage design: becoming unreachable alone is never immediately fatal to an object’s survival, and only the combination of remaining unreachable and having aged past the grace threshold triggers genuine, permanent deletion.

Automatic Triggering Versus Explicit Invocation

Garbage collection doesn’t require a person to remember to run it manually on every occasion. Git tracks rough indicators of accumulated loose objects and packfile count, and when these cross an internally configured threshold, many everyday Git commands will automatically trigger a routine garbage collection pass in the background as a normal, expected side effect of ordinary use. A person can also explicitly request it directly at any time, including requesting a more thorough, aggressive pass that spends extra effort seeking out better compression than the routine automatic pass typically attempts.

These automatic thresholds are themselves configurable, giving a repository’s maintainers a degree of control over exactly how eagerly routine maintenance kicks in, without ever needing to touch the underlying reachability logic that determines what’s actually safe to compact or prune in the first place. A repository with unusually heavy, rapid commit activity might reasonably tune these thresholds to trigger more frequently, keeping loose-object buildup consistently modest, while a smaller, quieter repository can comfortably leave the defaults untouched, relying on the occasional automatic pass to keep things reasonably tidy without any deliberate, ongoing attention required.

How GitHub Automates This at Platform Scale

On GitHub’s own infrastructure, this entire process runs as part of the platform’s own automated repository maintenance, scheduled and managed by GitHub’s own systems rather than left to chance or to an individual user remembering to trigger it. Repositories hosted on GitHub benefit from this maintenance continuously in the background, without requiring any manual action from the repository’s own maintainers, ensuring even a very large, very active repository stays reasonably compact and efficient over its lifetime without anyone needing to think about it directly.

The Aggressive Mode and When It’s Actually Worth Using

Beyond the routine, lightweight garbage collection pass that everyday commands trigger automatically, Git also supports a more thorough, explicitly requested mode that spends considerably more computational effort searching for the best possible delta compression across the entire object set, rather than the faster, lighter heuristics the routine pass typically applies. This more exhaustive pass can meaningfully shrink a repository’s overall size beyond what routine maintenance alone achieves, but at a real cost in processing time, which scales with the repository’s total size — making it a reasonable, occasional choice for a repository that’s grown large and hasn’t had a thorough pass in a long while, but a poor choice to run routinely as a matter of habit on every ordinary maintenance cycle.

Concurrency and Safety During an Active Garbage Collection Run

Because garbage collection can run automatically as a side effect of ordinary commands, Git includes safeguards to prevent it from interfering with other operations happening at the same time, or with another garbage collection process that might already be running. A lock file mechanism ensures that if a garbage collection pass is already in progress, a second attempt triggered elsewhere simply defers rather than running concurrently and risking a corrupted, half-finished repacking operation. This kind of careful coordination is a small but important detail in making automatic, background maintenance safe to run without requiring a person to carefully time it around their own active work.

Let’s trace how an individual piece of data actually moves through this entire lifecycle, from creation through eventual, possible removal.

Why This Full Lifecycle Rarely Happens Quickly

It’s worth appreciating just how much deliberate delay is built into this entire chain — a ref losing track of a commit doesn’t remove anything immediately; the reflog then independently preserves it further; and even after both of these protections lapse, the grace period adds yet another, separate delay before anything is actually deleted. This layered, multi-stage design is intentional: genuine, permanent data loss through garbage collection is meant to be something that only happens after several independent safety margins have all been exhausted, never as the immediate, direct consequence of a single action like deleting a branch or rewriting a few commits.

How GitHub’s Own Lifecycle Interacts With What You See

On GitHub specifically, an important nuance is that GitHub’s own internal timelines for compaction, grace periods, and eventual pruning are managed entirely by GitHub’s own infrastructure and aren’t necessarily identical to the default timing plain, local Git applies on an individual developer’s machine. A commit that becomes unreachable on GitHub follows GitHub’s own internal maintenance schedule for eventual removal, which is generally more conservative and longer than what a typical local repository’s default settings would apply, precisely because GitHub is managing shared, valuable data at a much larger scale with correspondingly higher stakes for an accidental, premature deletion.

What Happens to a Fork’s Copy When the Original Repository Cleans Up

A detail worth understanding for anyone working with forked repositories is that garbage collection operates entirely independently within each separate copy of a repository’s data. If a commit becomes unreachable and is eventually pruned from an original repository’s own storage, that has no direct effect at all on a fork that already has its own independent copy of that same commit, as long as something in the fork’s own ref structure still keeps it reachable there. This is a natural, direct consequence of Git’s distributed design, covered in earlier material — every clone, including every fork, is a genuinely independent repository with its own entirely separate reachability graph and its own entirely separate garbage collection lifecycle.

Interaction With Shallow Clones and Partial History

Repositories cloned with a deliberately limited history depth, or with only a portion of the full file tree fetched, interact with garbage collection somewhat differently than a full, complete clone does, since such a clone never held the full history’s objects in the first place, and its own reachability graph is intentionally truncated at whatever boundary the shallow or partial clone was configured with. This distinction mostly matters for understanding why a shallow clone’s disk footprint looks so different from a full clone’s, rather than changing anything about the underlying principles of reachability and pruning covered throughout this article, which apply consistently within whatever scope of history a given clone actually holds.

Garbage collection delivers genuine, necessary benefits, but its cautious, delayed approach to deletion also carries real trade-offs worth understanding.

The Core Trade-off: Safety Versus Immediacy

The entire design of garbage collection reflects one consistent trade-off, chosen deliberately in favor of safety: every stage that could destroy data is delayed and layered with recovery opportunities, at the direct cost of not reclaiming storage space, or genuinely removing sensitive content, as quickly as a more aggressive, immediate approach might. For the overwhelming majority of everyday development work, this trade-off is clearly the right one — accidental data loss from an overly eager cleanup process would be far more costly, in both time and trust, than a somewhat larger repository sitting around for a few extra weeks before eventually being trimmed down.

It’s worth noting this trade-off isn’t unique to Git at all — it mirrors a pattern found throughout computing wherever a system has to balance the convenience of quick, reversible actions against the finality of genuinely permanent ones. A file deleted into a desktop trash folder, an email moved to an archive rather than permanently erased, a database record soft-deleted rather than physically removed — all of these follow the exact same underlying philosophy garbage collection applies to Git history: make the common, everyday case reversible by default, and reserve true, irreversible finality for a deliberate, separate, less frequently taken step.

Garbage collection’s deliberately cautious, delayed approach to deletion has real, direct security implications, particularly around sensitive data that was accidentally committed.

Why Deleting a Commit Doesn’t Immediately Remove a Leaked Secret

This is one of the most important, practically consequential facts in this entire article: rewriting history to remove a commit containing an accidentally exposed credential does not, by itself, mean that credential is genuinely gone from the repository’s storage. As covered in the Data Flow chapter, the old commit remains present, protected first by the reflog and then by garbage collection’s own grace period, for a meaningful stretch of time afterward — during which the data is still technically present and, depending on access controls, potentially recoverable by someone who knows exactly what to look for.

Forcing an Accelerated, More Aggressive Cleanup

For situations where genuinely urgent removal is required — a serious, confirmed credential leak, for instance — Git supports explicitly forcing an aggressive, expedited garbage collection pass that skips or shortens the normal grace period, immediately pruning unreachable objects rather than waiting for the standard delay to elapse. This is a deliberate, manual override of the default, cautious behavior, and it should be used specifically when the security cost of retained data outweighs the recovery benefit the grace period would otherwise provide — a judgment call, not something to reach for automatically on every routine cleanup.

GitHub’s Own Process for Genuinely Sensitive Removal Requests

Because GitHub manages storage across an enormous, shared infrastructure with its own internal replication and backup systems, a request to permanently and urgently remove specific sensitive data from a GitHub-hosted repository generally involves GitHub’s own support and security processes directly, rather than something achievable purely through ordinary Git commands run locally. This reflects the reality that data hosted on a large platform exists in more places, and with more operational safeguards around accidental loss, than a single local repository — meaning genuinely urgent, complete removal at that scale is deliberately a more involved, platform-mediated process than a simple local prune.

Unreachable Objects as a Forensic Resource, for Better and Worse

The same grace period that protects against accidental data loss can, in principle, also be examined deliberately — by someone investigating exactly what was removed and when, for legitimate incident-response or auditing purposes, or, in a worse scenario, by someone attempting to recover data that was genuinely intended to be gone. This dual nature is worth keeping in mind: the very feature that makes garbage collection forgiving of honest mistakes is the same feature that means “removed from the visible branch” is never, on its own, a sufficient security guarantee for anything genuinely sensitive.

Access Control as a Complementary, Independent Layer

It’s worth being clear, and stating plainly, that garbage collection’s grace period only ever matters to someone who already has some form of legitimate read access to the repository’s storage in the first place — it isn’t itself a mechanism for granting or restricting who can see anything at all. A private repository’s own access controls remain the primary, entirely independent line of defense determining who could even attempt to inspect unreachable, lingering data during its grace period at all, regardless of how that grace period is itself configured. This is precisely why the two concerns are genuinely separate and both matter: strong access controls limit who could possibly go looking, while credential rotation ensures that even someone who somehow did find the old, leaked data would gain nothing usable from it, since the underlying secret itself would already be invalid.

Why Public Repositories Deserve Extra Caution Here

The stakes around this entire topic are meaningfully higher for a public repository than a private one, since a public repository’s data, including anything briefly reachable during its grace period, is potentially visible to a far broader, less controllable audience, and automated scanning tools are known to actively watch public repositories specifically for exposed credentials, as covered in earlier material on repository secrets. For a public project, treating any accidentally committed sensitive value as needing the most urgent possible response — immediate rotation, followed by expedited cleanup rather than simply waiting on the standard schedule — is the more appropriate, cautious default, given how much less control a public repository’s maintainers have over who might be watching.

Because garbage collection runs largely automatically and quietly, deliberate observability is what lets a team actually understand a repository’s storage health rather than simply hoping it stays reasonable.

Inspecting a Repository’s Object Counts Directly

Git provides a direct way to inspect exactly how many loose objects and packed objects a local repository currently holds, along with a rough estimate of the space each category occupies. Checking this periodically on a repository that’s grown unexpectedly large is often the fastest way to understand whether the growth is coming from a large volume of loose objects awaiting routine compaction, or from an already-packed history that’s simply grown large through genuine, legitimate content over time.

You may likeWhat Is Concurrency Control in Workflows in GitHub?→

GitHub’s Own Repository Size Reporting

GitHub surfaces a repository’s overall size directly in its own interface, giving maintainers a straightforward, ongoing signal without needing to run any local inspection commands at all. Because this figure reflects GitHub’s own internal storage state, including its own maintenance schedule, it may not update instantly the moment a local cleanup action is taken, precisely because of the same delayed, grace-period-driven timeline for garbage collection covered throughout this article — a genuinely useful reason not to be alarmed by a size figure that seems slow to reflect a recent, deliberate cleanup effort.

sequenceDiagram
    participant Dev as Developer
    participant Local as Local Repository
    participant GH as GitHub Storage
    Dev->>Local: Rewrite history,\nremove large file
    Local->>Local: Old object becomes\nunreachable locally
    Dev->>GH: Force-push rewritten history
    GH->>GH: Old object becomes\nunreachable on GitHub too
    Note over GH: Grace period begins\non GitHub's own schedule
    GH->>GH: Scheduled maintenance\neventually prunes it
    GH-->>Dev: Reported repository size\neventually reflects the change
    

Tracking Growth Trends Over Time

Beyond a single point-in-time size figure, tracking how a repository’s overall size trends over successive months gives a far more actionable signal than any single snapshot alone. A steady, gradual increase roughly matching genuine development activity is expected and healthy; a sudden, sharp jump often points to a specific event worth investigating directly — a large binary file accidentally committed, an unusually large merge, or a burst of activity that’s worth understanding rather than simply accepting as an unexplained anomaly.

Auditing What Automated Maintenance Actually Did

For repositories under stricter operational or compliance requirements, some teams maintain their own explicit logging around when local, manual garbage collection or pruning operations were run, by whom, and with what specific options, treating it with the same seriousness as any other operation capable of permanently affecting stored history. This is generally more relevant for self-managed Git infrastructure than for GitHub-hosted repositories, where the platform’s own automated maintenance and its own internal operational logging already handle this layer of tracking on the team’s behalf.

Correlating Size Changes With Specific Development Events

A genuinely useful monitoring discipline is deliberately correlating a repository’s size trend against the team’s own known activity — a major dependency vendoring exercise, a large asset import, or a significant history-rewriting cleanup — rather than treating size purely as an abstract number disconnected from what people actually did. When a size change lines up clearly with a known, deliberate event, there’s usually nothing to investigate further; when it doesn’t line up with anything the team recognizes, that mismatch itself becomes the most useful, actionable signal that something worth understanding happened without anyone’s direct knowledge or intention.

Using Object Count Trends to Anticipate Maintenance Needs

Beyond overall size, tracking the raw count of loose, not-yet-compacted objects over time gives an early, practical signal for whether a repository’s automatic maintenance thresholds are actually keeping pace with its real, ongoing activity level. A repository with an unusually high and steadily climbing loose-object count, despite otherwise normal development activity, can indicate that routine automatic compaction isn’t triggering as often as the repository’s actual usage pattern would benefit from, a useful, concrete prompt to consider adjusting local maintenance settings or scheduling a more deliberate, manual compaction pass rather than waiting indefinitely for the default thresholds to eventually catch up on their own.

Teams and repository maintainers who manage storage health well tend to follow a consistent set of patterns, while a handful of recurring anti-patterns explain most avoidable repository-bloat problems.

Proven Patterns

Anti-patterns to Avoid

A distilled checklist for understanding and working alongside Git’s garbage collection confidently, rather than being surprised or confused by its behavior.

Best Practices

• Never treat history rewriting alone as sufficient for sensitive data removal. Always rotate the exposed credential immediately, regardless of cleanup timing.
• Keep large binary assets out of ordinary commit history. Use a dedicated large-file mechanism instead, where one is appropriate for the content involved.
• Let routine, automatic maintenance do its job. Reserve explicit, forced cleanup actions for genuinely unusual, deliberate situations rather than routine habit.
• Expect a delay between a cleanup action and a reduced reported size. A repository’s size figure, particularly on GitHub, reflects the platform’s own maintenance schedule, not the instant of your local action.
• Investigate unexpected size growth rather than ignoring it. A sudden jump usually has a specific, identifiable, and often avoidable cause.
• Understand the reachability model before forcing anything. Know what a forced, expedited prune will actually affect before running it, especially on shared, important history.

Common Mistakes

Seeing how real teams and platforms actually encounter and manage garbage collection makes its practical importance concrete.

In short, Git garbage collection is, at its heart, a careful, two-part housekeeping process: constantly, cheaply reorganizing still-needed data into a more efficient form, and only very cautiously, after a deliberate delay, actually removing data confirmed to be genuinely unreachable. That deliberate, layered caution is really the entire point — it protects an enormous amount of honest, everyday work, like a deleted branch or a rewritten commit, from becoming an irreversible mistake the instant it happens. Understanding this layered, patient design changes how you think about several everyday actions: deleting a branch, rewriting history, or removing a large file all stop looking like instant, absolute deletions, and start looking like what they actually are — the beginning of a longer, deliberately protective process that only concludes with genuine, permanent removal much later, and only once several independent safety margins have all been exhausted.

Perhaps the most practically useful habit this deeper understanding produces is a simple, reflexive question worth asking whenever a repository behaves unexpectedly around size, missing history, or the lingering presence of something you thought was gone: is this object still reachable, and if not, how long ago did it actually stop being referenced? Nearly every confusing situation involving a repository reluctant to shrink, or a removed secret that still somehow feels present, traces back to exactly this layered, deliberately cautious lifecycle rather than to anything genuinely broken. Once that becomes the default lens for investigating storage-related surprises, garbage collection stops feeling like an opaque, unpredictable background process, and starts feeling like exactly what it is — a patient, careful system doing precisely what it was designed to do.