How to use Version Control since Xcode 9

Xcode 9 has introduced a few changes in regards to Version Control is now handled. If you’re looking for the once so proud Source Control – Configure menu option, you’ll find that it’s no longer there. Dang! Where has it gone, and how are we supposed to manage our projects now?

Turns out there is a new tab in town, next to the Project Navigator (File manager icon) in the left hand pane of Xcode 9, called the Source Control Navigator. Click on it to find a plethora of options:

And would you look at that: for the first time in a decade, we can actually manage Tags as well as Branches here! And we get to see all those commits and comments we’ve been making for years, all without having to use additional version control tools! It’s like Christmas has arrived early!

Here’s a WWDC video on how we’re meant to use the new features from now on. It certainly didn’t answer all the questions I had, so for that, read what I’ve learnt through experimentation further down.

How do we configure a (GitHub) Remote?

Apple have focussed on deep integration with, as well as GitHub Enterprise. At the heart of which is a GitHub account. We can now add our GitHub credentials under Xcode – Accounts.

This will allow us to search, use our avatar and email, even star repositories directly from the Xcode front page. Try it out by either restarting Xcode without any projects open, or choose Window – Welcome to Xcode, then select Checkout an existing project.

As soon as we do, we’ll see a list of our own GitHub projects, as well as those we’ve starred, ready to be cloned and worked on with a single click. Very nice indeed!

While all these features are nice additions, they do NOT address how we can configure exiting remotes with Xcode 9, nor do Apple tell us how this works.

How do we configure a NON-GitHub Remote then?

If a project that we’ve previously worked on already has a Git remote added, we can see it in the new Source Control navigator.

I would expect that right-clicking on said remote would reveal some further information, but alas it does not. Same goes for clicking that gear icon at the bottom of the Source Control navigator. This is either an oversight, or they don’t want us to use anything other than GitHub anymore (perhaps they’ve already bought the company, who knows).

To find out more about remote, we must use a command line tool. Displaying details on an attached remote to the project can be achieved by navigating to your project’s folder in a Terminal Session and typing git remote -v:

git remote -v
PRESLEY (fetch)
PRESLEY (push)

The -v switch stands for “verbose” and shows URL details. My remote is called PRESLEY, and I can use it for pulling and pushing (meaning I have read and write access). It also shows me that I’m using https rather than ssh (git supports both protocol, as it always did).

To add a different remote, we need to right-click on the top blue project icon in the Source Control Navigator and choose Add Existing Remote. Or, if we want to create a new remote for the project, chose Create on GitHub.

Note that only GitHub remotes can be created directly from Xcode 9.

How do we switch Branches?

Notice the obvious lack of the previous “switch to branch” option when we want to switch from another branch. The option is indeed still here, but the terminology has changed. Or rather, it has been updated with how it used to work in “plain git” for years.

See, on the command line, we always had to use the “git branch xyz” command, followed by the “git checkout xyz” command to actually switch to a different branch. So now in Xcode 9, we need to right-click on the desired branch and use the Checkout command.

This is the equivalent of using “switch to branch” in Xcode 8 and prior. It’ll grow on you, trust me.

How do we create Branches?

Just like before: right-click on the current branch, and select “Branch from…”

This will create a new Branch, and none of your changes will be committed to the current branch. That’s handy if we’ve been fiddling with code that we do not want to commit to the current branch.

Note that any changes we’ve made are not autistically committed to the new branch until we manually commit – we’re merely creating one, ready for the next commit. Don’t be concerned if the “m” icon does not immediately show up next to the file name after making a change either. Sometimes, Xcode needs a moment to communicate with git and update which file is in what state.

How do we create Tags?

Rejoice – we now have support for Tags in Xcode! And it only took a decade or so to implement. Better late than never, ey?

To create a new Tag, choose any commit, right-click on it and hit “Tag”.

How do folders work? How can we create them?

The “folders” under both Tags and Branches aren’t actually folders. Instead they’re a bit like the Groups you see in the File Inspector.

They’re easy to make when we create a new Tag or Branch, followed by a forward slash (for example, Releases/Version 2.0). Anything before the slash will become the “folder name”, and anything behind it will be the contents of a new “sub-folder”.

The idea is to keep related items grouped together, for example all your releases or beta versions or tests.

If something needs to go into another folder, simply right-click the commit and create a new Tag / Branch, prefixing it with your desired “folder title”. The commit will stay the same, so there’s no data-copying involved, but it will now show up in two places. Feel free to delete the one you no longer need.

In the above screenshot I’ve simply created another Tag (Releases/v1.7) from an existing Tag (v1.7) to keep all my releases organised. I don’t need two v1.7 Tags, so I could go ahead and delete the bottom one without losing anything.

Further Reading

Leave a Reply