Shelve
Posted by Jeremy Mon, 28 Jul 2008 19:48:14 GMT
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.
- Shelve… This button will bring up the Shelve Changes dialog.
- 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.
- Details. View the details for the shelveset. (Double-clicking an item will also activate this action.)
- 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.)
- 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
- Name – the name of the effected folder or file.
- Repository Path. This is the repository path at the time of shelve.
- Details
- Pending Change Type
- 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.
