Anatomy of Xcode Project files

iOS | Oct 18, 2016

I started developing iOS app again and I found myself struggling with all nitty-gritty aspects of Xcode environment. This will be a short guide to know things before you start the app development.

I will be taking project Falcon as demo and the content of it can be seen in below snapshot.

Project file snapshots
Falcon project file list
Xcode project explorer
Falcon project in Xcode project explorer

Key Concepts


It specify in detail how a product/binary is built. They include build settings, such as compiler and linker flags, and they define which files (source code and resources) actually belong to a product. When you build/run, you always select one specific target.

Each target have it's own setting

In above figure you can see that we have three targets.

  • Falcon
  • FalconTests
  • FalconUITests

All these three target will have different settings.


Now, it is very likely that we will have multiple targets and they will share common resources. So we will need to group them these related target and that is what a project is.

In above example Falcon is a project.


Guess, what is workspaces then? Workspaces contain and manage projects. All the directly included projects are on the same level and their targets can depend on each other. So let suppose if I add a new project

Another-Application is different project added to Falcon workspace


  • Most of the time project scope is sufficient.

Now you can easily figure out why CocoaPods uses workspaces. They manage third party libraries or projects for us.

Now let move on to Xcode files.

Xcode Files

All the Xcode file location is with respect to the root folder of the project.


Location: .xcodeproj/.pbxproj

PBXPROJ is an Xcode data file that saves all the project project data such as the list of source code, resource files, and build properties.

It is a critically important file.

The biggest challenge comes when you are working in a team and fix the merge conflict arising due to distribute changes. Unfortunately, there’s not much you can do except to make the changes manually.

The Xcode team has put a lot of effort into making the file merge-friendly. In managing several large projects via SVN, I’ve generally found that the merges are automatic and painless.

People have tried automating it but I wouldn’t not recommend until you check manually whether it is working fine or not.

Should I add it to .gitignore?



Location: .xcodeproj/xcuserdata/.xcuserdatad/xcschemes/.xcscheme

Instead of just ignoring the scheme file, you can ignore whole folder

# Exclude personal Xcode user settings

Should I add it to .gitignore?



Location: .xcworkspace/

A workspace is XML document which contains data of projects groups and other documents so you can work on them together. It can contain any number of Xcode projects, plus any other files you want to include. In addition to organizing all the files in each Xcode project, a workspace provides implicit and explicit relationships among the included projects and their targets. For example. The Falcon project workspace file looks like this.

<?xml version="1.0" encoding="UTF-8"?>
   version = "1.0">
      location = "group:Falcon.xcodeproj">
      location = "group:Pods/Pods.xcodeproj">

From above, it can inferred that workspace is trying to keep the reference for Falcon and Pods projects.

Should I add it to .gitignore?

NO and YES if you are not using CocoaPods

At last I will recommend to go through the official documentation to learn more about above files.

Let me know if above content helped you!


[1] Xcode Project File Format.

This content is open source. Please help improve it.