Chris Hannah

Xcode

Using GitHub and Xcode Together #

It’s been just under a year since I published my article on how to connect an Xcode project to a GitHub repository. Since then, Xcode has kept being updated with new Source Control features, and the guide started to break. So I’ve decided to start fresh and show how you can quickly and easily use GitHub to track your Xcode project.

The Xcode used for this guide was version 10.1.

We will first go through initialising a Git repository, finding the Source Control features in Xcode, and then either link it to an existing GitHub remote, or create one directly inside Xcode.

Initialising a Git Repository

You will need to make sure your project is inside a Git repository. The easiest way is to check the “Create Git repository on my Mac” checkbox when first creating the project, but you can also use the git init command1 to create one inside the root folder.


Once your project is being tracked by Git, you will see your project in the Source Control pane on the left of Xcode. It’s the second icon from the left, and you can quickly access it using CMD + 2.

This shows any local branches, tags, and also any remote repositories you have set up, along with remote branches. So you’ll be able to use this pane, along with the Source Control option in the menu bar to manage your repository once it is set up.

Setting Up a Remote

From this stage you have two options, you can link this repository to an already existing remote you have set up, or you can use Xcode’s new tools to create a new one. Either option can be found by right-clicking on the Remotes folder.

I’ll go through both methods.

Using an Existing Remote

For this example, I created a blank repository on GitHub. Once a blank repository is created, they show you a few ways to initialise the repository. However the only thing you’ll need is the URL address inside the Quick setup section. For me, it’s https://github.com/chrishannah/Test-Existing-Remote.git .

So if you go back to Xcode, right click on Remotes, and select Add Existing Remote, a new window will appear from the top prompting for the location. You just need to paste in the URL you got from GitHub, and select Add.

Once you’ve done that, you should see the new remote appear in the Source Control pane, and you’ll be able to commit, push, pull, etc. from the menu bar in Xcode, along with the usual places.

Create New Remote

If you haven’t got a remote repository set up yet, this is the easiest way to do so, and you don’t even have to leave Xcode.

Like before, go back to the Source Control pane, right-click on Remotes, and select Create “Project Name” Remote. You’ll then be presented with a window where you can customise the new repository you will be creating.

First of all, you’ll need to connect your GitHub account if you haven’t already. To do this just click on the Account drop down menu, tap Add, and then enter your GitHub credentials.

You can then enter a repository name, which will also dictate the URL, an optional description, the visibility of the project, and name you will call the remote in Xcode. The default options are usually fine, although you may want to make the repository private. The last field, remote name, can be left as the default “origin. This is just a label you can give to the remote repository, and if you used multiple, it would be helpful to distinguish each of them. Origin is just the conventional name that most developers use.

Xcode will then create the repost on GitHub, and push your code. You should then see the new remote appear in the Source Control pane, and you’ll be able to commit, push, pull, etc. from the menu bar in Xcode.

You’ll also find your code on the remote repository on GitHub.

I hope you found this guide helpful. If not, then please let me know either in the comments below, or on Twitter where I’m @chrishannah.

  1. https://git-scm.com/docs/git-init ↩

Putting Your Xcode Project on GitHub the Easy Way #

Warning: This guide is now outdated since Xcode has changed a lot since it was first published. A new version of this guide, Using GitHub and Xcode Together, is available and is based upon Xcode 10.1.

Developers are always talking about whether to use Git from the command line, or via a GUI such as GitHub Desktop. Well, if you’re using Xcode, then there’s a much simpler method that’s already built-in! It’s called Xcode Source Control[1].

I’m just about to upload one of my projects to GitHub, so I thought I’d share the process. Especially as I’ve recently found it so much easier to use, because it’s right there in Xcode!

Step 1

The first step is to let Xcode create a Git repository on your Mac. It should be checked by default.

Step 2

Then you will need to create a new repository on GitHub. Give it a name, description, and make it Public/Private. But make sure you don’t select “Initialize this repository with a README”.


Then select “Create Repository”.

Step 3

Then you’ll be redirected to a page where you’ll be asked to set up your repository. You only need one thing from this page, and it’s the URL in the Quick Setup section.

In my case, this is https://github.com/chrishannah/CH-Work-Item.git.

Step 4

Now it’s time to add this into Xcode.

Simply select Source Control from the menu bar, your project name, and then select the “Configure project” option.

Once you’ve done that, the next step is to select the “Remotes” tab, then select the + button in the bottom-left corner, and select “Add Remote”.

Here you will need to give it a name, and an address. The address is the URL previously found on the GitHub set up page. Then press “Add Remote”.

Step 5

The repository has now been created on GitHub, and added to Xcode, the next step is to initialise the repository.

Again, from the menu bar, select Source Control, and then Commit.

A window will appear with all the changes to the repository, since this hasn’t been initialised yet, it will show all of your projects files.

Simply add a commit message, select “Push to remote”, which should automatically select your GitHub repository, and press “Commit X Files and Push”.


If you haven’t connected your GitHub to Xcode before, you will be prompted for a username and password, these are your GitHub details.

That’s It!

Once you’ve completed all of the previous steps, your project should now be on GitHub, and if you go back to the repository on GitHub, it should now be populated.

If you haven’t already (like me above), it’s probably best to add a README file.

Managing Your Repository

From here it’s really easy to manage your repository in Xcode. It’s all found in the Source Control menu.

From there you can commit new files, push them to GitHub, pull any new changes, and anything else you’d expect from a Git client.

I hope that this guide proved useful, and provided a bit of piece of mind for you knowing that your project is now essentially backed up.

If you want to see the other tutorials I have here, then there is a Guide section.

You can find me on GitHub as chrishannah.

  1. For more information, there is a session from WWDC 2013, “Understanding Source Control in Xcode” that explains this in more detail ↩︎