GitHub and the New Source Control Workflows in Xcode 9
Learn about the new tools in Xcode 9 for exploring the source control history of your projects. See how Xcode integrates with GitHub, and discover how the new source control navigator makes it easy to browse branches, tags, and detailed history and commit information.
Hello. Good afternoon. Welcome. My name's Kieron Seenya. I'm an Xcode engineer at Apple.
I'm really excited to share with you some of the new source control features of Xcode 9.
In fact, I'm so excited about it it's now a first class citizen of Xcode. Today you're going to learn about some of the great concepts of SCM and how they fit in with Xcode 9.
So let's get started. So I've got a lot of work to get done today.
The first thing I need to do is to get my project and to do that I need to clone it.
Next up I'm going to review some recent changes that happened in the project. So I'm going to look at some commits.
After that I've got some feature work I need to do. So I'm going to create a branch to make sure my changes aren't affecting the rest of my team.
And then I'm going to release my app to the App Store.
So I'll create a tag to make sure I know when that happened.
The first thing I need to do though is clone the project.
So let's take a look at what that is, if you're unfamiliar. In most cases you're going to have a single, centralized copy of your source code.
This is known as a remote repository. And this stores all the history of your projects and all the changes that make up that history.
And just like it sounds, cloning creates an exact copy of all the code and brings it down onto your MacBook and you can start working.
So how does this fit into Xcode 9? Well, with your GitHub account connected we've introduced an entirely new clone workflow.
When you've added your GitHub account you'll get a list of your personal repositories.
You'll also get a list of the starred ones and all of those belonging to your organization.
And it is really easy to find what you're looking for from here.
Immediately I can see all of my repositories.
There's also a detail pane at the bottom. So I can see more information about those repositories.
And from here I can even star an interesting repository. So I can come back to it later.
There's full search capability in here.
So using the address bar at the top, I can enter some search criteria and search across GitHub.
This saves you having to jump to GitHub to find the repository you're looking for.
So I go ahead and select this TOTP app, but I can also clone any other repository that's not part of GitHub by just entering the URL of it in that address bar there.
So when I've found what I'm looking for I hit the "clone" button and it asks me where I want to save it.
I choose here, click clone, and it just goes ahead and clones it. It's that simple.
Now in the mornings when I'm sipping my cup of earl gray I need to get access to my repository. I don't want to flip back to Xcodes to do that. I don't want to have to search for it.
So now we work closely with GitHub so you can clone your Xcode projects right from github.com.
You find the repo you're looking for, hit the clone or download button, and here you'll see an "open in Xcode" button.
It's really easy. It's really handy.
So that's cloning in Xcode 9.
So next up I want to review some changes that have happened recently.
So I'm going to look at some commits.
Now if you're unfamiliar let's take a look at this.
And this star represents a single commit.
It is a snapshot of all the changes that have happened in my project at that point in time.
Committing changes to a project is something you're probably going to do many times a day and each commit adds history to your project. And this history's invaluable for keeping track of your code base, knowing who is changing what and why.
Now every commit has an author.
This lets you know who to blame.
It also has a description so you know why that change happened.
There's also a date just to let you know when it happened. And finally something called a shar, which is the unique identifier for that commit.
It lets you reference it later on if you need to.
So, as this information, along with the changes captured by the commit, this makes up the rich history of your project. So how does this fit into Xcode 9? Well, we can see here.
In Xcode 9 there's entirely new feature set for source control allowing you to see your history.
On the left hand side we've introduced an entirely new navigator.
This'll list the working copies that are part of your project.
When you select one of those working copies you'll get this new history view.
This lists all of your commits and we've been using it in Xcode's code base.
We have around a quarter of a million commits and we can scroll through really smoothly. It's really great.
For each of these entries there is those details you saw before; the author, the description. This is really useful information, but with your GitHub account connected we now go and get your avatar.
So you can put a face to the name or the name to the face. So let's say I'm looking for a specific commit, something I know my colleague Eric [assumed spelling] committed recently and I'm not entirely sure what I'm looking for.
So we can now search by token.
So here I specify I'm looking for Eric.
Now that gives me a big list of commits. I still need to narrow it down a bit further. So let's find out what happened the last day because I know it was that recent.
So I use this scope bar and search for the last 24 hours.
I still got four results. I'm a bit lazy. I don't want to read through the commit messages.
So I know it has something to do with cofeeing.
So it narrows the result down to that individual result, and that's the one I was looking for.
And these search results come back instantly. It's really fast.
You've got to try it out.
So that's commit in Xcode 9.
So now that I've cloned my project and I've reviewed commit it's time I worked on something that's a bit risky maybe.
To do that I want to create a branch and this will help isolate my changes from the rest of the team's so they don't get affected. So let's go back to this commit docs we saw earlier. Now my master branch is in pretty good shape.
Everything's stable. My bot's passing their unit test. So I'm going to go ahead and create a branch from there.
So it goes to new navigator.
I hit "new branch" from master and Xcode goes ahead and just creates it.
Now my new branch is going to be pushed to the top of the list and marked as "current." This lets me know what I'm currently working on. It's really easy to see.
And you can see in this diagram here; history has now diverged. This means my commit is no longer part of master. So my changes aren't going to affect my team and they're going to carry on committing and they'll carry on committing and it won't affect me. And as I carry on committing it's not going to affect them. And this is a good place to be when you're working on some risky work.
So now my tests are passing on my feature branch and I want to land those changes back into the master branch.
So to do that I go to the new source control navigator, I hit the merge button and my changes have landed in.
The thing is though, those changes haven't been published to my service so the rest of the team can't see them.
So how does this tie in with Xcode's new navigator? Well, let's go back to that cloud illustration that we saw earlier.
And as I make changes and as others make changes we need to synchronize those changes.
And to do that you can pull changes from the remote repository. And when I've made my changes I'll go ahead and push those. And this is really useful when you're working in a team environment because you can carry on pushing and pulling to make sure you have each other's changes.
So after I've merged and I need to push those changes I have three commits I need to push and Xcode will automatically display these in the new navigator so I know my team can't see them.
And in Xcode 9 we automatically fetch from your remote repositories and this lets you know if your team have been making changes that you need to pull. And you'll see it with these up and down arrows.
This is good to know because you can't go ahead and push until you've pulled their changes in.
So that's branching in Xcode 9. So now I'm ready to release a beta version of my app.
The tests are passing, I've merged all my work into master.
So let's go back to those docs that we saw earlier.
At specific points of time in your project's history you'll want to create a tag. This lets you know all of the changes that made it up until that point in time.
It's a good idea to do this when you release your app to the App Store for example. So you -- to help you track what changes were made.
So we'll continue to do this and here I'm creating my Beta 4 tag and you'll continue to do this as you release more versions of your app to the App Store. So now on Xcode 9 we have full tagging support.
You can go to the new history view, click on one of your commits, and select "tag," and you'll see this new pane to create your tag.
Now based on the naming conventions of your tag, by using forward slashes, Xcode will automatically group your tags to help organize them easier.
This makes it easier to look them up later and in this case we're going to create a beta's group.
And when you create your tag it will immediately appear in the new history view so you can see that point in time.
If we flip open the "tags" folder you'll see those tags.
By selecting the Beta 4 tag here I see only the history of that tag.
And you might wonder; why is that useful? To see just the history of that tag? Well, it lets you find precisely what changes and features were introduced in a particular version of your app.
And by using the new searching and filtering capabilities you can find them easier.
So I've been told there was a bug introduced and it was in Beta 3.
So I go to the new navigator and I select the Beta 3 tag and I see here that only two changes were made since the last Beta. One was by Eric; one was by me. And this top one here, it's looking you know particularly sketchy and I'm not sure if it's something to do with the author. At this point they cease to become avatars and instead become mugshots. So I select this guy and I double click on him and I see this new view. Now you might be familiar with this view in previous versions of Xcode. It used to display as a sheet. The problem with that though was it blocked your workflow.
With this you can open a new tab, carry on working as usual. And with the rich assistance support, which Eric's going to show us later, we'll see how easy it is to review your changes in your code.
So here we can see there's a force that I wrote, which can crash the app of course.
This new editor is really great for other reasons too. For example there's full jumper support so you can navigate your files really quickly.
You can collapse that list of files for more screen space as well. And at the bottom you have that detail pane, just so you know you're looking at the right commit.
So that's the all new tagging experience in Xcode 9.
So combining the new, current experience the new source control navigator, and the great new workflows around branching and tags makes it easier than ever to get real work done with source control and Xcode 9.
So with that I'd like to introduce Eric to the stage to show us some of these new features.
Thank you very much, Kieran.
So as he said, I'm going to show you some of the new features of Xcode 9 and source control. So I've just set up this machine and I've installed Xcode 9 on it, but I don't have any of my projects yet. I want to clone them from GitHub and in order to do that I'm going to need to sign into my GitHub account. So I'll just go to Xcode's preferences and to the "accounts" pane.
And here we see of course I have no accounts.
So if I just go to the plus button in the lower left I get an option to add any account that Xcode supports, such as my Apple ID for doing provisioning and signing, Xcode Server for continuous integration, or GitHub for source control. And I want to take a moment here and point out that we also support GitHub Enterprise. So if your company uses a GitHub Enterprise server all the features that we're showing you that work with GitHub work just as well with GitHub Enterprise on your own company's server.
But for today, I'm just going to use github.com.
Great, so I'm going to sign in and copy my password. Make sure that goes in the password field. And I use two factor authentication.
And Xcode 9 supports two factor authentication with GitHub. This is a great way to secure your account and make sure that only you can access your source code.
Great! So I've signed into Xcode -- or into GitHub in Xcode and we see that Xcode has automatically detected my SSH keys.
So I can clone using either HTTPS or SSH, whichever I prefer.
I'm going to leave it set to HTTPS, but before I go clone anything let me just go to my source control preferences and make sure everything is set up exactly the way I want.
So here if I go to source control I see that I have source control enabled and if I go specifically to the "get" settings we see that new in Xcode 9 you can now configure your "get author" and your "globally ignored" files right in Xcode.
So your get author, your user name, and email are what people will see when you make commits. So they'll know who to go to when they find a bug on that line.
So I think I'm all set up here.
So let's go back to the welcome window.
And to get to that new clone window we saw earlier I just go straight to "clone an existing project" right from the welcome window and immediately it populates with a list of projects that I might be interested in.
Now this is all the projects that I own and maintain on GitHub as well as any projects that I've starred on GitHub and indicated that I have some interest in.
Additionally, if I'm a member of any organization that has repositories on GitHub, such as the Apple organization here, I can see those repositories as well.
Now if this isn't what I'm looking for I can just search. So Kieran was telling me earlier that I should really check out research kit.
Research kit is Apple's open source framework for creating medical research applications and it's available on GitHub.
So I'll just search research kit and I'll put that into the search field and sure enough what comes back is research kit.
And if I'm not sure this is the one I'm looking for I get a little bit more information in the detail view.
So if we zoom in on that we see I get the full name and if I click that I can go right to the GitHub page for it.
But usually everything I need's right here. I get the description, the language, the number of people who have forked the project, how many people have starred the project, and the read me for the project.
So if I click the read me you get the read me file that this project provides on GitHub and usually this has information like a bit more about the project or how to get started with it and even some sample code.
And one of the great things is since a lot of these are written in markdown, when you do clone a project they work great in Xcode's new enhanced markdown support in our source editor. So that is the one I want so I'll go ahead and star it.
And so right in Xcode when I click the star button we see the star count incremented because I'm now starring this repository.
And if I clear out my search we see that sure enough, right in my default view I see research kit now. So every machine I sign into I can easily get back to research kit if I want to check that out a little bit later.
But today I want to check out that TOTP app. So TOTP is a onetime password generator. It's actually the app you saw me use a little bit earlier to sign in to GitHub. So I'll just clone that and right away I can save it to my documents folder.
And that's it. It's super simple in Xcode 9 to clone projects from GitHub. There's no more off prompts or any choices you have to make once you've selected a project.
And immediately upon cloning Xcode will open the project and you get a very familiar view. You get your project navigator and your editor area. And if we look over in the left, sure enough next to the project navigator we see the new source control navigator.
So this automatically gets populated with every working copy that makes up your project.
In this case I only have one; the TOTP working copy.
And I see the one branch that I automatically cloned when I cloned from GitHub Master.
If I select "master" I instantly get the full history of the project.
And here we see all the commits that make up this project and make it what it is.
Now Kieran was showing something a little bit earlier that looked like a bug and we should probably fix that before we move on.
So I need to find that. So I saw that it was made by Kieran.
So I'll just say, "author; Kieran." And here's all the commits Kieran's made.
And I think it had something to do with the generator, if I saw correctly. So I think it was something where in the message he said, "Generator." Generator -- sorry.
Ah, that's the one.
And if I select it I get a lot of extra information about that commit.
So in addition to a new source control navigator, a new source control history view, we also have a new source control inspector.
And in the inspector, when I select a commit I get additional information about that commit such as the full shaw, the exact commit date and time, the author, as well as the full commit message. I can also see the files that were modified in that commit. And if I want to review the changes made to any file in that commit I can click this arrow and go straight to them.
But as Kieran mentioned earlier, there's an even better way than just double clicking or clicking this arrow to get to the dif, and that's to make use of Xcode's assistant editor.
So many of you may be familiar with Xcode's assistant editor, but probably have seen it mostly on the right.
Now I want a little bit of extra horizontal space to view dif sen so if I click and hold on the "assistant editor" button I can select to have the assistant editor on the bottom.
And when it opens it automatically shows the commit details for the commit I have selected above. So this is great. I can go right to the change that Kieran made and sure enough, there it is.
Uh, well we should probably fix that.
While I'm here, let me just show you -- so even if I want to look at some other commits they show up. The second I click them I get all the files and all the changes made in those commits.
So let's close the assistant editor and go over to the app delegate, where I think that change was that broke it.
Ah, here it is.
So I'll just go ahead and fix that.
Great. I love magical code completion that fixes bugs.
And I would normally just commit this right onto master and be done with it, but I think this change should use -- could use a little bit more testing to make sure we've actually fixed this bug because I want to be sure.
So if we go back to the source control navigator and I select my master branch and control click it I can create a new branch from master.
And this new branch I'll just call "fix" because I don't have any good names.
So this now automatically got checked out by Xcode and all my uncommitted changes are now sitting on top of the fix branch.
So with that I'm ready to commit. And to do that I just go to source control and select "commit" and make sure my dif is correct.
Let's see, "fixes a crash." Great.
So now that is one of those commits that make up the history of my project.
And I can verify that if I go to the "fix" branch in the source control navigator.
Here we see that brand new commit I just created today.
Now one of the things that I often find when I'm making branches and committing things is that I forget what commits are on what branches and I easily lose track of them and it's really annoying to have to figure out whether or not a commit you've made landed in the right branch.
Well Xcode 9 has a great way to figure that out.
If I select my commit and zoom in here on the inspector we see that there's a branches area. And right now the only branches listed for that commit is "fix." So this particular commit is only in the fix branch.
If I go back and look at an older commit, now if we look at it this commit is a bit older and was before I branched.
So it's actually in both the "fix" branch and the master branch. So this is a great way to figure out exactly where your commits are and know exactly what you're shipping to your customers.
Now normally I create an Xcode server bot to integrate this and some unit tests and all that, but since I just got a thousand of my closest friends here to code review my change I'm going to just merge it into master.
So again, if I control click "master" in the navigator I can merge from "fix" into "master" and in one step I have merged my fix into master and switched to the master branch super easily from the source control navigator.
And sure enough, the history view updates.
This review updates and I can see that my fix is now on the master branch as well as "fix." And if we zoom in over here, if I need to confirm that indeed this change made it to master, the master branch is listed.
Now this was a crash that was affecting a lot of our users so I want to make sure we get this app out quickly. So I'm going to tag it.
And if I control click on a commit we see that there's a bunch of actions I can do on a commit as well. So just like you can do actions on a branch in Xcode 9, you can do particular actions on a commit such as checking out or branching even from an older point in time.
But today I'm going to tag this commit so that we know which one we want to release as Version 1.2.
So I'll select "tag" and select "releases/v1.2" and create that tag. And there we go. As soon as I do that the tag is automatically upended to that commit.
And I can verify that in the "tags" folder of the source control navigator.
And because I've been using slashes and names to prefix all my tags we see Xcode creates an automatic hierarchy for me in the navigator, making it super easy to organize my project.
So we'll get that onto the App Store to get rid of those one star reviews from all that crashing.
But while Kieran was up here I had another really cool idea that I was just thinking about. So I'm going to create a new project.
So let's open up Xcode and let's get started with a new Xcode project. And you know what I was thinking would be really fun is if we made some SCM centric stickers for iOS. So I'm going to make a sticker pack app.
So I'll just select that and call it "SCM Stickers." Now every time you create a new project in Xcode, Xcode always offers you the option to create a git repository right then and there as you create the project.
Now personally I always do this, even if I think it's just a throwaway project or I'm testing some code because you never know how long you're going to keep working on the same thing and this way you always have history from the very beginning of time for your project.
So let's create that git repository on my Mac.
And now I have my sticker app.
If we go to the source control navigator from this app we see that I have a working copy that was automatically created by Xcode and it has one branch master which is current.
And it has the initial commit, which is essentially just all the template stuff from Xcode.
So now it's time to put my stickers into my app.
So let's go over to the project navigator and select the "stickers" folder.
And I already have a few stickers here that I like. I've got one of a "tag" icon and I've got a few emoji peeking out from a safe. That says "SCM." So let's put those all into my sticker pack and go to "commit." So I'll go ahead and commit all those stickers.
And now they're all part of my history.
And if I look at my branch I have two commits.
But if I open the "remotes" folder I don't have a remote.
In fact this project only exists locally. So while git is tracking history for my project, if I want to check it out on another machine, share it with somebody else, or if I lose this machine, this is the only copy. So I need to make sure that I can put it somewhere where it's safe and easy to share with other people.
And for that I'm going to use GitHub again.
So if I control click on the "remotes" folder I see that one of the options is that I can now create the SCM stickers remote right on GitHub.
And if I select that a new sheet comes down and asks me all the things I want to set up about my project on GitHub.
I get to choose what account that I'm going to use. So I'll use mine.
And I can select the owner. So if you're a member of organizations and have permission to create repositories for them you can actually create repositories for your organizations.
And then I get to select a name for my project and by default it'll just pick the project name; "SCM Stickers." If we look closely we see that the owner name and repository name combine to form the URL where you'll be able to check this out on the World Wide Web.
Now let's give it a little bit of a description.
And while I would say check it out on the World Wide Web, but I can actually make it private so that no one but me can see it and commit to it because I don't think the world's quite ready for these yet.
If I go ahead and select "create" that project will get created on GitHub under my account and all my changes will get pushed right up to the server.
Ah, I forgot one of the stickers and it's my favorite one! Let's go back to the project navigator and select "stickers." And I don't know if you know this, but GitHub's logo is actually an octo-cat.
Well, I thought I'd take my -- try my hand at making my own octo-cat.
And so let's add that as one of the stickers.
And let's go ahead and go commit that.
Make sure that that gets up on the GitHub too.
Octo-cat. Now, since I now have a remote I can go ahead and push all my changes right up to GitHub where they're safe and secure as I commit to skip a whole bunch of extra steps of having to do it later. And this way I don't end up behind from my remote branch.
So I'll just go ahead and commit and push those files and that sticker now will also be up on GitHub.
If I go to my repository -- or sorry -- my source control navigator again and look at my master branch it now has three commits and I see that the remote's origin master branch is also at the same place.
If I want to be even further sure that this commit made it up onto GitHub or I wanted to look at it on GitHub I can just control click the commit, and like any other object in source control and Xcode, such as a branch or tag or remote, I can view it on GitHub. And if I select that Safari will open up straight to that commit on GitHub and I see my beautiful octo-cat.
Now I want Kieran to be able to check this out to, but I made it private. So let's go to "settings" and add him as a collaborator.
And we've got to make sure we're secure.
So let's add Kieran.
There he is.
So we'll add him as a collaborator so now he can see this private repo too. And I want him to check it out as soon as possible. So I'm going to make it really easy for him and I'm going to go ahead and we see on GitHub the "clone" -- or "download" button, just like we showed earlier the "open in Xcode" button is right there and I can even select that and just share that link with him in mail.
Let's see here.
Let's send that to Kieran.
"Check out my stickers." We'll send that to Kieran so he can just click this link right on his machine as soon as he gets it, Xcode will open, clone it, and he can have fun with my octo-cat.
Great. So now before he does check that out I want to bring him back on stage to talk a little bit more about source control and Xcode. Thank you.
Awesome. Thank you, Eric. I'll be sure to check that out on the World Wide Web later.
It's okay; I lived through the '90s.
So Eric showed us how easy it is to get started with source control and Xcode.
By adding your GitHub account you have quick access to all of your repositories.
With the new source control navigator we saw how easy it is to manage your branches, tags, and remotes.
And finally, we saw how easy it is to create a new project on GitHub and push all your code up.
So for more information check out session 405 on developer.apple.com.
There are also some related sessions you can take a look at.
You're very welcome.
Have a good rest of the week. Thanks!
Looking for something specific? Enter a topic above and jump straight to the good stuff.
An error occurred when submitting your query. Please check your Internet connection and try again.