CocoaPods documentation isn’t very opiniated, which can cause confusion for newcomers. Here are a few tricks I’ve picked up after building a few dozen projects with CocoaPods.

Source Control

Should you check in Podfile.lock? How about your *.xcworkspace and the Pods directory? Since all of these are automatically generated by running pod install, is it redundant to also include them in your source control?

Some CocoaPods maintainers recommend to check everything in.

My approach is to check in Podfile.lock but not xcworkspace and Pods. Here’s why:

Podfile.lock

Checking in Podfile.lock has the advantage of keeping track of the pod versions last used when working on the project. Also, if you run pod install and some pods have changed versions, you’ll see the change in your next commit, encouraging you to confirm that nothing broke.

Workspace

In most cases, checking in the *.xcworkspace to source control is unnecessary, since pod install will automatically generate it for you. There are rare cases in which you need to customize it, in which case you should check it in.

Pods Directory

Checking in the Pods directory is a contested issue. Checking it in allows full control of the pods and will ensure you review every change to your vendored code. Not checking it in will keep your code more decoupled from its dependencies and clean up your commit logs. I don’t do it because it ends up creating too many commit messages, especially if you’re using a library which is updated very often, like AFNetworking. Most dependency managers in other languages tend to not check in dependencies as well (i.e. npm & rubygems).

Finalizing a Project

If I’m going to stop working on a project for a while, or I’m handing it off to a client, I’ll create a branch with everything checked in. Podfile.lock, *.xcworkspace and Pods. This way, even if pods change over time, or they’re removed from github, or whatever happens, I’m sure to have a working version of my project.

Resources

No matter what strategy you choose to take for CocoaPods SCM, be aware of the pros/cons of each.

Here are a few resources to help you decide:

• Official CocoaPods .gitignore
• CocoaPods plugin to maintain pod integrity
• An interesting Twitter conversation about this article :)

Modifying Pods

Before modifying a pod, ask yourself if it’s necessary. Often, a category or subclass will do.

Pre-CocoaPods, when all vendored code was checked in, it was trivial to make small changes to 3rd party code. It’s still easy now, but not as obvious. There are many ways to make changes to Pods in your project:

1. Pull Request

If your modifications are useful to other users of the 3rd party library, then consider submitting a Pull Request. This way, everyone benefits. Hopefully it will be merged quickly.

2. Fork

Certain projects are notorious for taking a long time to merge PR’s (cough). In those cases or cases when your PR’s aren’t accepted, it can be useful to just point your Podfile to your fork of the project. Add this to your Podfile:

1

pod 'KIF', :git => 'https://github.com/ksuther/KIF'

The downside to this approach is that you have to keep your fork up to date, which is where the patchfile approach comes in.

3. Diffs

If your modifications are small, I’d encourage you to use patchfiles (*.diff) to apply them to your pods. This will apply your modifications every time you run pod install, with the added benefit of using the latest upstream updates. To see how it works, take a look at this github project: jpsim/pod-diffs.

Sidenote: patchfiles are super neat! Even if you modify code around your modification or the line numbers change, it’s smart enought to find it again!

4. Check it in

This is a last resort. If all other methods fail, check in your vendored code into your project outside of CocoaPods. Then, you’re free to modify it in any way you see fit. But then you need to update it manually when the upstream version changes.

Continuous Integration & Xcode Bots

There’s this misconception that using Xcode 5’s Bots feature for CI with CocoaPods projects means that you must check in your pods. In fact, Xcode Bots have the ability to run scripts prior to building your app. Check out this gist for a comprehensive guide to Bots and CocoaPods.

Thanks to @alloy, @aschndr, @ashfurrow & @swizzlr for their feedback while writing this article