Chris Dzombak

Including your Pods directory in source control

On my current project, we made the decision a month or so ago to add our Pods directory to git.

The team has seen a number of benefits from this decision. There are certainly some negatives, but in our experience the positives have been huge, immediately tangible, and well worth the price.

Why keep Pods under source control?

Isolation from others’ mistakes; a fully deterministic build

Our build process is now deterministic, no matter what other parties do.

This was the biggest factor that led to this decision. About a month ago, the Localytics podspecs all pointed to the same .zip archive, containing the most recent release. A new release of that library broke our build, and CocoaPods couldn’t restore the old version — ill-formed podspecs meant there was no old version to install.

Checking in the Pods directory means we’re relatively isolated from that issue, and our CI builds won’t suddenly start failing because of an issue like this.

It’s worth noting that it was easy to resolve this problem for all CocoaPods users after-the-fact. And I’ve started auditing the specs for pods we use much more closely after that incident.

Isolation from transient network failures

Before this change, we saw relatively frequent build failures on our CI server due entirely to transient network problems (or sometimes a DDOS against Github).

Our CI server now no longer needs to make tens of downloads from disparate sources for each build, and builds are much more reliable as a result.

No more pod install after changing branches or checking out old commits

With Pods stored in git, developers don’t need to remember to run pod install after checking out an old commit or a different branch.

This makes day-to-development easier, especially for team members who aren’t used to working with CocoaPods. It also makes offline development much less painful.

And perhaps most importantly, long sessions with git blame are way less annoying.

Easier for developers

It’s no secret that many developers aren’t fans of CocoaPods for one reason or another. This change means their day-to-day lives are more enjoyable. (And as a direct consequence I receive less ribbing, no matter how good-natured, in Campfire.)

What problems are there with keeping Pods under source control?

I expected this change to be more painful than it was. The only negatives I’ve noticed are, in this project, far outweighed by the very real benefits outlined above.

The only problem I can think of now is that there is some additional noise in Github; pull requests that include pod additions or upgrades are huge.

In practice, this is at worst a minor annoyance. Most pod additions — and nearly all upgrades — can take place in their own pull request. If they must be part of a larger PR, changes in Pods directory tend to be at the bottom of the diff view anyway. And if they’re not, it’s easy to scroll past them, or review the PR on a commit-by-commit basis.

That sounds more onerous than it really is. It’s a small price to pay.


Though I’ve long recommended against this practice, I now recommend that medium or large iOS teams keep the Pods directory in source control.

For tiny teams or one-person projects, I’m 50/50 — I really have to evaluate how important each of the benefits outlined above is. I have some personal projects that follow this advice, and some that don’t.

If you’re still interested, you should take a second to read the CocoaPods docs on this topic.