If you're like me, you hate to throw away code. Most code, especially the stuff that works, is a hard-won commodity that represents time, effort, expertise, and creativity. The best way to improve your code, however, is to experiment with new approaches — which often means abandoning or discarding the code you've already written. Making copies of your source files or saving snippets of old code as comments is both awkward and time consuming. Enter snapshots. Snapshots let you have it both ways: you can keep your existing code while simultaneously replacing it with new, experimental code.
In simple terms, a snapshot is an archived copy of the source files in your project. It quickly preserves their current state so you are free to make changes to your project — even radical ones — secure in the knowledge that you can always revert back to the saved version at any time. You can make as many snapshots as you like. You can easily see what changes you've made, as shown in Figure 11-1, by comparing your working project files to those in a snapshot. You can revert your changes to any previous snapshot on a change-by-change basis, by file, or perform a wholesale restore of the entire project.
Snapshots encourage experimentation by making it easy to save and contrast existing code with new code. There's very little risk in rewriting a collection loop to improve performance when Xcode will preserve the previous implementation. Take a snapshot, rewrite the loop, and test its performance. Is it an improvement? Keep the new code. Not an improvement? Restore the saved snapshot and move on or try a different approach. It's that simple.
Snapshots resemble a source control system, but shouldn't be treated as one. Each snapshot is (conceptually) a complete and independent copy of your entire project. Snapshots are not deltas, so they won't preserve a history or audit trail of your changes — although you can compare two snapshots. Snapshots are cached on your local filesystem; they cannot be transferred to another user, nor is any snapshot information preserved in the project itself. Snapshots are intended to be a spontaneous method of marking your progress. Snapshots can be used independently of, or in addition to, the source control management features. See the "Source Control vs. Snapshots" section of Chapter 21 about issues that can arise when mixing snapshots and source control operations.
You have four ways of taking a snapshot:
Choose the File
Add a snapshot from the snapshot window
Take a snapshot via the refactoring tool
Restore a snapshot
Snapshots occur immediately; there are no dialogs or other overt indications that a snapshot was taken. Each snapshot has a name and an optional description; but when initially added all snapshots are given a generic name that describes how the snapshot was made (menu command, snapshot window, refactor transformation, or restore) and the date. If you want to make a snapshot memorable, rename it or add a comment to the freshly created snapshot in the snapshot window (File
Warning
When Xcode takes a snapshot, it preserves the project source files contained within your project folder. If you have added source items to your project whose files are located outside of your project folder, those files will not be included in the snapshot. If you want resources outside of your project folder (like other projects) to be included in your snapshots, consider relocating your project's root folder (see Chapter 21) or use the snapshot feature of the organizer (see Chapter 22).
The minimal user interaction is intended to make snapshots a seamless part of your development workflow, not another interruption to it. On modern computer systems, snapshots are fast and inexpensive. Get into the habit of taking a snapshot before starting any atomic change to your project. Taking snapshots should become second nature, just as many developers save their files at strategic times. You will want to visit your snapshots occasionally to dispose of old and intermediate snapshots.
Snapshots are managed in the snapshot window (File
The snapshot window is the central interface for browsing, commenting, examining, comparing, and deleting your snapshots. These actions are explained in the following sections.
Snapshots are initially named by the method they were taken (via the main menu, before a refactoring, and so on) and when. If you want to give a snapshot a more memorable name, or make some notes about it, select the snapshot and edit the information as shown in Figure 11-3.
Remember that the snapshot represents the project as it was before you make any additional changes. Make your comments from the perspective of how the project was (for example, "Performance baseline before any optimization"), not how it will be (for example, "Adding new slider animation"). That way, the comments will make more sense later.
You can examine the differences between a snapshot and the current state of your project by selecting a snapshot and expanding the snapshot window, as was shown in Figure 11-1.
The right side of the snapshots window will contain one or two panes:
A list of file changes
A differences browser
When you select a snapshot, the files that have been changed, added, or removed to the project since that snapshot was taken are listed on the right. Selecting a file in the list presents a differences viewer pane that shows the specific changes that were made. Both are shown in Figure 11-4.
When you select a single snapshot, the differences shown are all the changes that have occurred since that snapshot was taken.
If you select exactly two snapshots, as shown in Figure 11-5, the file list shows the differences between those two snapshots.
You can discard your changes and recover your original code from a snapshot in one of three ways.
To recover an individual change, locate the change by selecting the snapshot and a file. Locate the original text in the differences browser. The original (snapshot) version will be on the left and your current version will be on the right, although you can change this in the Xcode preferences. Select and copy the original code to the clipboard, open the file in your project, and paste over the modified code.
To restore all of the changes made to an individual file, and this includes adding and removing a file, select the snapshot, select one or more files in the file list, and click the Restore button in the toolbar.
The snapshot files immediately replace those in the project. If the change entailed removing a file, that file is added back to the project. If the change was adding a file, that file is deleted and removed from the project.
To restore an entire project, select the snapshot, but don't select any files. Clicking the Restore button restores the entire project and all files to the state preserved in the snapshot.
If restoring your entire project from a snapshot — without any warning or confirmation — sounds hazardous, it's not. Every restore first creates a pre-restore snapshot of your project, forming a sort of redo stack. If you performed any kind of restore by mistake, find the pre-restore snapshot and restore that. Yes, this will create another pre-restore snapshot. To discard your changes permanently, restore from a snapshot and then delete the pre-restore snapshot created by the restore.
Deleting a snapshot is the one truly destructive snapshot action. To delete one or more snapshots, select them in the list and click the Delete button in the toolbar. Xcode confirms that you want to delete the selected snapshots, as shown in Figure 11-6.
If you want to delete all snapshots for every project at once, follow these steps:
Quit Xcode
Locate and discard the file
~/Library/Application Support/Developer/Shared/SnapshotRepository.sparseimage
Taking snapshots encourages experimentation, spontaneously illustrates your changes, and reduces the chance of errors should you decide to revert to a previous incarnation of your code. Using snapshots is easy and fast, and should become a regular part of your workflow.
The next chapter looks at the many ways of browsing and searching through the huge amount of documentation that Xcode includes.