Shelve is a feature which allows you to upload a set of changes in your working folder to the Vault Professional 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 changes 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.
Accepting Patches (untrusted code review). If there are users with Read Only folder security settings for the repository, they may still shelve changes and view other user's shelvesets. Using this, an untrusted developer could shelve a set of changes, which must be reviewed and checked in by a trusted developer.
In order to shelve changes, the Read Only user must disable the Require Check out before Check in option. When that option is enabled, only checked out files appear in the pending changeset. Read Only users are not allowed to check out files.
All pending change types can be shelved. Special care should be used when shelving files resulting from a 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.
You will find Shelve functions in the following places:
The Pending Changes Control. This control is found in the Visual Studio Enhanced Client, the Eclipse client and the standalone GUI client (in the Pending Changes tab). You can bring up the Shelve Changes dialog by selecting a set of changes and selecting Shelve… from the context menu. There are two shelve related buttons.
Shelve All This button will bring up the Shelve Changes dialog with all currently pending changes.
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.
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.
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 and the working folder file has not been edited. 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, Do Nothing, or Overwrite the files. The options when diffing the file are:
Diff the shelved file against shelved file's baseline
Diff the shelved file against the file in the working folder
Diff the file in the working folder against the last version retrieved from the server
Automerge is not an option, since there are four files which would need to be merged. We're sorry for the inconvenience, but hopefully you have all of the diff options available that will let you easily merge the contents manually.
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.
The file was deleted from the location where it was shelved. If the file is now deleted, 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.
If a Check-Out operation fails for any of the unshelved files, the shelveset will not be automatically deleted.
Other notes about unshelve:
If there is not a working folder for the target directory of an Add File and Add Folder operation, it will be unshelved into a temporary directory, and not into the working folder. If a file or folder with the name already exists in the working folder, it will be renamed, and the unshelved file or folder will be put in its place.
If you have the "Require Check-Out before Check-In" (VSS Mode) option specified, then you will be presented with a list of files that will need to be checked out and the opportunity to provide a checkout comment. If any of those checkouts fails, the shelveset will not be automatically deleted. You will be prompted to continue the unshelving operation or cancel the operation for each Check Out failure.
When unshelving file modifications, you can choose Modification or Current for the timestamp applied to the unshelved file(s).
Modification- The Modification timestamp is the last file modification date before the file was shelved.
Current- The Current timestamp is the time the file was unshelved.
After the unshelve process is complete, a summary dialog will be displayed to list which files were successfully unshelved, which had errors, and whether the shelveset was automatically deleted.