Hour 12. Using Source Control

---

What You’ll Learn in This Hour:

• The source control features offered in Xcode

• How to create and restore project snapshots

• The language of source control systems

• How to connect to remote Subversion and Git repositories

• The tools available for working with Subversion and Git

---

As projects grow larger, it becomes more and more important to keep track of the changes that you make and be able to identify modifications to your code. A change can sometimes cause unintended behaviors that, without a good way to audit your coding, might be difficult to track down. This is especially true for projects where one or more people need to access and modify the same project.

The answer to this problem is to use source control—a term that refers to a system that keeps track of changes to source code files. Xcode offers a number of source control options, from creating simple project snapshots, to integration with two of the most popular source control systems currently available: Subversion and Git. This hour’s lesson walks through these options and helps you get started using the tools Xcode provides.

Using Xcode Snapshots

If you’re planning to make many changes to your code and you’re not quite sure you’ll like the outcome, you might want to take advantage of the Xcode “snapshot” feature. A code snapshot is, in essence, a copy of all your source code at a particular moment in time. If you do not like changes you have made, you can revert to an earlier snapshot. Snapshots are also helpful because they show what has changed between multiple versions of an application.

Snapshots are a limited form of source control. Later in this hour, you learn about the full source control features offered in Xcode and how to take advantage of them. For many small projects, however, snapshots are likely all you will need.

Creating Snapshots

To take a snapshot of an open project, choose File, Create Snapshot. You are prompted for a name of the snapshot and a description, as shown in Figure 12.1. Provide appropriate input, and then click Create Snapshot. That’s all there is to it.

Figure 12.1. Create a snapshot of your project at any point in time.

Viewing and Restoring Snapshots

To view (and possibly restore) an available snapshot, choose File, Restore Snapshot. The snapshot viewer displays available snapshots for the project. Choose one and then click Restore, as demonstrated in Figure 12.2. Don’t worry. Xcode won’t restore just yet; you still have a chancel to cancel.

Figure 12.2. Choose the snapshot to (potentially) restore.

The display updates to show the files that changed between your current code and the chosen snapshot. Clicking a filename shows the snapshot code on the left and the current code on the right—highlighting changes between the different versions of code, as shown in Figure 12.3.

Figure 12.3. Use a snapshot to figure out what changes you have made among different versions of your application.

If, after viewing the changes, you still want to restore to the selected snapshot, make sure the files you want to restore are checked in the file list and then click the Restore button. Click Cancel to exit the snapshot viewer without making any changes.

Managing and Exporting Snapshots

You can manage all your project’s snapshots as well as export a snapshot as a new copy of your project by accessing the Projects section of the Organizer. Open the Organizer using the Organizer button on the far right of the Xcode toolbar, or by choosing Window, Organizer from the menu. Click the Projects icon to switch to the Projects section.

Projects are listed down the left side of the window, as shown in Figure 12.4. Clicking a project shows the snapshots associated with it. You can select individual snapshots and click the Delete Snapshot button to remove it, or the Export snapshot button to export all the files into a new folder of your choosing.

Figure 12.4. Manage and export your snapshots.

Xcode Auto Snapshots

Xcode can (and will) automatically take snapshots for you when you complete an action that makes changes across all (or many) of your files, such as a find and replace. To control this behavior, choose File, Project Settings, and then click the Snapshots check box in the dialog that appears, as shown in Figure 12.5. You can also use the Snapshots Location field to choose where project snapshots are saved.

Figure 12.5. Enable or disable auto snapshots.

A Brief Introduction to Source Control Systems

Snapshots are a great way to keep copies of your projects as you make enhancements or bug fixes. However, they pale in comparison to the features provided by a dedicated source control system. For the rest of this hour, we look at features in Xcode that, although similar to snapshots, go far beyond this simple functionality.

Xcode includes support for two popular version control systems: Subversion, also known as SVN (http://subversion.apache.org/), and Git (http://git-scm.com/). Like any version control system, the purpose of these products is the same, but the implementation in Xcode is different enough to be confusing. Before trying to use Xcode with SVN or Git, you need a bit of background in the philosophy and terminology of each system.

Repositories and Working Copies

Both Git and Subversion can provide server-based repositories. These act as very lightweight file servers that include the files for a project, along with a log of all the changes that have been made over the life of the project.

To edit code that is stored in a repository, you create what is called a working copy from all, or a portion of, the repository. The working copy is a local copy of a project that is edited on your computer (often pulled from a Git or SVN repository). The initial creation of a working copy is called a checkout in SVN terminology and a clone in Git terminology.

Committing Changes

One of the biggest differences between your use of Git and SVN in Xcode is saving changes to your code. You edit your projects exactly as you always have, editing the working copies of your code. When you decide you want to save a change to the repository, you execute a commit action. The commit notes the change and gives you an opportunity to annotate the change, as well.

In Subversion, a commit stores the updated file back to the repository immediately. In Git, however, your local copy is the repository, so nothing is updated on the remote repository. To push your changes back to a network repository, you must execute a Push command, as discussed later in this hour.

Downloading Changes

As you commit and, in the case of Git, push changes to a central repository, you’ll also want to download changes that other users have added to the repository. To do this, you execute an Update command on the SVN repositories and a Pull on Git repositories. In either operation, if there are conflicts with the code occur in your working copy, you are given the opportunity to reconcile the conflicting code.

Branching and Merging

Developers often need to maintain a release version of a product while working on new features. The base/release version of a project in Git/SVN is the trunk. New versions of the trunk are developed in branches off of the trunk or off of another branch. In Subversion, you work on branches in a new working copy of your code. Git maintains a single working copy and enables you to switch branches at will.

When changes are complete, and a branched version is ready to become the release version, it is merged with another branch (or the trunk) to create a unified code base. Conflicts are dealt with, and then the finished code is committed to the repository and pushed (with Git) to the remote server, if desired.

These are the basic operations that you learn about in the rest this hour. We cover just the tools necessary to make this work in Xcode. Entire books are written about using Git and Subversion, and the feature set exposed in Xcode is much smaller than what is available from the CLI. If you’re interested in learning more about these tools, I highly recommend reading the resources on their respective websites.

Working with Subversion and Git Repositories

Xcode’s integration of Subversion and Git features directly into the UI make working with these systems quite simple, even if you have never touched a version control system before. In fact Xcode even enables you to create local Git repositories that you can use to track your own changes on a project or share, via a file server, with other individuals working on a project.

In this part of the hour, we create a local repository, and then cover the process needed to connect to remote SVN or Git servers. Because these topics do not necessarily flow together as well as I would like, do not feel bad about jumping around to find the information relevant to you.

Creating Local GIT Repositories

If you’re a small developer with a good backup system and only a few people working on a project, you can probably do just fine with a locally hosted Git repository that Xcode can create for you when you start your project.

To create a project that includes its own Git repository, follow these steps:

1. Begin the project-creation process, as you learned in Hour 4, “Using Xcode Templates to Create Projects.”

2. When prompted to save the project, be sure the Source Control check box is checked, as shown in Figure 12.6.

Figure 12.6. Make sure you have checked the option to use source control.

3. Click Create. The project is created and opened.

Within the main project group in the Project Navigator, you’ll see a status icon, probably M, as demonstrated in Figure 12.7. This shows the status of the project’s source control and demonstrates that your new project is within a repository. You learn more about the source control status icons in the section “Managing a Project in Source Control,” later this hour.

Figure 12.7. A source control icon appears in your main project group.

If you want to start working with files in your repository, skip ahead to the “Managing a Project in Source Control” section. If you think you would like to connect your new repository to a Git server, read the upcoming section “Loading a Project into a Repository.”

Connecting to Remote Repositories

If you have already established a hosted repository outside of Xcode, you can connect Xcode to the repository by walking through a simple setup assistant. This enables Xcode to download and work with copies of the stored code—or upload new code to the server. You manage access to your repositories through the Xcode Organizer’s Repositories section (Window, Organizer), as shown in Figure 12.8.

Figure 12.8. Use the Organizer to manage your repositories.

To add a new repository, follow these steps:

1. Click the + button in the lower-left corner of the Repository view within the Organizer, as shown in Figure 12.8.

2. When prompted, add a name for the repository and the URL that describes its location, as shown in Figure 12.9. This information is available from your repository provider (and is usually displayed front and center when a repository is created).

Figure 12.9. Enter the information for the new repository.

3. The repository type is autodetected, but if it isn’t, use the Type pop-up menu to choose between Subversion and Git.

4. Click Next to continue.

5. If prompted for authentication information, enter it in the dialog box shown in Figure 12.10 and then click OK.

Figure 12.10. Provide authentication information if requested.

6. Subversion repositories may prompt for additional information—the paths to the Trunk, Branches, and Tags directories, as shown in Figure 12.11. Enter these if you have them. These are special folders within the repository and are not necessary for creating your connection.

Figure 12.11. Enter the paths for Subversion repository directories.

7. Click Add, and the repository is added to the repository list within the Organizer. Selecting the repository enables you to review the type of the repository and its configuration information at the top of the organizer.

Loading a Project into a Repository

After creating a repository and connecting to it, you either want to pull code from it or add code to it. If you already have a project in the repository and want to download a working copy of it, skip ahead to the “Creating a Working Copy” section.

If you’re still reading, you want to add code to the repository, right? In that case, there are a number of different approaches you can take. Regardless of whether you’re using Subversion or Git, you can create a working copy of the repository and copy your existing project folder into it, and then commit those changes back to the repository. That said, there are methods specific to both Git and Subversion that might make getting your first code files in a bit easier.

Subversion

Subversion repositories have a special import tool to simplify the import process. To populate a subversion repository for the first time, follow these steps:

1. Open the Organizer and switch to the Repositories view.

2. Expand the SVN repository that you want to perform your initial upload to.

3. Select the Trunk folder, as shown in Figure 12.12.

Figure 12.12. Select the trunk to import your initial code files.

4. Click the Import button in the lower-right corner of the window.

5. When prompted, choose your project folder, as shown in Figure 12.13.

Figure 12.13. Choose the project to import.

6. Enter a comment for your initial upload to the repository, as shown in Figure 12.14, and then click Import.

Figure 12.14. Enter a comment for the import.

Your project is then imported into the Trunk directory. Be aware that depending on how large the project is, this can take quite some time. Xcode provides almost zero feedback during this process, so be patient. Figure 12.15 shows a project, ImageHop, showing up under the Trunk directory after a successful import.

Figure 12.15. After the import is complete, the project folder should be visible.

Git

For Git projects, you need to either copy your project into a local Git working copy, or if you have already set your project up under local Git source control, you can push the entire project to a repository very quickly.

Git repositories are self-contained. So, instead of pushing a local Git project into a repository you define in Xcode, you instead “tell” your local Git project about the presence of a remote Git repository and provide it with the information it needs to access it. Your repository can then automatically push to the remote server.

To configure a remote repository for a local Git-based project, follow these steps:

1. Open the Organizer and switch to the Repositories view. All your local repositories are listed.

2. Expand the repository you want to work with and click the Remotes folder within it.

3. Click the Add Remote button at the bottom of the Organizer window.

4. When prompted, enter the name and location for the remote repository, as shown in Figure 12.16.

Figure 12.16. Enter the name and location string for the repository.

5. Click Create.

6. Close the Organizer and switch back to your project.

7. From the File menu, choose Source Control, Push.

8. When prompted, choose the repository you configured and then click Push, as shown in Figure 12.17.

Figure 12.17. Click Push to upload your changes.

Your project is pushed to the remote Git repository. You have effectively just converted your local Git project into one that is connected to a hosted Git repository.

Creating a Working Copy

Before you can start working with code that is under source control, you need to create a working copy. For Git projects, you may have already done exactly that by creating a local repository. The local repository is your working copy and can be connected back to a hosted repository using the steps described in the previous section.

Subversion users always, after having created an initial import, need to create a working copy to use in Xcode. Regardless of the route you took to get here, this section walks through the steps of using one of your defined repositories to create a working copy of a project that you can then use in Xcode:

1. Open the Organizer and switch to the Repositories view.

2. For Git repositories, click in the column on the right to select the name of the repository. For Subversion repositories, expand the repository by clicking the disclosure arrow, and then click the Trunk, Branches, or Tags directory within, depending on where the code you want to check out is located.

3. The content area to the right of the repositories list refreshes to show the possible directories that you can check out (Subversion) or clone (Git), as shown in Figure 12.18.

Figure 12.18. Locate the code directory that you want to check out or clone.

4. Select the directory and click the Checkout button (Subversion) or Clone button (Git) at the bottom of the Organizer.

5. When prompted, enter a name to use for saving the working copy.

Xcode downloads the code and prompts you whether to open the project and begin working. The working copy is shown with a blue folder under its repository in the Organizer.

Managing a Project in Source Control

Once you have a project under source control, you work just as you normally would, but you now have some additional options at your disposal. You’ll also notice some changes in how the files display in the Project Navigator. In this, the last part of the hour, we review many of the common activities you will perform with your Subversion or Git repository.

Status Codes

When working with a project that is under source control (that is, your working copy), you’ll notice that a number of badges appear beside the files listed in your Project Navigator, as shown in Figure 12.19.

Figure 12.19. The Project Navigator now contains badges indicating source control status.

Table 12.1 lists the badges you might encounter, as provided by Apple.

Table 12.1. Badges You Might Encounter

Commits and Pushes

The most common type of change you need to make when working with source control is a commit. A commit is used to add a finished collection of code to the repository. You might, for example, perform a commit at the end of every day or commit any changes you have made after you have tested them thoroughly.

To perform a commit, follow these steps:

1. Choose File, Source Control, Commit.

2. The Commit dialog appears, as shown in Figure 12.20.

Figure 12.20. Commit the check files to the repository.

3. Click to check the check boxes beside each of the modified or added files that you want to commit.

4. Enter a message to describe your changes in the text area at the bottom of the dialog.

5. Click Commit to commit your changes to the repository.

After you have completed a commit on Subversion, you’re done. Your file is sent back to the hosted repository. With Git, however, your changes are sent to the server only after you execute a Push command. To push your changes, select File, Source Control, Push from the menu. After a few seconds, you should see a list of the possible remote destinations you can choose from, as shown in Figure 12.21. Choose the destination and then click Push. Your changes are transmitted to the remote repository.

Figure 12.21. Choose where the files should be pushed.

Updates and Pulls

While you’re making changes to your project in your local working copy, others might do the same in their copy, committing changes back to the repository. The end result: Your version of the project might become out of sync with the central repository. This is not a problem. In fact, it’s a guaranteed outcome of a distributed source control system.

To update your working copy of a project to the latest version held in a repository, you use the Update command (Subversion) or Pull command (Git). Strangely, only the Pull command is available from the File, Source Control menu, whereas Update is available under the contextual menu. To keep things consistent, I recommend these steps:

1. Go to the Organizer’s Repositories area

2. Select the blue folder (the working copy) of the project you want to update/pull.

3. Click the Update or Pull button that appears below the content area of the screen, as shown in Figure 12.22.

Figure 12.22. Click the Update or Pull button (shown here) to get your code in sync.

Viewing Revisions

Using source control enables you to go back through your code and see what changed and when. You can get a quick view of all the commits that have been made to a repository, working copy, or any directory of a repository by selecting it in the Organizer, as shown in Figure 12.23.

Figure 12.23. Use the Organizer to get a quick view of the history of your changes.

You can even expand each item in the history and can click the View Changes button to see the changes that have been made to a specific file. As you browse the history, you’ll notice that the names associated with changes are not necessarily helpful. To make reviewing the history easier on the eyes (and brain), Apple allows you to tie source control users to individuals in your OS X Contacts application. To do this, just click the silhouette of a person in the history. A popover appears, as shown in Figure 12.24.

Figure 12.24. Choose a person to tie to the repository changes

Use the popover to enter the pertinent information about the person, or click Choose Card to pick a card from your contacts.

Using the Version Editor

In addition to the Organizer, you can also view the changes that have been made to a file through the Version editor in the main Xcode interface. This works on the current file you have selected, so it is a bit easier to target and identify individual changes.

To display the Version editor, click the third icon in the Editor section of the Xcode toolbar. The screen refreshes to show one of three modes (Comparison, Blame, and Log), controlled by the three icons in the lower-right corner, as shown in Figure 12.25. Here, the Log mode is visible.

Figure 12.25. Use the Version editor to target changes to a specific file.

In the Log mode, a chronological list of changes is shown to the right of the current file. Clicking the arrow beside each entry displays the changes.

The Blame mode is similar to the Log mode, but displays the change entries next to the code that was changed, as shown in Figure 12.26. Click the gear icon beside each name to show a popover with the full details about the change, and then click the arrow within the popover to view the changes.

Figure 12.26. Blame mode makes it easy to assign blame to your team.

The final view, Comparison mode, shown in Figure 12.27, displays revisions side by side in the Editor area.

Figure 12.27. Use the Comparison view to see changes side-by-side.

Use the pop-up file paths under each side of the view to choose the revision you want to see. Alternatively, you can click the clock icon to show a Time Machine-like view of both files. In this view (visible in Figure 12.27), you can use the arrows on either side of the black bar to position the point in time you want to display on either side.

Branches and Merges

When writing code, you’ll finally reach a point (I hope) where you are ready to release a product. At that point, you will likely want to create a new branch of your code that will contain any future work (feature additions, for example). You can still continue to work on the existing copy for bug fixes and so on, but the new branch represents your next release.

Creating Branches

To create a branch in Subversion or Git, follow these steps. (Apple has made the process mostly identical regardless of your repository choice).

1. Open the Organizer and switch to the Repositories view.

2. Navigate to the Branches folder within the repository where you want to create a branch.

3. Click the Add Branch button at the bottom of the window.

4. Provide a name for the branch and choose a starting point (an existing branch, or the trunk copy of your code) to copy, as shown in Figure 12.28.

Figure 12.28. Create a new branch.

5. In Subversion, this is committed back to the repository immediately, so enter a message to go with the branch action.

6. Choose whether to check out the branch and make a new working copy. In Git, this option is called Automatically Switch to This Branch because instead of creating a new working copy, it switches the existing working copy to the code contained in the branch.

7. Click Create.

Xcode now churns away for a while and, if you have chosen to create a new working copy or switch branches, opens the new branch ready for editing. You then work within the branch until you reach a point where you are ready to merge it back to your main code base, such as a new release. At that point, you perform a merge.

Performing Merges

To merge a branch back to another branch or to the trunk of your repository, first open a working copy of the code that you want to merge into. This would be your first release, the trunk, or the branch you used to make the branch you’re currently working on. Now, with the project open, follow these steps:

1. View the project in the main Xcode workspace (not the Organizer).

2. Choose File, Source Control, Merge.

3. Pick the branch that you are merging with your code, as shown in Figure 12.29.

Figure 12.29. Choose the branch to merge with your code.

Xcode merges the branches together, identifying any conflicting code along with way, as shown in Figure 12.30. At this point, you must resolve any conflicts before proceeding.

Figure 12.30. Fix any conflicts in your files.

Work through each file listed on the left side of the display. Using the buttons at the bottom of the screen, choose whether to use the code from the file on the right or the file on the left. When satisfied with your selections, click the Merge button to merge the changes into your repository. You should then perform a commit (and a push, in Git) to sync the merge to the remote source control servers.

Summary

In this hour, you learned how to use the different source control options in Xcode. Snapshots, the easiest to employ, can be used on any project at any time and create a view of your code at a specific point in time. You can even export a snapshot to a new project if you choose to split your development at some point. In addition to snapshots, Xcode integrates access to Subversion and Git repositories, including local Git repositories that require no additional servers. Using these options, you can easily work with teams to collaboratively code. Although a few options are missing, and the interface is not as consistent as I would like, the Xcode source control tools do provide most of the features you need to manage large, distributed projects.

Q&A

Q. Aren’t snapshots just as good as using Git or Subversion?

A. If they fulfill the source control need you have, absolutely. Git and Subversion are useful for projects with multiple developers and multiple branches. These tools also put source control front and center, making you aware of the status of your source files at all times.

Q. Why doesn’t Xcode provide the ability to revert to a previous revision within a repository?

A. I wish I knew. You can right-click a changed source file and copy the differences from one file to another, but as of the time of this writing, reverts are still not possible.

Q. Source control sounds like a hassle. Should I bother?

A. I recommend working with a local Git repository. If you see value in this, expand your horizons by looking at a hosted repository in the future.

Workshop

Quiz

1. Snapshots are implemented using Subversion. True or false?

2. Using the Versions editor, you can easily revert to an earlier copy of a file under source control. Yes or no?

3. How do you upload a local Git repository to a remote server?

Answers

1. Snapshots are a feature of Xcode outside of Subversion or Git.

2. No. You can view the differences between files, but not revert. This is currently not a feature provided with Xcode, but can be handled by using the Subversion and Git tools directly at the command line.

3. Use the Organizer to redefine a remote for the repository, and then use the File, Source Control, Push command to push the existing code base into the remote.

Activities

1. Create a project and experiment with the various source control options. Use the snapshot feature to create and restore snapshots. Use a local Git repository to create branches, merges, resolve conflicts, and so on.

2. Sign up for a Subversion or Git repository at one of the hosting providers mentioned in this hour. Practice connecting to the repository in Xcode and importing projects and creating working copies.