Shelving files
Shelving enables you to store copies of open files temporarily in the Helix Core Server without checking them in. Shelving is useful for a variety of purposes, including taking and restoring snapshots of in-progress work and reviewing other users' code before it's checked in. When you shelve a file, a copy is placed in a pending changelist A list of files, their version numbers, the changes made to the files, and a description of the changes made. A changelist is the basic unit of versioned work in Helix Server. The changes specified in the changelist are not stored in the depot until the changelist is submitted to the depot. See also atomic change transaction and changelist number. from which other users can unshelve it. Pending changelists that contain shelved files are displayed as follows:
. When the changelist is expanded, it contains a node listing shelved files. When you expand the Shelved Files node, shelved files are indicated as follows:
. The decoration on the file indicates the action for which it was opened before being shelved.
When managing shelved files, note the following:
- Server: Shelving is available for Helix Server 2010.2 and higher.
- Basics: To be shelved, a file must be checked out. However, you cannot unshelve a checked-out file.
- Submitting shelved files: You cannot submit
To send a pending changelist into the Helix Server depot for processing. a shelved file directly. To submit a shelved file, you must first unshelve it, then delete the shelved copy. (Unshelving does not delete the shelved copy.)
- Managing changelists: You cannot submit a changelist that contains shelved files. You must delete the shelved copies before submitting. You cannot move a shelved copy to another pending changelist. If you revert a file after shelving it, the copy remains shelved in the changelist until you delete it. Only the changelist owner can reshelve or delete files that are shelved in the changelist.
- File history: No file history is created when you shelve or unshelve files.
- Diffing: You can diff shelved copies just as you diff any other file. For example, to display any changes you made after shelving a file, drag the shelved copy and drop it on the checked-out file. To diff a file and its shelved version, right-click the file and choose Compare With Shelved Version...
Shelve checked-out files in a pending changelist:
- In the P4 Pending Changelists view, right-click the changelist and choose Shelve...
- Select the files you want to shelve.
- Select one of the following options to shelve the files:
- Shelve selected files: Adds the files you have selected to the existing shelf.
- Replace shelved files with pending changelist files: Deletes the existing shelf and replaces the shelf with the pending changelist files.
- Delete selected shelved files: Deletes the selected files from the shelf.
- Select the following options if required:
- Revert checked-out files after they are shelved: Reverts the files in your workspace to the head revision in the depot.
- Remove files that are opened for add: If you do not want P4Eclipse to remove these files from the file system when they are shelved, make sure to clear the Remove files that are opened for add check box.
- Click Shelve.
P4Eclipse displays the Shelve dialog.
To see a preview of your file and shelving option selections, look at the Shelved Files Update Preview pane.
By default, when this option is selected, P4Eclipse also removes any files that are marked for add in the changelist from the file system when they are shelved. See below for details.
P4Eclipse shelves the file in the selected changelist or, if you are shelving files in the default changelist, creates a new changelist.
Unshelving files
After shelving a file, you (or another user) can unshelve it, which restores the shelved copy to your workspace and opens it in the changelist of your choice. Unshelving does not remove files from the shelf. To unshelve a file that was shelved by another user, you must have permission to check out the file. When you unshelve a file that was shelved by another user, it is copied to one of your changelists, from which you can edit and submit the file. To replace a file with its shelved version, right-click the file and choose Replace with Shelved Version...
To unshelve files to a specified pending changelist:
- Right-click the shelved file or the Shelved Files node and choose Unshelve...
- Select the files you want to unshelve and specify the changelist you want them unshelved to.
- Select the following options if required:
- Use selected changelist until submitted or deleted and don't prompt again: Unshelves the selected files to the selected changelist for all future unshelve operations of this shelf. This is canceled when you manually select a new changelist, submit the files, or delete the files.
- Overwrite files currently writable (-f): Forces the overwriting of writable (but unopened) files during the unshelve operation. As a best practice, use this option to unshelve a shelf that has added files.
- Revert current changes before unshelving: Reverts the current changes before unshelving the files.
- Click OK.
P4Eclipse displays the Unshelve dialog.
The shelved file is copied to your workspace and opened in the specified changelist.
Shelved files remain shelved until you delete them from the pending changelist. To delete a shelved file from a pending changelist, right-click the shelved file and choose Delete Shelved Files.
Submit a changelist containing only shelved files
You can submit a changelist which has shelved files if they are mapped in your client view. To do that, you need make sure that the shelved changelist is submittable, that is, the changelist should not contain opened files, then:
- Right-click the shelved changelist either from P4 Shelved Changes view, or from the Pending Changelists view
- Select the Submit Shelved Files... if the context menu is enabled. If the selected shelve changelist is not submittable, P4Eclipse will prompt you. Then you can either move the non-shelved file to a new changelist, or revert them, then re-submit
- Confirm the submit.