Merging Xcode project files Merging Xcode project files xcode xcode

Merging Xcode project files


  1. Break your projects up into smaller, more logical libraries/packages. Massive projects are regularly the sign of a bad design, like the object that does way too much or is way too large.

  2. Design for easy rebuilding -- this also helps if you're writing programs which must be built by multiple tools or IDEs. Many of my 'projects' can be reconstructed by adding one directory.

  3. Remove extraneous build phases. Example: I've removed the "Copy Headers" build phase from all projects. Explicitly include the specific files via the include directive.

  4. Use xcconfig files wherever possible. This also reduces the number of changes you must make when updating your builds. xcconfig files define a collection of build settings, and support #include. Of course, you then delete the (majority of) user defined settings from each project and target when you define the xcconfig to use.

  5. For target dependencies: create targets which perform logical operations, rather than physical operations. This is usually a shell script target or aggregate target. For example: "build dependencies", "run all unit tests", "build all", "clean all". then you do not have to maintain every dependency change every step of a way - it's like using references.

  6. Define a common "Source Tree" for your code, and a second for 3rd party sources.

  7. There are external build tools available. This may be an option for you (at least, for some of your targets).

At this point, a xcodeproj will be much simpler. It will require fewer changes, and be very easy to reconstruct. You can go much further with these concepts to further reduce the complexity of your projects and builds.


You might want to try https://github.com/simonwagner/mergepbx/

It is a script that will help you to merge Xcode project files correctly. Note that it is still alpha.

Disclaimer: I am the author of mergepbx.


The best way I have found is to instruct Git to treat the .pbxproj file as a binary. This prevents messy merges.

Add this to your .gitatributes file:

*.pbxproj -crlf -diff -merge