Git: A happy repository is a lightweight repository

Published on 05 August 2013 • Estimated reading time: 3 minutes

I have had the joy of working with some great teams and learning how they use Git, but I have also seen it misused. The number one issue I’ve helped teams resolve when using Git is what I call the Fat Repository. The fat repository—not to be confused with the funny & NSFW Fat Git Enterprises—is an especially easy trap to fall into for teams who have come from the client/server source control world (SVN, TFS, CVS, etc.). In their world, a fat repository isn’t harmful and may even be a good thing—but in the DVCS world, the fat repository is a major problem.

Fat Repository

A fat repository can have one or both of the following characteristics:

Characteristic One: Multi-tasked Repository

A multi-tasked repository is a single repository with multiple root folders, each for a different customer or project. This is common with internal-focused items. For example, a consulting company may develop a set of common libraries used across projects, storing them all in one repository for easy access. Another case: a department might have all its projects in a single repository.

Many developers—including myself—have multiple Visual Studio projects in one repository, which is fine unless those projects are unrelated from a delivery perspective. They’re often grouped only because they share a common organizational structure.

This is called a multi-tasked repository because a single repository handles multiple unrelated deliverables.

Characteristic Two: Multi-focused Repository

Even if a repository avoids the multi-tasked trap, it can still become fat when used to handle requirements beyond a single deliverable’s core code. A common example: including a documents folder or database backup folder in the code repository. While everything is technically related to software development, not everything contributes to building the code.

This is called a multi-focused repository because its focus splits between specs, backups, virtual machines, and code. I see this issue not just in repositories but also in tools like Dropbox, where a shared folder for one document syncs hundreds of unrelated files—backups, installers, and more—that no one needs.

Fat Repository – Summary

In short, a fat repository contains more than just the code needed for a single project or deliverable. A simple test: Is everything here vital to my deliverables? If not, it’s a fat repository.

Client/Server and the Fat Repository

In traditional client/server source control (SVN, TFS), fat repositories aren’t an issue—in fact, they’re common and even advantageous since there’s one place to find everything needed.

The key differences (compared to DVCS) are:

1. You work with a working set, not the full repo. Initially, you pull down only what you need, rather than the entire history.
2. In client/server systems, you can checkout a single subfolder or file without downloading the rest.

DVCS and the Fat Repository

DVCS tools like Mercurial and Git differ fundamentally from client/server systems:

• Repositories are cheap to create (git init is all it takes). No server admin is needed, so teams create many repositories—some temporary, others long-lived.
• When you clone a DVCS repo, you get everything: every folder, file, and all history—whether you need it or not.

This is where fat repositories cause pain: Multi-tasked or multi-focused repos force you to pull down unwanted content, slowing down development.

Issues a Fat Repository Causes

• Slow initial checkouts. Even if this is a one-time pain, it’s still frustrating. I once helped a team where each project was in a separate multi-focused repo. While working sets were small, senior devs floating between teams struggled—their repos were so large that most couldn’t keep more than two checked out at a time, even though their working sets were under 1 GB.
• Disk space waste. Developers (especially those with SSDs) care about space. DVCS repos include all history, meaning a 1 GB database backup checked in (then deleted) still occupies space for everyone.

Solution: The Lightweight Repository

For DVCS, the solution is simple:

1. Keep repos lightweight—check in only what’s needed. Use .gitignore and staging to control what’s committed.
2. Create many repositories. Have one for code, one for docs, one for artwork—teams can cherry-pick what they need.
3. Avoid the Law of the Instrument. Just because you can put everything in a repo doesn’t mean you should. Database backups? A file share or Dropbox may suffice. Word docs? Tools like SharePoint (or TFS’s built-in SharePoint integration) work better for versioning and search.

In short: A happy repository is a lightweight repository.