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.
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
Pods. Here’s why:
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.
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.
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.
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.
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
- CocoaPods plugin to maintain pod integrity
- An interesting Twitter conversation about this article :)
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.
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
The downside to this approach is that you have to keep your fork up to date, which is where the patchfile approach comes in.
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