Shelving and Checkpointing are new features introduced in Cornerstone 4.0. They let you save the effects of your work to a temporary storage and continue working on your working copy. Later, you can use that saved work by patching your working copy with the contents of your shelf or checkpoint.
​
Shelving and Checkpointing are similar features. The difference between them is what your working copy will look like after you make a shelf or a checkpoint. A checkpoint will save your modified working copy files into a shelf, but your changes will remain in the working copy. Shelving, on the other hand, will revert your changes, so your working copy will be missing all modified files (they will be saved in a checkpoint though).

In order to be able to use Shelving and Checkpointing, you need to have a working copy checked out in Cornerstone. You can access the new features either using the Working Copy menu (Fig.1) or a right button menu on a working copy (Fig.2).

Figure 1: Working copy menu with Shelve and Unshelve
​

Figure 2: Left menu of Working copy - Shelve and Unshelve visible

Shelving and unshelving options can be used only on your local working copy, not on a remote repository. There is also a possibility to shelve a single file or a group of files. It is illustrated in a Figure 2.a.

Figure 2.a: Ability to shelve a file directly from a Working Copy Browser

If you select a file or files that are modified, added, or deleted, you can shelve them directly. They will appear as selected in the Shelving window (Figures 2.b and 3). You cannot, however, select a directory or non-text file to shelve. So, the Shelve changes option will be grayed out on images or directories.

Figure 2.b: Items selected after a direct selection shelve

Figure 3: Shelve items

 
Figure 3 shows a window that is visible after the Shelve command is clicked. In the top of a window we have a tab bar that lets us choose if we want to make a Shelf (Shelve and revert), or a Checkpoint (Save a checkpoint (do not revert) ).

Below that we have an option to choose a shelf. We can either create a new one (default option) and enter a new name for it or choose an existing one. If you choose the existing shelf, SVN will add a new version to it, which will be visible in the Unshelve dialog, described later.

In this window we can optionally type a log message for a shelf. The log message is the same for every version within a shelf – it’s one log message for one shelf. However, it’s an optional selection and a shelf does not require a log message.

Finally, in the bottom of the window we are presented with a list of files that have been changed (in SVN terminology). We can select which files will be added to our newly created shelf/checkpoint. We do it by clicking them in the list. We can also use a button to select all.

After we complete all of the steps, the Shelve changes button will become active. When we press it, the shelf/checkpoint will be created.

Figure 4 presents the Unshelve window. It allows you to unshelve changes that were saved in a Shelve window. If you do not have any shelves or checkpoints, the options will be empty and you won’t be able to do anything here.

Figure 4: Unshelve window

If you have shelves or checkpoints, they will be visible in the first list. You can choose which one is to be unshelved. If you select a shelf, you will see all versions that were created for a selected shelf.

Note: the shelf can be empty, it doesn’t have to contain any versions. It can also create quite a few versions, depending on how you were using the shelving mechanism. Each version has a date modified field, which tells you when the changes were made.

The next step is to select a version that is to be unshelved. When you do that, you will see files that are stored within this version. This is a read-only field; you can only see a file’s name, nothing more.

Finally, there are 2 checkboxes. One allows you to delete the entire shelf when these changes are applied, and the second lets you delete the version that was applied and all newer versions, leaving the rest of the shelf untouched. It means that if you have versions 1 - 5 of your shelf and you are applying version number 3 and the box Delete selected and later versions after applying is checked, versions 3, 4, and 5 will be deleted. You do not have to use any of these checkboxes, however you can only select one of them at the most (the other one will automatically get disabled).

There are, however, some special cases when Unshelving might not be possible. That is illustrated in Figure 5.

Fig. 5: Unshelve window

Sometimes, the shelf that you’ve created might cause some troubles – it might not be possible to unshelve it without generating a conflict in a working copy. Currently, shelving in SVN 1.10 doesn’t support full merge, as SVN does. It cannot generate conflicted files. That kind of situation will be detected by the application. The files that will cause a conflict are marked with a red color. A message below the table appears. You can see the patch file (for the whole shelf) and correct things. When you click cancel and Unshelve again, if you properly handled the problems, you will be able to unshelve this time.

When all the steps are completed, the Apply shelved changes button is made visible. Pressing it will apply the shelved changes onto your working copy. You will see new files in Cornerstone's view for a working copy.

Need help? Contact us at support@assembla.com