Shelve

Jeremy — Mon, 28 Jul 2008 14:48:14 -0500

Introduction

We’ve been talking about Shelve for a while, and lots of customers have been curious about how Shelve will work in Vault and Fortress. For Shelve, we’re writing the user documentation first, before we write a single line of code. This has been a really helpful exercise, since we’ve had to talk through a lot of issues that would have been surprises in a more technical-focused spec. The goal of this documentation is clarity and completeness. Please complain in the comments section if anything is confusing at all.

Overview

Shelve is a feature which allows you to upload a set of changes in your working folder to the Vault server without committing them. In order to commit these shelved changes (called a shelveset), you must first unshelve them to a working folder. After unshelving the changes, you may commit them just as you would a normal changeset. Some cases where shelve is useful are:

Archiving changes. If you are interrupted while working on a task, shelve allows you to set aside your changes and come back to them at a later time.
Sharing change before checkin (code review). All shelvesets are visible to all users with access to that repository. By informing your reviewers of the name of your shelveset, they can unshelve it to their working folder, or view the shelveset in the web client.

What kinds of changes can be shelved?

All pending change types can be shelved. Special care should be used when shelving Rollback, as versions may have been added since the Rollback was shelved. On committing an unshelved Rollback, the contents of those versions would be rolled back as well.

Finding the Shelve Functions.

You will find Shelve functions in the following places

The Pending Changes Control. This control is found in the Visual Studio Enhanced Client (How to bring it up), the Eclipse client (where to find it) and the standalone GUI client (in the Pending Changes tab). There are two shelve related buttons. You may also bring up the Shelve Changes dialog by selecting a set of changes and selecting Shelve… from the context menu.
1. Shelve… This button will bring up the Shelve Changes dialog.
2. Unshelve… This button will bring up the Find Shelveset dialog.
View Shelved Changes. This menu item is available in the View menu of the standalone GUI client. This menu item will bring up the Find Shelveset dialog.
The File and Folder lists. The file and folder controls in the standalone GUI client will have context menu items to bring up the Shelve Changes dialog.
The Command Line Client/NAnt/Ant. These components all have shelve and unshelve commands.
Source Control Web Client. Each repository will have a page for Shelved changes. Here you may view the shelves, their details and diff their file changes.

The Shelve Changes Dialog

This dialog is used to create a shelveset from a set of pending changes. In this dialog, you will see the list of currently pended changes. If you brought this dialog up using the context menu in the Pending Changes control, you will only see the list of changes that you had selected there. You may enter the following information about your new shelveset.

Shelveset name. This name must be unique among all of your shelvesets. If you reuse a shelveset name, you will be prompted to confirm that you wish to delete the existing shelveset and create a new one with the contents you select here.
Changes. In the change list section, any changes that are checked will be included in the shelveset.
Comment. You may enter a comment that will be retained inside this shelveset.
Work Items (Fortress only). You may select a list of work items to update. The work items will link back to this shelveset. This way, any other users who wish to review your changes can use the work item as the hub to find all of the relevant shelvesets.
Undo changes in my working folder. This checkbox will inform Vault to undo the changes when the shelveset has been uploaded. The default is unchecked. You may change the default setting for this checkbox in the Options dialog.

The Find Shelveset Dialog

This dialog is used to browse the shelvesets for a repository and get basic details about them. The controls are as follows:

The User dropdown. This dropdown will display a list of all active users with access to the repository. Your user name is selected by default in this dialog. Selecting the first item in the dropdown (named “all”) will show all shelvesets from all users.
The Find Button. Clicking this button will populate the Shelveset list for the user selected in the user dropdown.
The Shelveset List. This list will display all of the shelvesets for a selected user. The displayed columns are shelveset name, date, and comment. Selecting a shelveset in this list will activate the Details button. You can unshelve the selected shelveset through the Shelveset Details dialog (opened by selecting a shelveset and clicking the Details button). The following operations are available in the context menu of The Shelveset List.
1. Details. View the details for the shelveset. (Double-clicking an item will also activate this action.)
2. Rename. Rename the shelveset. Renaming a shelveset will not affect the shelveset creation time. You may only rename your shelvesets. (F2 is a shortcut for this action.)
3. Delete. Delete the shelveset. You many only delete your shelvesets. (The delete key is a shortcut for this action.)

When Diffing shelvesets, the Find Shelvesets dialog expands to allow you to select two shelvesets. The Diff function will fetch both shelvesets to a temporary directory and perform a folder diff.

Shelveset Details

This dialog will display the contents of a shelveset and allow you to unshelve it. For more help on unshelving a shelveset, see “How do I unshelve my changes?”. Please note that a shelveset may contain changes to paths that you have been denied permission to see by the Folder Security settings in the admin web client. This dialog will only show changes that you have permission to view. A warning dialog will be shown to alert you when items you did not have permission to view have been omitted from the details you are about to view. Unshelving the shelveset will only unshelve changes that you have permission to view.

This dialog has the following controls:

Shelveset name
Shelveset owner
Shelveset comment
Shelveset time.
Web Client link. Clicking this link will open a web browser to this shelveset in the Source Control web client. Right-clicking this link will present a context menu to Copy the URL to the web client. Emailing this URL is another good way to facilitate a code review of this shelveset.
Work Item links (Fortress Only). A list of links to work items that were referenced by the shelveset. Basic information about these items will be listed along with a link. Clicking any of these links will open a item browsing dialog to the referenced work item in the Item Tracking client. If an associated work item has been deleted by an administrator, it will not appear in this list.
Automatically delete shelveset after I unshelve it. This checkbox will cause the client to delete the shelveset after it has been successfully unshelved. If any of the files could not be unshelved or if there were any namespace conflicts during the unshelve process, the shelveset will not be deleted. This checkbox is only enabled if you are the owner of the shelveset. This checkbox will be disabled unless all changes in the Shelveset contents are checked for unshelving. This checkbox will also be disabled if changes have been omitted from the contents due to permissions.
Shelveset contents. This control will list all of the pending changes. When the unshelve button is clicked, only items which are checked in this control will be unshelved. The following details will show in this list
1. Name – the name of the effected folder or file.
2. Repository Path. This is the repository path at the time of shelve.
3. Details
4. Pending Change Type
5. Comment. This is the comment put on this pending change before it was shelved.

The following operation is available from the context menu.

Diff. If a pending change has file content changes associated with it, you may choose this menu item to bring up the Diff dialog.
View. This item will allow you to view edited or new files (add file operations). Choosing this dialog will bring up the View dialog.

How to unshelve changes

Once you’ve used the Unshelve button in the Shelveset Details dialog, the unshelve process will begin. You will be asked to make decisions when complications arise in the unshelve process. Any of these complications will negate the “Automatically delete shelveset after I unshelve it” setting. Some complications are:

There is no working folder set for the destination of one of the items in a shelveset. You will be prompted to set a working folder, or to unshelve to non-working folder. No baseline information will be set in the non-working folder case, so you will not be able to check in that change.
A newer version of a file has been checked in since the change was shelved. The file will be unshelved, and the status of the file will be Needs Merge.
There is an edited file in the working folder at the location. You will be prompted with the same prompt dialog used in the get latest process. You may Diff the files, Attempt Automatic merge, Do Nothing, or Overwrite the files.
The file no longer has the same name as it did when it was shelved. In this case, the unshelve process will unshelve the change into a file with the new name.
The file is no longer in the same location that it was when it was shelved. If its new location can be determined, then it will be unshelved to the new location. If the new location cannot be determined, you will be prompted for a location to put the file as a non-working folder unshelve. You will not be able to directly check in the file from the non-working folder.

"Shelve" by Jeremy

Fri, 22 Aug 2008 08:52:19 -0500

We've figured out how we are going to do compare against baseline and compare against latest for shelvesets. In both cases, we will download the latest or baseline version of each file in the shelve to a temp directory and each file from the shelveset to a different directory. Then, we'll do a folder diff between the two temp folders. As for shelveset names, there can be only one shelveset with a given name for a user inside a repository. That name can be reused for other users or other repositories.

"Shelve" by Rob Goodridge

Wed, 06 Aug 2008 20:11:16 -0500

I would agree that comparing the whole Shelveset to the previous version in the repository is very important, given that one reason for shelving is to code review the changes from the previous version. May also be useful to compare to any Branch. I was also wondering if the Shelveset names were unique to a user or to the whole repository?

"Shelve" by Jeremy

Mon, 04 Aug 2008 13:57:42 -0500

Bradley, The diff context menu will bring the full diff dialog, so it will be able to diff against baseline, latest or any file on the disk or in the repository. Greg, You're right. SGDM can hide orphaned files. I don't think it will be hard to add this capability.

"Shelve" by Bradley Uffner

Wed, 30 Jul 2008 23:12:36 -0500

I see the context menu now in the screenshot. Does that compare against the current checked in file in vault, or the file as it is in the working folder? This is a great feature that is going to get a LOT of use from my team.

"Shelve" by GregM

Tue, 29 Jul 2008 11:42:49 -0500

If shelvesets are sparse, and you can compare one sparse shelveset to another sparse shelveset, then it makes sense to be able to compare a sparse selveset to a working folder. I'm not sure about SGDM, but BeyondCompare, which we use, can be set to not display orphan files, so it would only display files that are in both places and different.

"Shelve" by Jeremy

Tue, 29 Jul 2008 08:16:39 -0500

Differences versus trunk is accomplished one file at a time through the context menu in the Shelveset Details dialog. The reasoning for this is that a shelveset is sparse (it only contains the files that are changed), so a folder-compare style diff against trunk would show lots of "this is in the trunk but not in the shelveset" differences. The other benefit to doing it in the Shelveset Details is that we can bring up the full "Show Differences" dialog, which will let you choose between diffing against the baseline, or the latest version, or a version in another branch.

"Shelve" by Bradley Uffner

Mon, 28 Jul 2008 21:18:44 -0500

I see a way to diff a shelf set to another shelf set, but what about a way to compare it to the trunk as it stands now? Can this only be done by downloading the shelf set and doing the diff, or is there a way to view that from the shelf interface?

SourceGear Development Blog: Shelve

Shelve

Introduction

Overview

What kinds of changes can be shelved?

Finding the Shelve Functions.

The Shelve Changes Dialog

The Find Shelveset Dialog

Shelveset Details

How to unshelve changes

"Shelve" by Jeremy

"Shelve" by Rob Goodridge

"Shelve" by Jeremy

"Shelve" by Bradley Uffner

"Shelve" by GregM

"Shelve" by Jeremy

"Shelve" by Bradley Uffner