Stop spending more time resolving merge conflicts in .pbxproj

Praveen Kumar
Jan 23 · 3 min read

If you working in a large team and your team is working on a multiple new modules, then you know the pain of resolving conflicts in Xcode project file each time you add new files to your project. I have been through this many years and finally I came across a tool named XcodeGen, in this article will look how this tool is helpful resolving our problem.

A bit of background

Every Xcode project has settings file .pbxproj contains all of the metadata about your project that Xcode uses to build it; the settings, the file references, configuration, targeted platforms, etc... This file is very important to compile, build and archive your project. When ever you add new folders, files, modify project settings, build phases this file get modified. It’s quite possible to get conflicts in this file when you raise pull request. This file is not human friendly to read and resolve conflicts and length of the file is depend on size and complexity of your project. What normally I do is I will resolve conflicts with theirs and add my files and modifications again. But this is a tedious manual process, and error prone, even time consuming some times.

What XcodeGen will do to solve this problem

XcodeGen is a command line tool written in Swift that generates your Xcode project settings file using your folder structure and a project spec. So you can add your .pbxproj files to git ignore. So that no more merge conflicts on this file. But you need to run a command before you start compiling your project. Let’s deep dive into more information.

The project spec is a YAML or JSON file that defines your targets, configurations, schemes, custom build settings and many other options. In this article I used YAML format. All your source directories are automatically parsed and referenced appropriately while preserving your folder structure. Sensible defaults are used in many places, so you only need to customise what is needed. Very complex projects can also be defined using more advanced features.


First make sure you have Xcode 11 installed on your mac and then you can install XcodeGen using anyone of the below

Install using mint

Install using Homebrew

Swift package manager

How to use

Go to your project root directory and run this command

This will look for a project spec in the current directory named and generate an Xcode project settings file with the name defined in the spec.

Example for creating spec file

Create a single view application and name it as HelloWorld

Remove the .pbxproj file and create XcodeGen configuration file project.yml in same directory. In this case it’s simple and plain and it looks like this

Go to the same directory in terminal and execute the below

Now you can see that settings file created and try open and run your project it will be successful.

You can find below how to create more complex spec files.

Handling dependencies

You also include carthage binaries directly using this. If you are using CocoaPods you should run pod install after generating .pbxproj file.

It’s quite simple hope so this article helped you stop spending more time resolving conflicts in .pbxproj file.

Mac O’Clock

The best stories for Apple owners and enthusiasts

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store