source control workflow for workspace with subprojects?

This has been confusing for a long time. For example, see this thread in the old devforums archive:

devforums.apple.com/message/927709#927709

There used to be a bug where creating a workspace locally didn't create the local git repository (or perhaps it was when in creating a project in an existing workspace, I can't remember). I have to assume that this bug has been fixed, but I don't really know.

IIRC, the auto-clone behavior for dependent projects was added at a time when Apple had given up on selling the idea of freestanding workspaces. It seemed that the intended structure was for you to create a main project which — not being created within a workspace — instead contained an implict workspace. Then you would clone the dependent projects (already under source control — prototypically, by adding open source frameworks) into your main project as children or peers, which meant into the implicit workspace. Then, after you set the required/optional SCM options and pushed the main project to a remote repository, any subsequent clone of the remote repository would pull the main project first, then the additional projects listed as required in its implicit workspace.

Alternatively, it seems possible to start with a freestanding workspace separate from any projects. You have to make sure that it's under SCM locally, then push it to its own repository remotely. Then you can add any number of required projects already under SCM from different repositories to the workspace, and push the workspace again. Subsequent clones of the remote workspace would then pull clones of the required projects as well. It's basically the same scenario as above, except that there's an extra repository for the umbrella workspace, and the starting point is the workspace instead of a main project.

So, I think the reason it's not working for you is that you're trying to combine, into a single repository, multiple projects — and the umbrella workspace, by the sound of it — but they must be in separate repositories for Xcode automatic pull/clones to work.

To complicate this a bit further, I believe you can (that is, I have done in the past, but haven't tried recently) force multiple projects into a single remote repository, although you might have to apply a bit of crowbarring via the git command line to get started. However, to avoid pain, it's probably better just to accept what Xcode wants, which is one project per repository.

Again, I want to emphasize that I haven't tried to do anything clever since probably Xcode 5, so the behavior may have changed since the last time I looked at it.

P.S. The 2013 WWDC video is tantalizing, but there was a little bit of handwaving at the key moment, which obscured what was really happening. In addition, it looked like it was being done with a prelease version of Xcode, and the mechanism was slightly different by the time it was actually released. And of course it was never really documented, since the behavior is … ahem … obvious.

My advice is to not use Xcode for git repositories, use SourceTree or some other tool instead to manage the repository.