Setting Up Xcode 5 Workspaces with Multiple Repositories
Saturday, December 28, 2013 at 7:10PM
Richard Warren in Multiple Working Copies, Source Control, Xcode 5


The WWDC 2013 session, Understanding Source Control in Xcode showed a really cool new feature. We could set up a workspace that contained a number of projects. Most of the time this would be an application and a number of static libraries. Each of these projects could have their own repository. Some might be hosted on a local OS X server. Others might be out on GitHub or other remote servers. It doesn't matter.

Xcode is supposed to be smart enough that when you check out the containing workspace, it recognizes these dependencies and can automatically download all the projects.

Unfortunately, there are two problems with this:

  1. Workspaces in the current version of Xcode 5 are badly broken. Specifically, if you create a workspace, and then create a project inside that workspace, Xcode will not create a git repository for that project, even if you ask for one.
  2. The Workspace itself must be under source control--however, there's no option to create a git repository when creating a workspace (only when creating projects). So, we must manually create the git repository.

The good news is, after a lot of trial and error, I've managed to find a way to set everything up by hand. Everything has to be set up just right, or it won't work. And, there are a number of steps that are easy to miss. However, once everything's in place, you can check out all the projects by simply checking out the workspace, as advertised.

Setting Up Our Projects

The first step is to set up all the individual projects. Each of these should be created as free-standing projects. Do not add them to any workspace yet. We'll take care of that later.

Additionally, each of the projects must be the working copy cloned from a remote repository. If you're using a project on GitHub, it's easy. You just clone a local copy of the repository. However, if you're creating a new project, things get a bit more complex.

Fortunately, if you have a Mac running OS X Server and the Xcode service on your local network, we can create projects directly on a remote repository with a local working copy. For complete details, please check out the Other Tools of the Trade bonus chapter from my book Creating iOS Apps: Develop and Design, Second Edition.

Setting Up Our Workspace

Once the project is setup and ready to go, we can create our workspace.

Now, we need to make sure that all the projects and the workspace are in separate directories. This isn't the way I typically organize my projects. Instead, I like to have a folder that contains both my workspace and all my project folders. Unfortunately that won't work. We need to place the workspace in its own folder. I recommend the following directory structure:

Once this is done, open the workspace and add our projects to the workspace. Then we need to quit Xcode. Simply closing the workspace won't be sufficient. We're going to manually create a repository for our workspace, and Xcode won't detect the new repository unless we actually quit and restart the entire application.

With Xcode shut down, open Terminal and navigate to our workspace's directory. Now, let's create a local get repository. Type the following commands:

bash$ git init
Initialized empty Git repository in /Users/rikiwarren/Develop/Sample Multiple Repository Project/Sample Workspace/.git/**
bash$ cat > .gitignore
bash$ git add .
bash$ git commit -m "Initial Commit"
[master (root-commit) 49b2e6d] Initial Commit
 2 files changed, 12 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Sample Workspace.xcworkspace/contents.xcworkspacedata

Note: Make sure you are only committing two files, .gitignore and your .xcworkspace file

Now, we need to create a remote repository for our workspace. Open Xcode again. Now, when you click on the Source Control menu, you should see the workspace repository, along with your project repositories. Select Source Control > Your Workspace > Configure Your Workspace.

In the Configuration Sheet select the Remotes tab, then click the + button and select Create New Remote. This will let you setup a remote repository, and it will make your local copy a working copy of that remote.

Configure The Project Repositories

Now, we need to configure the project repositories. Unfortunately, we need to quit and relaunch Xcode again before the options will be available.

For each project, select Source Control > Your Project > Configure Your Project. Then in the Configuration Sheet make sure the project is included as required during checkout.

Once this is done, commit and push these changes.

Note: We must commit and push the changes to our workspace's .xccheckout file. In my tests, Xcode did not always add this file to our repository. If it isn't being committed automatically, you may need to go back to the Terminal and add and commit it by hand.

That's it. We can now use Xcode's Check out an existing project command to clone the workspace and all our projects onto any other machine.

Hopefully much of this will be automated, and the bugs will be fixed in the next release.

Bug Reports

I have filed the following bug reports. Please feel free to file duplicates.

Article originally appeared on Freelance Mad Science Labs (
See website for complete article licensing information.