Snapshots WHAT'S IN THIS CHAPTER? Taking snapshots of your entire project Reviewing snapshots and comparing them with your working fi les Managing and restoring snapshots 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 fi les 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 fi les 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 fi les to those in a snapshot. You can revert your changes to any previous snapshot on a change - by - change basis, by fi le, or perform a wholesale restore of the entire project. ➤ ➤ ➤ 11 c11.indd 201c11.indd 201 1/21/10 3:23:41 PM1/21/10 3:23:41 PM Download at getcoolebook.com 202 ❘ CHAPTER 11 SNAPSHOTS 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 fi lesystem; 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. TAKING SNAPSHOTS You have four ways of taking a snapshot: Choose the File ➪ Make Snapshot (Control+Command+S) command Add a snapshot from the snapshot window Take a snapshot via the refactoring tool Restore a snapshot ➤ ➤ ➤ ➤ FIGURE 11 - 1 c11.indd 202c11.indd 202 1/21/10 3:23:44 PM1/21/10 3:23:44 PM Download at getcoolebook.com 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 ➪ Snapshots). When Xcode takes a snapshot, it preserves the project source fi les contained within your project folder. If you have added source items to your project whose fi les are located outside of your project folder, those fi les 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 workfl ow, 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 fi les at strategic times. You will want to visit your snapshots occasionally to dispose of old and intermediate snapshots. MANAGING SNAPSHOTS Snapshots are managed in the snapshot window (File ➪ Snapshots). The snapshot window is typically collapsed and shows only the summary of snapshots, as shown in Figure 11 - 2. Click the Show Files button in the toolbar to display change information that was shown in Figure 11 - 1. The snapshot window is the central interface for browsing, commenting, examining, comparing, and deleting your snapshots. These actions are explained in the following sections. Commenting on Snapshots Snapshots are initially named by the method they were taken (via the main menu, before a refactoring, and so on) FIGURE 11-2 Managing Snapshots ❘ 203 c11.indd 203c11.indd 203 1/21/10 3:23:44 PM1/21/10 3:23:44 PM Download at getcoolebook.com 204 ❘ CHAPTER 11 SNAPSHOTS 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. Examining Snapshots 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 fi le changes A differences browser When you select a snapshot, the fi les that have been changed, added, or removed to the project since that snapshot was taken are listed on the right. Selecting a fi le in the list presents a differences viewer pane that shows the specifi c changes that were made. Both are shown in Figure 11 - 4. ➤ ➤ FIGURE 11-4 FIGURE 11-3 c11.indd 204c11.indd 204 1/21/10 3:23:49 PM1/21/10 3:23:49 PM Download at getcoolebook.com 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 fi le list shows the differences between those two snapshots. FIGURE 11-5 Restoring Changes You can discard your changes and recover your original code from a snapshot in one of three ways. Restore Individual Changes To recover an individual change, locate the change by selecting the snapshot and a fi le. 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 fi le in your project, and paste over the modifi ed code. The differences viewer can normally update the fi les directly, exchanging or combining changes directly. For some reason, this feature is disabled in the snapshots window. Managing Snapshots ❘ 205 c11.indd 205c11.indd 205 1/21/10 3:23:50 PM1/21/10 3:23:50 PM Download at getcoolebook.com 206 ❘ CHAPTER 11 SNAPSHOTS Restore Individual Files To restore all of the changes made to an individual fi le, and this includes adding and removing a fi le, select the snapshot, select one or more fi les in the fi le list, and click the Restore button in the toolbar. The snapshot fi les immediately replace those in the project. If the change entailed removing a fi le, that fi le is added back to the project. If the change was adding a fi le, that fi le is deleted and removed from the project. Restore an Entire Project To restore an entire project, select the snapshot, but don ’ t select any fi les. Clicking the Restore button restores the entire project and all fi les to the state preserved in the snapshot. Undoing a Restore If restoring your entire project from a snapshot — without any warning or confi rmation — sounds hazardous, it ’ s not. Every restore fi rst creates a pre - restore snapshot of your project, forming a sort of redo stack. If you performed any kind of restore by mistake, fi nd 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 SNAPSHOTS 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 confi rms 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 fi le ~/Library/ Application Support/Developer/Shared/ SnapshotRepository.sparseimage SUMMARY 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 workfl ow. The next chapter looks at the many ways of browsing and searching through the huge amount of documentation that Xcode includes. ➤ ➤ FIGURE 11-6 c11.indd 206c11.indd 206 1/21/10 3:24:03 PM1/21/10 3:24:03 PM Download at getcoolebook.com . before a refactoring, and so on) FIGURE 11-2 Managing Snapshots ❘ 2 03 c11.indd 203c11.indd 2 03 1/21/10 3: 23: 44 PM1/21/10 3: 23: 44 PM Download at getcoolebook.com 204 ❘ CHAPTER 11 SNAPSHOTS and. were made. Both are shown in Figure 11 - 4. ➤ ➤ FIGURE 11-4 FIGURE 11 -3 c11.indd 204c11.indd 204 1/21/10 3: 23: 49 PM1/21/10 3: 23: 49 PM Download at getcoolebook.com When you select a single snapshot,. a wholesale restore of the entire project. ➤ ➤ ➤ 11 c11.indd 201c11.indd 201 1/21/10 3: 23: 41 PM1/21/10 3: 23: 41 PM Download at getcoolebook.com 202 ❘ CHAPTER 11 SNAPSHOTS Snapshots encourage