Share via

Working with Shelvesets

  • Article

Shelving lets you set aside a batch of pending changes temporarily and optionally remove the pending changes from workspace. The product of the shelve operation is a shelveset. The changes in a shelveset can be restored later into your workspace or into another user's workspace.

The Difference between Changesets and Shelvesets

When you check in one or more of the pending changes in your workspace, Team Foundation creates a changeset in the source control server. A changeset is a group of source file revisions, check-in notes, a comment, and links to associated work items. Similarly, a shelveset is a group of source file revisions, check-in notes, comments, and a list of associated work items. However, a shelveset does not contain a collection of committed and versioned file changes. Both shelvesets and changesets are stored on the Team Foundation server and can be retrieved into a workspace by any user who has sufficient permissions.

Other differences between changesets and shelvesets:

  • Unlike a changeset, a shelveset is a non-versioned entity. If you or another user unshelve the items of which a shelveset consists, edit several files, and reshelve the shelveset, Team Foundation does not create a new version of the items for future comparison and maintains no record of who revised the items, when, or in what manner. The original shelveset is completely replaced.

  • You can delete a shelveset but you cannot delete a changeset.

  • You can link a changeset to a work item so that when a user clicks the changeset link on the Links tab of the work item form, the changeset is automatically retrieved to the current workspace. This functionality is not supported for shelvesets.

  • You can prevent or at least, strongly discourage users from creating changeset that do not comply with established team standards by creating and enforcing check-in policies. This functionality is not supported for shelvesets.

The Purpose of Shelving

Shelve your pending changes when you are not ready to or cannot check in a set of pending changes. There are primarily five shelve scenarios:

  • Interrupt   When you have pending changes that are not ready for check in but you need to work on a different task, you can shelve your pending changes to set them aside.

  • Integration   When you have pending changes that are not ready for check in but you need to share them with another team member, you can shelve your pending changes and ask your team member to unshelve them.

  • Review   When you have pending changes that are ready for check-in and have to be code-reviewed, you can shelve your changes and inform the code reviewer of the shelveset.

  • Build   Before you check in your changes, you can use your build system to make sure that the changes in a shelveset will not break your regularly scheduled build processes, such as a nightly build. You can perform this validation manually by queuing a private build or automatically by implementing gated check-in.

  • Backup   When you have work in progress that you want to back up, but are not ready to check in, you can shelve your changes to have them preserved on the Team Foundation server.

  • Handoff   When you have work in progress that is to be completed by another team member, you can shelve your changes to make a handoff easier.

Creating Shelvesets

Shelvesets are created from either Source Control Explorer, the Pending Changes window, or the menu. For more information about how to create a shelveset see Shelve and Unshelve Pending Changes.

Unshelving Shelved Changes

Whereas you can restore a changeset into a workspace using the Get command, you must use the Unshelve Command to restore a shelveset. You can use the Unshelve button in the Pending Changes window to restore one, some, or all the pending changes in a shelveset to your workspace. For more information about the Pending Changes window, see Check In Pending Changes. When you unshelve all the changes in a shelveset to a workspace using Visual Studio, the pending changes information with which the items are associated is restored to the Pending Changes window also. For more information, see Shelve and Unshelve Pending Changes.

When you unshelve a shelveset, Team Foundation restores each shelved revision into the destination workspace as a pending change as long as the revision does not conflict with a change that was already pending in the workspace.

  • Edits   Team Foundation copies the contents of the source workspace version into the destination workspace version and checks out the file for edit.

  • Deletions   Shelved files and folders that were deleted pending check in to the source workspace are deleted in the destination workspace.

  • Additions   Shelved files and folders that were added to source control pending check in to the source workspace are added to the destination workspace.

  • Renames and Moves   Shelved files and folders that were renamed or moved in the source workspace are renamed and moved into their new folders in the destination workspace.

    Important

    To unshelve an item, there must be no pending revisions against it in the destination workspace.

Comparing a Shelved File to its Base Shelveset Version

You can use the Unshelve command in Visual Studio or you can use the Difference Command from the command line to compare one, some, or all of the shelved file revisions in a shelveset to the base shelveset version, which is the server version of the item upon which it was based.

Deleting Shelvesets

Unlike changesets, which are permanently stored in the source control server, you can delete shelvesets from the server.

Warning

Unlike a deleted file, a shelveset is permanently deleted and you cannot retrieve it from source control.

For more information about how to delete a shelveset using Visual Studio, see Delete a Shelveset. For more information about deleting shelvesets using the command line interface, see Shelve Command.

In This Section

Reference

Team Foundation Version Control Command-Line Reference

See Also

Concepts

Working with Changesets

Queue a Build

Define a Gated Check-In Build Process to Validate Changes