Save and Revert Changes to Projects

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.

To assign address book information to identities in the organizer

1. Click a repository in the navigation pane of the repositories organizer.

2. Click the icon well next to the commit ID number.

   

3. 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.

To view changes for a specific commit version

 

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.

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.

To set up a Git repository from the command line

 

Use command-line commands to set up a Subversion repository.

To set up a Subversion repository from the command line

 

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.

To check out or clone a repository

 

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.

To create a branch in a Git repository

 

Create a branch in a repository to isolate specific aspects of your software development efforts and to work in parallel with other developers.

To create a branch in a Subversion repository

 

Switch to another branch of a repository to work on a different line of code development or to prepare for a branch merge.

To switch branches

 

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.

To clone specific branches of a remote repository

1. Open the repositories organizer, click the Add button (+) at the bottom of the navigator pane, and choose Add Repository.

2. In the Add a Repository dialog, fill in a name for your local working copy and the location of the remote repository. Click Add.

   

3. 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.

To add files to a new Subversion directory

 

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.

To commit files to 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.

To merge two branches

 

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.

To pull changes from a remote Git repository

 

Update your local working copy with changes from a shared or remote Subversion repository to ensure that your local copy is up to date.

To update changes from a remote Subversion repository

 

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.

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.

To compare versions of a file with the timeline

 

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.

To see who is responsible for the last revision of a line of code

• 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.

To review all revisions to a file

• Click the log mode button at the bottom of the version editor.

  All the log entries for the file are listed in chronological order and include the name of the person who committed the change, the date, the ID of the commit, and the commit comments.