What goes into your .gitignore if you're using CocoaPods?

Question

I've been doing iOS development for a couple of months now and just learned of the promising CocoaPods library for dependency management.

I tried it out on a personal project: added a dependency to Kiwi to my Podfile, ran pod install CocoaPodsTest.xcodeproj, and voila, it worked great.

The only thing I'm left wondering is: what do I check in, and what do I ignore for version control? It seems obvious that I want to check in the Podfile itself, and probably the .xcworkspace file as well; but do I ignore the Pods/ directory? Are there other files that will be generated down the road (when I add other dependencies) that I should also add to my .gitignore?

Answer 1

Personally I do not check in the Pods directory & contents. I can't say I spent long ages considering the implications but my reasoning is something like:

The Podfile refers to a specific tag or or commit of each dependency so the Pods themselves can be generated from the podfile, ergo they are more like an intermediate build product than a source and, hence, don't need version control in my project.

Answer 2

I commit my Pods directory. I don't agree that the Pods directory is a build artefact. In fact I'd say it most definitely isn't. It's part of your application source: it won't build without it!

It's easier to think of CocoaPods as a developer tool rather than a build tool. It doesn't build your project, it simply clones and installs your dependencies for you. It shouldn't be necessary to have CocoaPods installed to be able to simply build your project.

By making CocoaPods a dependency of your build, you now need to make sure it's available everywhere you might need to build your project...a team admin needs it, your CI server needs it. You should, as a rule, always be able to clone your source repository and build without any further effort.

Not committing your Pods directory also creates a massive headache if you frequently switch branches. Now you need to run pod install every time you switch branches to make sure your dependencies are correct. This might be less hassle as your dependencies stabilise but early in a project this is a massive time sink.

So, what do I ignore? Nothing. Podfile, the lock file and the Pods directory all get committed. Trust me, it will save you a lot of hassle. What are the cons? A slightly bigger repo? Not the end of the world.

Answer 3

I recommend to use the GitHub’s Objective-C gitignore. In detail, the best practices are:

• The Podfile must always be under source control.
• The Podfile.lock must always be under source control.
• The Workspace generated by CocoaPods should be kept under source control.
• Any Pod referenced with the :path option should be kept under source control.
• The ./Pods folder can be kept under source control.

For more information you can refer to the official guide.

source: I’m a member of the CocoaPods core team, like @alloy

---

Although the Pods folder is a build artifact there are reasons that you might consider while deciding wether to keep it under source control:

• CocoaPods is not a package manager so the original source of the library could be removed in future by the author.
• If the Pods folder is included in source control, it is not necessary to install CocoaPods to run the project as the checkout would suffice.
• CocoaPods is still work in progress and there are options which don’t always lead to the same result (for example the :head and the :git options currently are not using the commits stored in the Podfile.lock).
• There are less points of failure if you might resume work on a project after a medium/long amount of time.

Answer 4

.gitignore file

No answer actually offers a .gitignore, so here are two flavors.

---

Checking in the Pods directory (Benefits)

Xcode/iOS friendly git ignore, skipping Mac OS system files, Xcode, builds, other repositories and backups.

.gitignore:

# Mac OS X Finder
.DS_Store

# Private Keys
*.pem

# Xcode legacy
*.mode1
*.mode1v3
*.mode2v3
*.perspective
*.perspectivev3
*.pbxuser

# Xcode
xcuserdata/
project.xcworkspace/
DerivedData/

# build products
build/
*.[oa]

# repositories
.hg
.svn
CVS

# automatic backup files
*~.nib
*.swp
*~
*(Autosaved).rtfd/
Backup[ ]of[ ]*.pages/
Backup[ ]of[ ]*.key/
Backup[ ]of[ ]*.numbers/

---

Ignoring the Pods directory (Benefits)

.gitignore: (append to previous list)

# Cocoapods
Pods/

Whether or not you check in the Pods directory, the Podfile and Podfile.lock should always be kept under version control.

If Pods are not checked-in, your Podfile should probably request explicit version numbers for each Cocoapod. Cocoapods.org discussion here.

Answer 5

I generally work on app’s of clients. In that case I add the Pods directory to the repo as well, to ensure that at any given time any developer could do a checkout and build and run.

If it were an app of our own, I would probably exclude the Pods directory until I won’t be working on it for a while.

Actually, I must conclude I might not be the best person to answer your question, versus views of pure users :) I’ll tweet about this question from https://twitter.com/CocoaPodsOrg.

Answer 6

I check in everything. (Pods/ and Podfile.lock.)

I want to be able to clone the repository and know that everything will just work as it did last time I used the app.

I'd rather vendor things in than risk having different results that could be caused by a different version of the gem, or someone rewriting history in the Pod's repository, etc.

Answer 7

The answer for this is given directly in Cocoapod docs. You may look at "http://guides.cocoapods.org/using/using-cocoapods.html#should-i-ignore-the-pods-directory-in-source-control"

Whether or not you check in your Pods folder is up to you, as workflows vary from project to project. We recommend that you keep the Pods directory under source control, and don't add it to your .gitignore. But ultimately this decision is up to you:

Benefits of checking in the Pods directory

• After cloning the repo, the project can immediately build and run, even without having CocoaPods installed on the machine. There is no need to run pod install, and no Internet connection is necessary.
• The Pod artifacts (code/libraries) are always available, even if the source of a Pod (e.g. GitHub) were to go down.
• The Pod artifacts are guaranteed to be identical to those in the original installation after cloning the repo.

Benefits of ignoring the Pods directory

• The source control repo will be smaller and take up less space.

• As long as the sources (e.g. GitHub) for all Pods are available, CocoaPods is generally able to recreate the same installation. (Technically there is no guarantee that running pod install will fetch and recreate identical artifacts when not using a commit SHA in the Podfile. This is especially true when using zip files in the Podfile.)

• There won't be any conflicts to deal with when performing source control operations, such as merging branches with different Pod versions.

Whether or not you check in the Pods directory, the Podfile and Podfile.lock should always be kept under version control.

Answer 8

I'm in the camp of developers who do not check in libraries, assuming we have a good copy available in another location. So, in my .gitignore I include the following lines specific to CocoaPods:

Pods/
#Podfile.lock  # changed my mind on Podfile.lock

Then I make sure that we have a copy of the libraries in a safe location. Rather than (mis-)use a project's code repository to store dependencies (compiled or not) I think the best way to do this is to archive builds. If you use a CI server for your builds (such as Jenkins) you can permanently archive any builds that are important to you. If you do all your production builds in your local Xcode, make a habit of taking an archive of your project for any builds you need to keep. Something like: 1. Product --> Archive

1. Distribute... Submit to the iOS App Store / Save for Enterprise or Ad-hoc Deployment / what have you

2. Reveal your project folder in Finder

3. Right click and Compress "WhateverProject"

This provides an as-built image of the entire project, including the complete project and workspace settings used to build the app as well as binary distributions (such as Sparkle, proprietary SDKs such as TestFlight, etc.) whether or not they use CocoaPods.

Update: I've changed my mind on this and now do commit the Podfile.lock to source control. However, I still believe that the pods themselves are build artifacts and should be managed as such outside of source control, through another method such as your CI server or an archive process like I describe above.

Answer 9

I prefer committing Pods directory along with Podfile and Podfile.lock to make sure anyone in my team can checkout the source anytime and they don't have to worry about anything or do additional stuff to make it work.

This also helps in a scenario where you have fixed a bug inside one of the pods or modified some behaviour as per your needs but these changes will not be available on other machines if not committed.

And to ignore unnecessary directories:

xcuserdata/

Answer 10

I must say, I am a fan of committing Pods to the repository. Following a link already mentioned will give you a good .gitignore file to get up your Xcode projects for iOS to allow for Pods but also for you to easily exclude them if you so wish: https://github.com/github/gitignore/blob/master/Objective-C.gitignore

My reasoning for being a fan of adding Pods to the repository is for one fundamental reason which no one seems to be picking up on, what happens if a library which our project is so dependant upon is suddenly removed from the web?

• Maybe the host decides they no longer want to keep their GitHub account open What happens if the library is say several years old (like older than 5 years for example) there is a high risk the project may no longer be available at source
• Also another point, what happens if the URL to the repository changes? Lets say the person serving the Pod from their GitHub account, decides to represent themselves under a different handle - your Pods URLs are going to break.
• Finally another point. Say if you're a developer like me who does a lot of coding when on a flight between countries. I do a quick pull on the 'master' branch, do a pod install on that branch, while sitting in the airport and have myself all set for the upcoming 8 hour flight. I get 3 hours into my flight, and realise I need to switch to another branch.... 'DOH' - missing Pod information which is only available on the 'master' branch.

NB... please note the 'master' branch for development is just for examples, obviously 'master' branches in version control systems, should be kept clean and deployable/buildable at any time

I think from these, snapshots in your code repositories are certainly better than being strict on repository size. And as already mentioned, the podfile.lock file - while version controlled will give you a good history of your Pod versions.

At the end of the day, if you have a pressing deadline, a tight budget, time is of the essence - we need to be as resourceful as possible and not waste time on strict ideologies, and instead harness a set of tools to work together - to make our lives easier more efficient.

Answer 11

At the end is up to you the approach you take.

This is what Cocoapods team thinks about it:

Whether or not you check in your Pods folder is up to you, as workflows vary from project to project. We recommend that you keep the Pods directory under source control, and don't add it to your .gitignore. But ultimately this decision is up to you.

Personally I'd like to keep Pods out, as node_modules if I were using Node or bower_components if I were using Bower. This apply for almost any Dependency Manager out there, and is the philosophy behind git submodules aswell.

However there are sometimes that you might want to be really sure about the state-of-art of a certain dependency, that way you are carry own the dependency within your project. Of-course there are several drawbacks that apply if you do that, but concerns do not only apply to Cocoapods, those applies to any Dependency Manager out there.

Below there is a good pros/cons list made by Cocoapods team, and the full text of the quote mentioned previously.

Cocoapods team: Should I check the Pods directory into source control?

Answer 12

It depends, personally:

Why pods should be part of the repo (under source control) and should not be ignored

• The source is identical
• You can build it right away as is (even without the cocoapods)
• Even if a pod is deleted, we still have its copy (Yes, this can happen and it did. In an old project where you want just a small change you would need to implement a new library to be able to even build).
• pods.xcodeproj settings are part of the source control as well. This means e.g. if you have the project in swift 4, but some pods must be in swift 3.2 because they are not updated yet, these settings will be saved. Otherwise the one who cloned the repo would end up with errors.
• You can always delete pods from the project and run pod install, the opposite can not be done.
• Even the authors of the Cocoapods recommend it.

Some cons: larger repository, confusing diffs (mainly for team members), potentially more conflicts.

Answer 13

Pros of not checking in Pods/ to version control (in subjective order of importance):

0. Much easier to merge commits, and review code diffs. Merging is a common source of issues in a code base, and this allows you to focus only on things that are pertinent.
1. It's impossible for some random contributor to edit the dependencies themselves and check the changes in, which they should never do (and again would be hard to identify if the diff is massive). Editing dependencies is very bad practice because a future pod install could occlude the changes.
2. Discrepancies between the Podfile and the Pods/ directory are found quicker among teammates. If you check in Pods/ and, for example, update a version in the Podfile, but forget to run pod install or check in the changes to Pods/, you will have a much harder time noticing the source of the discrepancy. If Pods/ isn't checked in, you always need to run pod install anyway.
3. Smaller repo size. Having a smaller byte-footprint is nice, but that doesn't matter much in the grand scheme. More importantly: having more things in the repo also increases your cognitive load. There is no reason to have things in the repo that you shouldn't be looking at. Refer to documentation (the abstraction) to know how something works, not at code (the implementation).
4. Easier to discern how much someone contributes (since their lines of code contributed won't include dependencies they didn't write)
5. JAR files, .venv/ (virtual environments), and node_modules/ are never included in version control. If we were completely agnostic about the question, not checking in Pods would be the default based on precedent.

Cons of not checking in the Pods/

0. You must run pod install when switching branches, or reverting commits.
1. You can't run a project just by cloning the repository. You must install the pod tool, then run pod install.
2. You must have an internet connection to run pod install, and the source of the pods must be available.
3. If the owner of a dependency removes their package, you can't use it (though you shouldn't be using a deprecated dependency in the first place - this just forces you to have dependency hygiene earlier).

In summary, not including the Pods directory is a guardrail against more bad practices. Including the Pods directory makes running the project easier. I prefer the former over the latter. You won't need to debrief every new person on a project about "what not to do" if there is not a possibility for making certain mistakes in the first place. I also like the idea of having a separate version control for the Pods which alleviates the Cons.

Answer 14

To me, the biggest concern is future proofing your source. If you plan to have your project last for a while and CocoaPods ever goes away or the source of one of the pods goes down, you're completely out of luck if trying to build fresh from an archive.

This could be mitigated with periodic full source archivals.

Answer 15

Check in the Pods.

I think this should be a tenet of software development

• All builds must be reproducible
• The only way to ensure builds are reproducible is to be in control of all dependencies; checking in all dependencies is therefore a must.
• A new developer starting from scratch shall be able to check out your project and start working.

Why?

CocoaPods or any other external libraries might change which might break things. Or they might move, or be renamed, or be removed altogether. You can't rely on the internet to store things for you. Your laptop might have died and there is a critical bug in production that needs to be fixed. The main developer might get hit by a bus and his replacement has to start up in a hurry. And I wish that last one was a theoretical example but it actually happened at a startup I was with. RIP.

Now, realistically, you can't really check in ALL dependencies. You can't check in an image of the machine you used to create builds; you can't check in the exact version of the compiler. And so on. There are realistic limits. But check in all you can - not doing so just makes your life harder. And we don't want that.

Final word: Pods are not build artifacts. Build artifacts are what gets generated from your builds. Your build uses Pods, not generate them. I'm not even sure why this has to be debated.

Answer 16

TL;DR: when you track the Pods/ folder, the project is easier to pick up from. When you don't track it, it's easier to improve on when you work in a team.

Although the Cocoapods organization encourage us to track the Pods/ directory, they say it's up to the devs to decide whether or not to do it based on these pros and cons: http://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control

Personally, I usually track the Pods/ folder just for projects that I won’t be working on anymore for a while. That way any developer can quickly pick up from it and continue the work using the proper version of the cocoapods.

On the other hand, I think the commit history gets cleaner and its easier to merge the code and review another person's code when you are not tracking the Pods/ folder. I usually set the cocoapod library's version when I install it to make sure anyone can install the project using the same versions as I.

Also, when the Pods/ directory is being tracked all the devs have to use the same version of Cocoapods to prevent it from changing dozens of files every time we run pod install to add/remove a pod.

Bottom line: when you track the Pods/ folder, the project is easier to pick up from. When you don't track it, it's easier to improve on.

Answer 17

In theory, you should check in the Pods directory. In practice, it is not always going to work. Many pods well exceed the size limit of github files so if you are using github you are going to have issues checking in the Pods directory.

Answer 18

Seems like a good way to structure this really would be to have the "Pods" directory as a git submodule / separate project, here's why.

• Having pods in your project repo, when working with several developers, can cause VERY LARGE diffs in pull requests where it's nearly impossible to see the actual work that was changed by people (think several hundreds to thousands of files changed for libraries, and only a few changed in the actual project).

• I see the issue of not committing anything to git, as the person owning the library could take it down at any time and you're essentially SOL, this also solves that.

Answer 19

Whether or not you check in your Pods folder is up to you, as workflows vary from project to project. We recommend that you keep the Pods directory under source control, and don't add it to your .gitignore. But ultimately this decision is up to you:

Benefits of checking in the Pods directory

1. After cloning the repo, the project can immediately build and run, even without having CocoaPods installed on the machine. There is no need to run pod install, and no Internet connection is necessary.
2. The Pod artifacts (code/libraries) are always available, even if the source of a Pod (e.g. GitHub) were to go down.
3. The Pod artifacts are guaranteed to be identical to those in the original installation after cloning the repo.

Benefits of ignoring the Pods directory

1. The source control repo will be smaller and take up less space. As long as the sources (e.g. GitHub) for all Pods are available, CocoaPods is generally able to recreate the same installation.(Technically there is no guarantee that running pod install will fetch and recreate identical artifacts when not using a commit SHA in the Podfile. This is especially true when using zip files in the Podfile.)
2. There won't be any conflicts to deal with when performing source control operations, such as merging branches with different Pod versions. Whether or not you check in the Pods directory, the Podfile and Podfile.lock should always be kept under version control.