How to deal with conflicts in Pod folders

Checking in your Pods folder is useful to get developers quickly onboarded to the project, and have builds that are consistently reproducible. However, it makes merge conflicts where two people update pods on separate branches a pain. Here's the technique I've been using for a while, and some background about how Cocoapods works.

Recognising the merge conflict of pods

Typically, when you get a merge conflict in pods, you will see conflicts in these files:

• Podfile.lock
• Pods/Manifest.lock
• Pods/Pods.xcodeproj

If these three files are showing as conflicted, you can use the steps below. If not, your merge conflict may not be related to your pods at all, and you should probably fix the merge conflict in your usual way.

Fixing the merge conflict

As the Podfile and Podfile.lock both keep the information about versions currently installed, you can safely delete the entire Pods/ folder. Fixing the conflicts in the Pods.xcodeproj file are only recommended if you really want to make your day worse. 😃

I’m not entirely sure what Pods/Manifest.lock is for, as it seems to be exactly the same as Podfile.lock. If someone knows, let me know!

Next open Podfile.lock. If you have both updated the same pod to different versions, you'll get merge conflicts in the upper part of the file — talk to whoever made the other change and decide which version you should be accepting (probably, the higher of the two versions). Otherwise, just accept the changes that make sense in this section.

The problematic conflict will be at the bottom of the file, at the line starting PODFILE CHECKSUM. Accept one of the checksums — it doesn't matter which, as we're going to have to regenerate the Podfile.lock anyway — and save the file. You can read more about why at the bottom of this article.

We’re nearly there! Simply run pod install (or bundle exec pod install if using bundler) to reinstall all the project's pods. This will regenerate the deleted Pods/ folder and create the correct checksum in Podfile.lock. That's it — you've now got both your changes merged, and you've fixed the merge conflict (at least, for the pods!).

Sum up, and short version

1. Delete the Pods/ folder
2. Fix conflicts in Podfile.lock, accepting either checksum
3. Run pod install (or bundle exec pod install if using bundler)
4. Commit your changes.

And that’s it! I hope this is useful for you and your team. I plan on writing more about these nitty-gritty details about working in a team, and if there are any things your team finds difficult you’d like to know more about, let me know on my Twitter. 👋

P.S. Why can we accept either checksum?

A checksum, or hash, is a string generated by inputting some data into algorithm, which generates a unique output for every different input. Importantly, if you put the same input in, it will always generate the same output.

For a hashing function f(x): f(a) is always equal to f(a) f(a) is never equal to f(b)

In CocoaPods’ case, the input is information about all the dependencies you have in the project. So using dependencies A, B, and C will generate a different checksum compared to using B, C, and D. Dependency A at version 1.0 will also generate a different checksum compared to version 1.1.

It doesn’t matter which checksum you accept, because neither contain the changes of the other — therefore both checksums are wrong. You will have to generate a new checksum containing all of the changes, which happens when you run pod install, after you've fixed all the conflicts.