Source trees define folder locations where shared source files reside. There is no restriction on where these are located or on how the source files are maintained. An earlier chapter mentioned a suite of application projects that all need to include the same corporate artwork; a source tree folder could be defined for those graphic files.

Any number of projects can refer to the files in a source tree's location. Changing the location of the source tree changes all of the references in all of your projects simultaneously. For example, if the graphics art department sends you a new CD with updated artwork, all you have to do is pop the disc into the CD-ROM drive, point that source tree to a folder on the CD, and rebuild your projects. Source tree locations are defined individually for each user, so a different programmer can use the same project with source tree locations specific to their environment.

Source control, often referred to as version control, is the principal method of tracking historical changes made to source files and sharing source files among a group of developers. It provides three important services:

The first service stores the master copy of all source files in a central repository. Changes made to a source file by one developer are sent back to the central repository, where those changes can then be distributed to other developers. This allows multiple developers to work on the same project in a rational manner.

The second service provides a degree of security, protecting against accidental damage to local project files and providing a point for centralized backups.

The third service, and probably the most important, keeps a record of all changes made to a project over time. Developers can quickly see exactly what has changed in each file, and review comments made by the programmer that explain why. Source control can also be used like a time machine. You can reconstruct the state of a project at any point during its lifetime. You don't need to archive a copy of your entire project at every point in its development. For example, if you're working on version 1.6 of your application, but suddenly need to debug version 1.2, simply query the source control system for a copy of your project as it existed on the day you finished version 1.2.

Source trees and source control serve different needs and each is designed to solve a different problem. Some aspects overlap, but generally they complement each other. They can be used independently or in combination. For example, a project from one source control repository can refer to files in a source tree that's being maintained in a different source control repository. What source file sharing and control techniques you employ will depend entirely on your needs and work environment.

Open the Source Tree tab of the Xcode Preferences, as shown in Figure 21-1.

Figure 21-1. FIGURE 21-1

Click the + button below the list to define a new source tree. Give it a symbolic name or key, a display name, and a path where the tree can be accessed on your system.

The symbolic name is how Xcode identifies a source tree. It should be simple and must be unique. I prefer to use so-called "reverse DNS" notation, like com.wiley.proXcode3.shared. The symbolic name is stored in each project file reference that's relative to a source tree. Any other developers you share the project with must define a source tree with the exact same symbolic name, or their project file references will be broken.

The display name is how the source tree will appear in the Xcode user interface. It can be anything you want, should be descriptive, and can be changed later. Different users can have different display names for the same source tree.

To delete a tree, select it in the list and click the – button.

After you've defined a tree, use it to refer to source files in your project. The source trees you've defined automatically appear in all dialogs that add an existing file, folder, or framework to your project, as shown in Figure 21-2.

Figure 21-2. FIGURE 21-2

Source trees also appear in the reference section of every source file's Info window, as shown in Figure 21-3. You can make any source file's path type relative to any source tree that you've defined. If you are reorganizing a project to use source trees, select a group of source file references and change their path type to the new source tree as a group. Typically, you would set the path type of a group folder to that of a source tree, and leave the members of that group as Relative to Enclosing Group.

Figure 21-3. FIGURE 21-3

If you open a project that refers to a source tree that is not defined on your system, Xcode attempts to locate the file at the same path it used the last time that tree was defined. If this path is wrong, the file will turn red, indicating that it cannot be located. Define the required source tree, then close and reopen the project to resolve the reference.

To redefine your source trees, close all projects, redefine your source trees, and open the projects again. Xcode resolves the source file paths using the new source tree locations.

Using source control through Xcode can be broadly divided into three phases:

The next section describes how to define a repository. The sections starting with "Browsing Repositories" describe how to view the contents of a repository and check out an Xcode project. Once you have a project checked out under source control, all of your subsequent interaction will be through the project, described starting in the "Source Control Interface" section.

As mentioned earlier, a repository is a centralized collection of managed files. Before you can use source control, you must define the location and characteristics of the repository, or repositories, that you want to use. Just like source trees, each developer must create an equivalent repository definition if they expect to share the same set of managed files. The definitions might be the same or different. For example, you might create a source control repository on your local drive. Later, you decide to collaborate with another programmer and open access to that repository via the Internet. Your repository definition would still refer to your local file system while his would refer to a remote repository.

All of the repositories you use are defined in the SCM tab of the Xcode Preferences (Command+,), as shown in Figure 21-4.

Figure 21-4. FIGURE 21-4

Each repository definition has three parts:

Click the + button below the list of repositories to define a new repository. A dialog sheet will prompt you for a repository name and the client that will be used to access the repository. The client you choose — SVN, Subversion, or Perforce — will determine what settings are needed to define the repository. The name identifies the repository definition in Xcode and can be changed later.

Clicking OK creates a new repository definition. Fill in the settings as required. What those settings are is entirely dependent on how the repository was created and where it resides. If you didn't set up the repository, contact the administrator of the repository for the correct settings. In some situations they may need to create a user account and password for you, or you might have to register an SSH key.

For Subversion repositories, the settings to configure are:

The URL setting and the other settings mirror each other. Whatever you enter for the other settings is combined into a single URL, and whatever you enter into the URL setting is decomposed into its individual settings. If your Subversion administrator or open source project provides an URL to the repository, paste that into the URL field; Xcode will fill in the settings for you. Conversely, if you need an URL to access your repository via the source control client or some third-party tool, Xcode has already constructed it for you. Copy the URL and paste it into your client.

The path setting defines the top-level directory within the repository where this repository definition is anchored. You may create a single repository definition that points to the top-level directory in the repository, or you can define multiple repository definitions that point to individual subdirectories within a single repository. Which you choose is a matter of personal preference, style, and any security restrictions that might be in place. I tend to define a repository definition for each set of related projects, even if more than one set shares a single repository. When I browse that repository, I'm not distracted by unrelated directories.

The path setting might also describe the location of the repository itself. That is, the first part of the path is the location of the repository database, and any remainder is a path within the repository structure. It's not obvious where the path to the repository ends and the path within the repository begins, but it's usually immaterial.

Before running off to use your newly defined repository, take a quick look at the Options tab of the SCM preferences pane, as shown in Figure 21-5.

Figure 21-5. FIGURE 21-5

I recommend checking the Configure SCM Automatically option. When you check out a project via source control, the working files are under the influence of the source control system — but the project will not necessarily be configured to use source control. Turning this option on allows Xcode to configure your project automatically to use source control when it detects that it's appropriate. Otherwise, you'll have to configure the project manually as described later in the "Configuring a Project for Source Control" section.

The Save File Before SCM Operations automatically saves your files to disk before performing any source control action (check in, check out, and so on). I recommend setting this option for the same reasons I recommend setting the Always Save Files option in the Building pane.

The remaining options control how files are compared in Xcode. Most often this is when you want to compare the working version of your file with a different version in the repository. Some of these settings also apply to comparing files in snapshots.

The Comparisons Handling option selects the application and layout used when comparing two files. Xcode will obtain both versions of the file and pass them to the application for side-by-side comparison. Your choices are:

Using Xcode is the fastest, but also the least capable. Xcode's built-in comparison window is adequate for comparing two files but is awkward if you want to selectively replace individual sections of your working files with those from the revision.

The FileMerge application is a standalone file comparison utility included in the Xcode Development Tools package. If you own Bare Bone's BBEdit application, you can use its excellent file comparison interface instead.

The Other setting lets you select any third-party comparison tool that accepts two filename arguments and compares them.

Xcode can also compare files using the traditional POSIX diff tool. The settings under Differencing define some format arguments that Xcode will pass to diff. See the diff man page for a complete description of these settings.

If access to your repositories requires a private SSH encryption key, those keys will appear in the SSH tab of the SCM preferences pane.

The keys that appear here will be any keys installed in your account's .ssh directory and any SSH keys in your keychain.

You can add security by entering a passphrase for one or more keys. Xcode will prompt you for this phrase whenever it needs to use the selected SSH key. Leave the passphrase field empty to bypass the prompt.

If you're setting up Subversion for your own personal use, or just want to try out source control, the simplest solution is to create a local repository. The following Terminal command creates an empty repository named Subversion in your Documents folder:

svnadmin create ~/Documents/Subversion

Now go to Xcode's SCM preferences pane and create a repository definition, as described in the "Defining a Repository" section. For the example given, your settings will be:

You can elect to use a different repository name and location as you see fit. Note that you can't use a user-relative path (~/Documents/...) in the repository definition setting.

Ideally, your source control repository should contain only the files needed to build your project. This includes your project document, source files, resources files, and so on. It should not contain any intermediate products (object files, compiled data models, help indexes), superficial files (code sense index, disassembly files), or any final products (applications, bundles). There are a number of techniques for excluding these so-called noise files from your repository.

Xcode's default folder organization conveniently places all intermediate files, project indexes, and products inside the project's build folder. Wow, that makes it easy! All you have to do is leave the build folder out of your repository and 98 percent of your noise files have been eliminated. There are basically two approaches to this, and which one you take determines whether you address other noise files at the same time.

### Set global-ignores to a set of whitespace-delimited globs
### which Subversion will ignore in its 'status' output.
# global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store
global-ignores = .DS_Store build *.mode* *~.nib *~

Once you have one or more repositories defined, you can open the Repositories window by choosing the SCM

Figure 21-6. FIGURE 21-6

On the left are the repositories that you've defined. Select one and the browser in the upper pane will let you navigate through the most recent content of each repository directory. The lower pane shows a running log of the actual SCM commands that Xcode is issuing in order to perform whatever actions you request.

The Reload toolbar button re-fetches the information from the repository and refreshes the display. The Configure button jumps to the SCM pane of the Xcode preferences — the one you've been using in the previous sections.

You don't typically spend a lot of time in the repositories window. The significant actions you'll perform here are checking out and importing/exporting entire projects, which are all described in subsequent sections. Once you do that, almost everything else is done through the project.

The repository window does provide a basic set of repository commands. Besides perusing the contents of a repository, you can:

These commands are all self-explanatory. Just remember that you're modifying the content of the repository, not the files in your file system.

While the command set looks simple, there's actually a lot you can do with it. If you've taken time to skim the Version Control with Subversion book, you already know that Subversion doesn't use metadata (a.k.a., tags) to demarcate releases or branches. Instead, it uses a convention of subdirectories. The main development files are stored in a trunk directory. Releases are defined by copying the entire trunk into a subdirectory of the tags directory. Similarly, copying a project folder into a branches subdirectory creates a branch. Thus, tagging milestones and branching are simply matters of copying one repository directory into another.

Speaking of subdirectory conventions, if you've just created a new Subversion repository for a single project, you'll want to start by creating a trunk subdirectory, as shown in Figure 21-7. You can create tags and branches directories when you need them.

Figure 21-7. FIGURE 21-7

When you create the subdirectory, Xcode prompts you for a comment. Every change to the repository is recorded, annotated with an explanation that you provide, and no information is actually destroyed. Deleting a repository folder doesn't delete it from the repository; it simply means that, in the most current version of the repository, the directory no longer exists. Its previous incarnations are still, and will always be, available.

If you plan to store multiple projects in a single repository, I recommend creating top-level folders for each project, and then creating trunk, tags, and branches subfolders within each project folder. Other developers prefer to create single top-level trunk, tags, and branches directories and then have subdirectories for each project within those. There are advantages and disadvantages to each. Consult the Version Control with Subversion book before embarking on any major repository design.

So far, you've created a repository, defined it in Xcode, and can browse the repository in the repository window. Now you want to place your project under source control. The basic steps for putting a project under source control are:

The first two steps are required because placing a project under source control presents a bit of a chicken-and-egg problem; a project can't be under source control until it's been checked out of the repository, and it can't add files to a repository until the project is under source control. To get around this conundrum, you begin by importing a project into the repository.

Importing takes a project folder — actually any arbitrary file or folder — that is not under source control and adds it to the repository. You can do this with anything at any time, but the most common reason is to get a project into source control in the first place.

In the repositories window, select the repository directory where you want the project folder copied into the repository, or select just the repository to import it into the repository's root directory. Click the Import button in the toolbar and choose the project folder to import, as shown in Figure 21-8.

Figure 21-8. FIGURE 21-8

Click the Import button and Xcode copies the entire project directory into the repository as a new subdirectory.

You might think that all you have to do now is flip a switch in the project and start using source control, but you're not there yet. You must now check the project back out of the repository — only then do you have a set of working files that are under source control.

Checking out a project (or any set of files) from source control creates a working copy of the managed files in the repository. Working files are special. The source control system maintains additional information about the file and its relationship to its managed counterpart in the repository. Before you can use source control from within an Xcode project you must first check the project out.

Somewhat counterintuitively, you must check out your project to someplace other than its original project folder. Either checkout the project to a new location, or first trash, move, or rename the original project folder. I wouldn't delete it yet — just in case something goes wrong.

In the repositories window, select the repository folder you want to check out. If you want to check out the entire repository, select only the repository. Click the Checkout button and select a location where the working project files will be written, as shown in Figure 21-9.

Figure 21-9. FIGURE 21-9

The default name for the enclosing folder will be the repository or folder you're checking out. If you want to change it, do so now. The reasons you might want to change it are varied, but one common reason is that Xcode and traditional Subversion repositories don't use the same directory structure.

In an "old school" Subversion repository, a project folder named MyProject would appear in the repository as /MyProject/trunk, /MyProject/tags, and /MyProject/branches. When you check out trunk, the folder "trunk" becomes the project folder. This is probably not what you wanted. The solution is to check out trunk from the repository, but rename it to MyProject before clicking Checkout.

All of the files in your project have now been checked out, and all of the working copies of those files are under source control. You can now skip ahead to the "Configuring a Project for Source Control" section.

Exporting a project is the inverse of importing one, and is the complement to checking one out. Exporting a project produces copies of the managed files in the repository, but does not create working files. In other words, it simply copies the files in the repository to your local drive without any of the source control metadata required to manage them. An exported project is not under source control.

Use the export command when you simply want to obtain an unencumbered copy of a project or some files. For example, let's say there's an open source project that you're interested in looking at. You're not a contributor to the project (yet), and have no need to track changes or compare files to older revisions. You would use the export command to fetch a copy of the project sans any source control information or ties to its originating repository.

Similarly, you might be working on version 1.6 of your application and need to build version 1.2. If you have no intention of creating a new branch or reviewing changes, simply export the project from the 1.2 tag directory into a new folder and build it.

The last step is to configure the project to use source control. Open the Info window for the project group, choose the Project

Figure 21-10. FIGURE 21-10

This portion of the project's Info window describes the project's name, location, and the roots of the project. The project roots is a list of directories that encompass the assets of the project. For most projects, everything is contained within the project's folder, which appears in the list as <Project File Directory>.

Because you just checked the entire project out from source control, the first order of business is to enable source control for the project folder. Click the Configure Roots & SCM button. A sheet appears listing all of the roots of this project and the source control repository each is associated with. For now, all you are interested in is the repository for your <Project File Directory>. If the Configure SCM Automatically preference is on and Xcode was able to unambiguously determine which repository the project came from, the repository for your project may already be configured. If that's the case, you can skip to the next section and start using source control from within your project.

If SCM has not been configured for your project, do so now. First, select the source control management system you're using from the pop-up menu at the top of the sheet. All of your project roots must use the same source control system. For example, you can't have one root managed by Subversion and another by Perforce.

Now select the repository from where your project was checked out, as shown in Figure 21-11. Here, Xcode plays matchmaker; it compares the source control information in your working directories with the definitions of your repositories, and suggests which repositories appear to be valid choices.

Figure 21-11. FIGURE 21-11

Click OK to accept your changes. Once at least one project root has been configured to use source control, the source control interface within Xcode is enabled. If this is a single, self-contained project, move on to the "Source Control Interface" section.

Setting a root's repository to none disables source control management for that directory tree.

The Configure SCM Repositories command at the bottom of the menu jumps to the SCM pane of the Xcode preferences, which you used at the beginning of this chapter to define the repository.

A single project can administer source control in multiple directory trees by defining additional project roots. As a rule, you should always define the repository for your project's folder. If your project incorporates assets outside your project folder, those assets are under source control, and you want to manage them from within your project, add each top-level directory as a project root by following these steps:

Naturally, if your additional root directories were checked out of repositories other than the one your project is in, you'll first have to define those repositories in the SCM pane of the Xcode preferences.

There are a number of scenarios in which a project would have multiple roots:

The paths to your project roots are all always relative to your project folder. If you add roots to a project and then change anything that invalidates this relationship — relocating a source tree, for example — the source control features for those files will simply stop working until you update your root paths.

Interaction with source control in Xcode is done primarily through the commands in the SCM (Source Control Manager) menu and the SCM tab in various Info windows. File-specific commands apply to either the selected file or group of files in the project window, or to the currently active editor pane. This chapter often refers to "selecting a file" before executing one of the SCM commands. It's implied that the same command would apply equally to the file in the active editor pane.

As soon as you enable source control for a project, a new SCM tab appears in the project's Info window, as shown in Figure 21-12. A similar SCM tab appears in the Info window of all project files that are under source control.

Figure 21-12. FIGURE 21-12

The State field shows the current status of the project document or source file. This tells you if the file is up-to-date (that is, it is the same as the most recent version of the file stored in the repository), if it has been modified locally, if it needs to be updated, and so on. The Local field shows the version of the file that you last checked out of the repository — also called the base revision — and the Latest field shows the most recent version stored in the repository.

Below the file's status is the list of revisions. Each revision has a number, an author, a date, and a comment. Select one to show the full details of the revision in the lower pane of the window.

Use the four buttons below the detailed description to update or see the annotation view of a selected revision in the list. You can select one revision in the list and compare or diff it against the working copy of the file, or you can select two revisions in the list and compare them to each other. All of these commands are explained later in this chapter.

The SCM smart group in the Groups & Files pane lists the pending source control operations for the project, as shown in Figure 21-13. The details pane for the SCM smart group displays an additional source control status column — the left column, next to the document icons shown in Figure 21-13.

Figure 21-13. FIGURE 21-13

The SCM column shows the status of any pending source control actions or conflicts. When you make changes to a project in Xcode, you are only changing the local copy of the project. None of the changes you make propagate back to the source control repository until you commit those changes. As you work on the project — adding, removing, and editing files — Xcode keeps track of all of the changes that you've made. These appear in the SCM smart group. When you commit your changes, Xcode executes the pending actions in the SCM smart group, dutifully adding, removing, and modifying files in the repository to mirror those in your project.

You can also view the SCM status of files in any other details pane by enabling the SCM column, as shown in Figure 21-14. Right/Control+click the column titles to show or hide the SCM column.

Figure 21-14. FIGURE 21-14

The SCM column contains a single character that indicates the status or pending SCM operation of each file, as described in the following table:

Choose the SCM

Double-clicking the SCM smart group or choosing the SCM

Figure 21-15. FIGURE 21-15

This window shows more detailed information about the SCM status of each file. Like the SCM smart group and details pane, it lists the name and status of each file. It also lists:

In the lower-left corner of the window are a small log button and a pop-up menu. Clicking the log button toggles the display of the SCM transaction log, as shown in the middle of Figure 21-15. The log shows the commands issued to, and the results from, the source control client used for this project.

The menu button next the log button selects one of three display modes for the SCM window:

The All setting displays all of the files in your project. The Interesting and Flat settings show only pending SCM actions (modified files, new files, files that need updating, pending deletes). The Interesting choice organizes items hierarchically, whereas Flat lists them alphabetically.

At the bottom of the window is a standard editor pane, which you can collapse by dragging the pane divider to the bottom of the window.

No change occurs in the repository until you commit it. Choose the SCM

Committing individual files is usually safe, as long as you are sure the changes being checked in will be valid in the absence of other changes that you have yet to commit. Whenever a commit includes the addition or removal of files, you should endeavor to commit those actions along with the corresponding changes made to the project document. The safest action in this situation is to commit the entire project. The "Source Control and the Project Document" section explains this in more detail.

When you commit a change, Xcode prompts you for a comment, as shown in Figure 21-16. You should be descriptive and complete. The comments you enter will be attached to every transaction required to complete the commit. Source control comments are another form of documentation. The modifications made in your project are only comprehensible if you explain what you changed and why, both clearly and accurately.

Figure 21-16. FIGURE 21-16

If, for whatever reason, you decide to abandon the changes that you've made to a file, you can discard them and revert to the base revision — the version you originally checked out from source control. This is not necessarily the latest version of the file in the repository. When you discard changes to a file, Xcode presents the warning dialog shown in Figure 21-17.

Figure 21-17. FIGURE 21-17

You can't discard changes by simply checking out a different revision of the file (as discussed in the "Updating Files" section). Xcode won't overwrite your local file with a revision from the repository until you explicitly discard your changes. This prevents you from accidentally wiping out hours, if not days, worth of work. If you do try to update a modified file, you will only end up changing the base revision associated with that file. This action will either associate the file with the latest revision (containing as-yet uncommitted changes), or it will put the file in conflict mode. The "Resolving Conflicts" section explains how to merge conflicting changes.

Adding a file to the project involves first adding the file to the project and then adding it to the repository. How you add the file to the project is entirely up to you. You can use any method discussed in the book so far for adding an existing file or creating a new one. (Chapter 5 contains detailed instructions on adding files to a project.) After the file is added to the project, the SCM status of the file may be ?, -, or blank, indicating that the file, or the folder that contains the file, is unknown to the repository.

In the case of an unknown file (?), select the file in the source group or details pane and choose the SCM

If you've created files inside a folder that is not in the repository, you'll need to add that folder to the repository before Xcode will pay any attention to its files. Use one of these two methods to add a folder to your project:

If you add just the folder, the status of the files in that folder will change to ?, indicating that Xcode now sees them as unknown files. You can now use Xcode to add those files to the repository.

Whenever you make source control changes using the client tool, the repositories window, or through any other means outside the project, choose SCM

Deleting a file requires that you remove it from both the project and the source control repository. When you delete a file reference from a project, Xcode gives you the option of removing just the file reference or physically deleting the source file. If you choose the latter, and the file exists in the repository, Xcode presents a second dialog, shown in Figure 21-18.

Figure 21-18. FIGURE 21-18

If you choose to remove the file, a repository remove action is added to the SCM smart group and the file is removed from the repository when the action is committed. If you choose not to remove the file, the file is deleted locally but remains in the repository. If you choose to remove the repository file as well, the project displays a grey (disabled) reference to the file in the project, indicating a reference to a file that has been deleted. After the action has been committed and the file in the repository has been removed, the phantom reference to the deleted file will disappear.

Renaming a file in a source control repository is as simple as renaming the source item in your project. In the repository, the action consists of removing an existing file and adding a new file with a different name. When you rename a source file in Xcode, it presents the dialog box shown in Figure 21-19.

Figure 21-19. FIGURE 21-19

If you choose to rename the file in the repository, Xcode creates two SCM actions: the first action removes the old file, and the second action adds the same file back into the repository with its new name. Commit these two actions together to complete the rename.

When a newer version of a file exists in the repository, Xcode displays a U as the SCM status for the file. This indicates that you must update this file if you want the latest version.

If you want to retrieve the latest version of a file, select one or more files in the project window and choose the SCM

You can also retrieve an earlier version of a file. Select a single file and choose the SCM

Figure 21-20. FIGURE 21-20

You can also update (check out) multiple files at or near a specific revision using the SCM

Note

When you revert to an older revision of a file, the SCM information about that file may revert as well. This depends on which source control system you are using. If it does revert, the file's SCM history appears to be current when it isn't, listing only the revision information up to the revision you retrieved. The file does not display a U indicating that a newer version of the file is available. Use the SCM

You can bring an entire project up to date by selecting the project group in the Groups & Files pane of the project window and choosing the SCM

You can compare the files in your project with other revisions using the SCM

Choose the file you want to compare, and then choose the Latest, Base, Revisions, or Specific Revision command from either the Compare With or Diff With submenu:

If your working file is already the same as the latest or base revision, the appropriate commands are disabled. If you want to browse the revisions and their comments, choose the Revisions command.

All of the various Compare With commands use the comparison utility selected in the SCM preferences pane (see the "Source Control Options" section, earlier in this chapter). I recommend using FileMerge or BBEdit (if you own it). This chapter demonstrates using FileMerge.

You've already used Xcode's built-in comparison editor when comparing files in snapshots. This choice has the advantage of being fast, and it doesn't launch another application, but Xcode's tool is significantly limited in its ability to selectively borrow and undo changes from the other file, which I feel makes it more of a hindrance when working with source control.

When launched by Xcode, FileMerge shows a side-by-side comparison of the two files, as shown in Figure 21-21.

Figure 21-21. FIGURE 21-21

The window graphically illustrates the changes made between the two files. In the example shown in Figure 21-21, four groups of changes (visible in the window) were detected. Scroll through the file to see other differences, or use the Find

The Compare With commands give you one additional command not available in the Diff With submenu. SCM

If you use one of the Diff With commands, Xcode opens a text window that displays the output of the diff command, as shown in Figure 21-22. The SCM options, described in the "Source Control Options" section, let you choose a number of diff formatting options.

Figure 21-22. FIGURE 21-22

The file comparison and merge utilities can also be used to combine the differences between two files. This is useful in a number of situations. One of the very liberating aspects of working with a source control system is the freedom to make experimental changes to your code. If you decide that you don't like the changes, you can compare your working copy with an earlier version of your source code stored in the repository. The file comparison utilities let you "undo" your changes by selectively moving blocks of code from the earlier version back into your working one. This is a much more surgical correction than merely discarding all of the changes in a file.

Both the FileMerge utility and BBEdit's compare files function place both old and new versions of the file on the screen side by side. Both highlight the blocks of text that differ between the two. For each difference, you can choose whether to keep it as it is or revert to the alternative version in the other file.

The FileMerge utility does this with a merged file pane at the bottom of the window. The merged file contains all of the common elements of both files and selected blocks of text from either the right or the left file pane. To create the merged version, select each difference and choose what to include in the merged version from the following table:

Using ↑ the and ↓ keys, navigate to the next change and then use ← or → to select which change you want to keep. When you are finished, save the file as a new document, or replace one of the existing files with the merged version.

BBEdit works a little differently. In BBEdit there is no third file. It presents the two files in a separate editor windows (see Figure 21-23). A third window displays the list of differences between the two. Select a difference to highlight the corresponding regions in both files. From the differences window, you can replace the block in either file with the contents of the other using the Apply to New or Apply to Old button. When you are done, save the modified files back to their original locations, or use the File

Figure 21-23. FIGURE 21-23

Another way of seeing how a file has evolved is to look at its annotation view. Select a file and choose a command from the SCM

The annotated listing of a file, shown in Figure 21-24, displays the revision number in which each line was added and the author of that line. In this example, you can see that the maxPrime property was added by daphne in revision 10 of the file. The rest of the file was from the original when james first checked it in. Annotated listings do not show lines that have been removed, nor do they show the previous versions of lines that have been altered.

Figure 21-24. FIGURE 21-24

When a newer revision of a file appears in the repository, and you have modified that same file locally, the SCM status of the file changes to C to indicate a conflict. Before committing your version of the file, you need to join it with the latest revision checked into the repository to add, combine, or discard the changes made by the other developer with yours — or not.

When a conflict occurs, you have two choices. You can abandon the changes that you've made, replacing them wholesale with the changes made in the latest revision of the file. To abandon your changes, select the conflicting file and choose SCM

The other choice is to merge your changes manually with those checked into source control. Select the file and choose the SCM

If the changes conflict, the overlapping sections of the file that are different are noted by comments, as shown in Figure 21-25. The SCM status for the file changes to a green C, indicating that the file is in conflict resolution.

Figure 21-25. FIGURE 21-25

Edit the file, removing or combining the differences, until you have successfully integrated your changes with those of the other developer. If you are using Subversion, choose the SCM

You can now commit your combined changes, creating a new revision that contains the changes from both versions. When you commit your merged file, document your changes and the fact that these were combined with changes from the previous revision.

At some point, you may find yourself working on a project without access to the source control system or repository from which it was checked out. For example, you might have moved the project to another computer, or are using it on laptop that is no longer in contact with your source control server.

You can temporarily disable SCM control of your project using the SCM

You can continue to edit, add, and rename files in your project. These actions simply create pending SCM actions. When you are back in touch with the source control repository, restore SCM functionality by choosing the SCM

The project document requires some special handing when a project is under the control of a source control system. The project document is a package containing several files. The project.pbxproj file contains the structure and common settings of the project document bundle. This includes source file references, target definitions, and build settings. If you change any of these values, the project.pbxproj file appears in the SCM smart group as a modified file, as shown in Figure 21-26. The changes made to the project won't be stored in the repository until you commit this file.

Figure 21-26. FIGURE 21-26

Each user has a personalized settings file in the project document package. These were described in the "Excluding Other Noise Files" section. When, and whether, you check these files into the repository is up to you. Being part of the project document, modifications to these files will make it appear that the project document has changed — unless they are explicitly excluded from the repository. Here are some points to keep in mind: