Save and Revert Changes to Projects
Xcode provides several ways to save versions of your project:
A snapshot saves the current state of your project or workspace on disk for possible restoration later.
Source control repositories keep track of individual changes to files and enable you to merge different versions of a file.
An archive packages your products for distribution, either through your own distribution mechanism or for submission to the App Store.
Xcode provides direct support for Git and Subversion repositories, including an option to create a local Git repository when you create a new project. Because it’s so easy to set up a repository to use with your Xcode project, Xcode provides a special editor, called the version editor, that also makes it easy to compare different versions of files saved in repositories.
This chapter assumes that some developers using Xcode are new to repositories. If you’re an experienced repository user, skip over the introductory material in each section and go straight to the descriptions of aspects of Xcode’s repository UI.
Take a Snapshot of Your Project
A snapshot provides an easy way to back up the current version of your project or workspace so that, if something goes wrong with a change or process, you can restore the earlier version. Xcode can create a snapshot automatically before a major change such as refactoring your code or executing a Find and Replace operation. You can change this setting any time in the Snapshots pane of the File > Project Settings or File > Workspace Settings dialog (Figure 12-1).
You can also set Xcode to automatically create snapshots in other circumstances, such as before a build, by selecting the Create Snapshot option in the Behaviors pane of Xcode preferences (“Customize Your Build and Run Workflow”).
You can create a snapshot manually whenever you like by choosing File > Create Snapshot. To see where Xcode stores your snapshots, or to change the location, look in the Locations pane of Xcode preferences or the Snapshots pane of the Project (or Workspace) Settings dialog.
To see the snapshots for a project or workspace, click the project in the projects organizer. To restore from a snapshot in Xcode 4.0, select a snapshot in the projects organizer and click the Restore Snapshot button at the bottom of the window.
In Xcode 4.1 and later, to restore a snapshot, choose Restore Snapshot from the File menu and select the snapshot to restore. Xcode displays a preview dialog in which you can review the differences between the current version of the project and the snapshot version. When you click Restore, Xcode replaces the current version of the project with the version in the snapshot. Xcode makes a snapshot of the current version before replacing it.
To restore a snapshot in a new location instead of restoring on top of the current project, select the project in the Projects pane of the Organizer window, choose the snapshot you want to restore, and click the Export Snapshot button at the bottom of the window (Figure 12-2).
Because Xcode 4 keeps track of all your projects and displays them in the projects organizer even if they no longer exist, you can restore a deleted project from a snapshot.
Keep Track of Changes with Source Control
When working on a software project, it can be very useful to use software control management (SCM) to keep track of changes in the code and coordinate work groups. An SCM system, also referred to as source control, saves multiple versions of each file on disk, storing metadata about each version of each file in a location known as an SCM repository.
Why Use Source Control?
There are two fundamental reasons for using source control:
A source control system helps you reconstruct past versions of the software and the process used to develop it. If you are working on a project by yourself, you can commit a file to your SCM repository each time you make a major change. Then, if you find you’ve introduced bugs, you can compare the new version with a past version that worked correctly to help to locate the source of the trouble. In the worst-case scenario, you can revert to an earlier version and start over from there to reimplement the new feature. If you keep your repository, or a copy of the repository, in another, physically safe location, you can even reconstruct your project if your computer is lost or destroyed.
When two or more people are working on the same project, source control helps prevent conflicts and helps resolve conflicts should they arise. By keeping a central repository that holds the canonical copy of the software, the source control system allows each programmer to work on his or her own local copy without any danger of corrupting the canonical version. If you set up a system of checking out a file before working on it, you can ensure that two people are not working on the same code at the same time. If two people do change the same code, the SCM software helps you to merge the two versions. You can also look through past changes to see what they were and who made them, which can be a great help in managing the project and in fixing bugs.
Choose Git or Subversion
Xcode supports two SCM systems: Subversion (often abbreviated svn) and Git. Subversion is always server-based and the server is normally on a remote machine, though it is possible to install one locally. Git can be used purely as a local repository, or you can install a Git server on a remote machine to share files among team members. The Xcode 4 installer installs the Git and Subversion tools when you select System Tools.
If you are working alone, it’s generally easiest to use Git, as you don’t need to set up a server. In fact, Xcode can automatically set up a Git repository for you when you create a new project (see “Create a Git Repository For Your New Project”). For a group project, the choice of Subversion or Git is usually a matter of taste and prior experience.
In so far as is possible, Xcode provides a consistent user interface and workflow for users of either Subversion or Git.
Learn SCM Terminology
In general, you work on a copy of the project (called, appropriately, a working copy). The command to create a working copy is clone for Git and checkout for Subversion. When you have changed one or more files and want to add your changes to the repository, you execute a commit command to the SCM software. The SCM software records the date and time of the commit, any comments you include to help you remember later why you committed this version of the code, your identity (that is, the identity of the person who executed the commit command), and any other information the SCM software needs in order to keep track of the software.
Because Subversion repositories always reside on a server, when you commit changes to your project, Xcode sends those changes back to the server. Because Git repositories can be local or on a server, the situation is a bit different with Git. For Git, your working copy is also a local repository, so once you’ve committed the file, the repository has been updated. Even if you have a remote Git server, committing a file in Git does not automatically send changes to the server. To update the Git repository on a remote server, you use a push command.
To update your working copy with the latest version of the file in a remote repository, you use a pull command (in Git) or update command (in Subversion). For a local Git repository, the pull command is not needed.
The main line of code for development is often referred to as the trunk. To avoid modifying the trunk while developing new features, you can create a new copy of the project referred to as a branch. Eventually, branches are merged back into the trunk. In Git, a branch is simply a working copy of the project. In Subversion, a branch is a copy maintained by the repository. You can check out any number of working copies of a Subversion branch. When you update your local working copy with the update or pull command, and when you merge two branches or merge a branch into the trunk, Xcode displays a dialog that lets you reconcile differences between the versions. You can also use the version editor to compare two versions of a file at any time.
Manage Your Repositories
In Xcode, you configure SCM repositories in the Organizer (Figure 12-3).
The repositories pane of the Organizer window (referred to hereafter as the repositories organizer) lets you examine the structure of the repository (folders, files, and branches) and your working copy. In addition to the more obvious features provided by the repositories organizer, it lets you assign address-book information to the person who committed each version listed and you can examine the changes to each file for each commit.
Click a repository in the navigation pane of the repositories organizer.
Click the icon well next to the commit ID number.
Fill in the information about the person who executed the commit, or if the person is in your address book, click Choose Card and select that person’s card in your address book. If your address book has a picture associated with the entry, the picture is displayed in the organizer.
View files in a specific commit version to inspect changes that you have made to those files.
Find SCM Commands
SCM commands are located in the main Xcode menu, in the shortcut menu, and in the repositories organizer.
Source control commands are in the Source Control submenu of the File menu (Figure 12-4).
The project navigator shortcut menu contains a subset of these commands (Figure 12-5).
Many SCM commands can be executed by using buttons at the bottom of the repositories organizer. Which buttons are available and active depends on your selection in the navigator pane of the repositories organizer. For example, Figure 12-6 shows the buttons at the bottom of the repositories organizer when a git working copy is selected.
Update and commit operations are recorded in the log navigator. Select a log to see the individual steps of that operation in the log viewer.
Keep Track of Your Files’ SCM Status
You can keep track of your files’ SCM status in the project navigator. SCM status is shown as a badge next to the file name (Figure 12-7), as follows:
Badges propagate up to the highest container so you can see the source control status of the whole workspace regardless of the disclosure level. Detailed SCM status is shown in the Source Control area of the File inspector in the utility pane.
Work with Git and Subversion
Common source control tasks include setting up a repository, checking files out of and in to a repository, reconciling different versions of a file, and using branches to isolate risky changes to your code.
Set Up Git Version Control When You Create a New Project
As described in “Create a Git Repository For Your New Project,” Xcode creates a Git repository for a new project if you select the Source Control option in the Save As dialog. When you do so, Xcode adds a hidden file (named
.git) to the folder containing the project. That file contains all the information Git needs to keep track of the files in the project and the changes made to them. Xcode also performs an initial commit of the files in the folder. Any time you add files to your project or modify any of the files in the project, you need to commit them to add them to the repository (see “Commit Files to Add Them to a Repository”).
Add Git or Subversion Version Control to an Existing Project
You may need to create your own repository if, for example, you want to start managing an existing project under source control. You can use command-line tools to set up a Git or Subversion repository. The necessary tools are installed during Xcode installation, if you select the System Tools package.
Use command-line commands to set up a Git repository for an existing project.
Use command-line commands to set up a Subversion repository.
Clone or Check Out a Copy of a Project to Use Locally
If you or your work group have a Subversion server or a master copy of a Git repository shared on a file server, you can create a local working copy by checking out (Subversion) or cloning (Git) a copy of the master. You can then use the source control commands in Xcode to commit changes to your local copy, update your local copy from the master copy, and push your changes up to the master copy (for Git). Note that it is not necessary to clone a copy of a local Git repository, as in this case the master copy is also your working copy.
Check out or clone a repository to create a copy on your local system.
Add an Existing SCM Working Copy of a Project to Xcode
If you have a working copy of a project that was checked out of Subversion or cloned from Git using the command line or another tool, you can add it to your Xcode SCM repository support. To do so, click the Add button (+) at the bottom of the navigation pane in the repository organizer and choose Add Working Copy.
Create a Branch to Isolate Risky Changes
After you’ve been working on a project for a while, you are likely to have a body of reliable, stable code. Although a repository enables you to revert to an earlier version if you destabilize your program while attempting to add a new feature, you might want to be able to work on the new feature while still maintaining your stable body of code. That way, one of the members of your team can (for example) work on refining the user interface or fixing minor bugs while another team member works on a risky new feature. In order to implement such a scheme, most source control systems (including Git and Subversion) allow you to create a branch, which is another copy of your code that you can modify independently of the original body of code (or of any other branches). You can base a branch on the trunk or on any other branch.
Subversion keeps all the information about branches, submissions, updates, and so forth on the server. You need to be connected to the server to see any of this information in Xcode. In Git, when you clone a repository, you get a copy of all of the metadata associated with the repository as well as copies of all the existing branches. To see the structure of a Subversion repository without checking out a working copy, or to see the branches of a remote Git repository so you can clone an individual branch, use the Add Repository menu item (see “Clone a Specific Branch”).
Create a branch in a repository to isolate specific aspects of your software development efforts and to work in parallel with other developers.
Create a branch in a repository to isolate specific aspects of your software development efforts and to work in parallel with other developers.
Switch to another branch of a repository to work on a different line of code development or to prepare for a branch merge.
Clone a Specific Branch
Rather than clone an entire remote repository, you might want to clone only a specific branch. Use the Add Repository command for this purpose. You can also use the Add Repository command to browse a Subversion repository without creating a working copy.
Open the repositories organizer, click the Add button (+) at the bottom of the navigator pane, and choose Add Repository.
In the Add a Repository dialog, fill in a name for your local working copy and the location of the remote repository. Click Add.
Select the branch for which you want a local working copy and click Clone.
Add a Folder to a Subversion Repository
When you select a folder such as Trunk for a Subversion repository in the navigation pane of the repositories organizer, or any folder in the outline view of a Subversion repository, a New Directory button is available at the bottom of the window. This button creates a new directory, represented as a folder in the organizer. If no folder is selected in the outline view, the folder is created at the same level as the top-level folders in the outline view. If a folder in the outline view is selected, the new folder is created inside that folder.
Once you create a new Subversion directory, you can add files to it.
Add nonproject files to a repository folder created with the repositories organizer.
Commit Files to Add Them to a Repository
When you edit a file, it is changed locally but the changes are not included in the source control repository. To add the changes to the repository, you must commit the file. You must save the file before you can commit it, but note that saving a file is not the same as committing it to source control—you must explicitly commit the file. To see which files have been modified locally but not committed, look for the M badge next to the filename in the project navigator. (New files that have never been committed to source control have the A badge. Files that are not under source control have a question mark badge.) You can use the SCM status filter at the bottom of the project navigator to display only files with SCM status.
Commit changed files to ensure that those changes are preserved and managed as part of a repository.
Reconcile Different Branches
When you’re ready to merge the code in a separate branch back into the main branch, or when you want to combine the code in any two branches, you can use the merge facility of your source control system to reconcile differences between the branches.
Merge two branches to combine the code in them and reconcile differences between them.
Update Your Working Copy from a Remote Repository
When two or more people are working on a automata project, from time to time you need to synchronize your working copy with changes made in the remote repository. You use the Pull command in Git or the Update command in Subversion to do so.
Use a pull operation to update local files with changes from a shared or remote Git repository to ensure that your local repository is up to date.
Update your local working copy with changes from a shared or remote Subversion repository to ensure that your local copy is up to date.
Send Your Working Copy to the Remote Git Repository
If you’re using a remote Git repository, when you’re ready to share your work with the other members of your team, you can push your files back to the remote repository. (If you’re using Subversion, the commit command updates the remote repository.) If you cloned your working copy from a repository, you should see the remote repository in the repository organizer. Before performing a push, you have to save and commit all changes and execute the Pull command to reconcile any differences between your version and the one on the server. Then, choose File > Source Control > Push.
Save Internal Project Files in Repositories
In Xcode 4.1 and later, you can use repositories to view internal project files (for example, schemes and user interface settings) when looking at SCM details in the SCM commit and update workflows. You can use this facility to save and keep track of versions of project files in the same way as you save and keep track of source files. Figure 12-8 shows a commit dialog displaying two versions of a scheme.
You use the Xcode version editor to compare revisions. To compare any two versions of a file under source control in a side-by-side view, select the file in the project navigator and click the version editor button (). Use the jump bar underneath either editor pane to select the version of the file to compare with the one in the other pane (Figure 12-9). You can select any committed version of that file in any branch.
Buttons under the version editor () allow you to show a file comparison and timeline, change logs for the file, or individual change annotations (“blame”) for each line of the file.
You can edit the current working copy of the file in the version editor and you can copy code from an older version and paste it into the current version.
Select Specific Revisions
Click the timeline icon () in the center column to show a visual timeline of all repository versions; use the sliders to control which version is displayed on each side.
Use the version timeline to choose file versions based on their chronological order.
Review Individual Changes
In blame mode, the current revision of the file is displayed along with the last revision that modified each line of the file.
Click the blame mode button at the bottom of the version editor.
Each blame mode entry is aligned with the line in the file where the change was made. The entry includes the name of the person who committed the change, the date, and the ID of the commit.
View All Revisions Chronologically
To review all revisions to a file listed in chronological order, use Log mode. Each change is listed individually, and you can click the arrow next to the log entry to see the change displayed in Comparison mode.
Distribute Your App
Archives package your products for distribution. Use archives to distribute your program through your own distribution mechanism or to submit an application to iTunes Connect for inclusion in the iOS or Mac app store. To build your project and save the resulting application or a disk image of the set of build products, choose Product > Archive. Xcode creates an archive of your project using the build configuration and name you specified in the Archive pane of the scheme editor (Figure 3-2) and saves the archive in the location specified in the Locations pane of Xcode preferences.
To see the archives for your project, open the archives organizer (Figure 12-10). You can add a comment by clicking in the text field in the Comment column.
For details on how to use archives to distribute your products, see “Distribute Your App.”
© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)