Shelving files
Shelving enables you to store copies of open files temporarily in the Perforce repository 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 from which other users can unshelve
it. Pending changelists that contain shelved files are indicated by a red triangle marked by a file icon: . When the changelist is expanded, shelved files are indicated by a file icon with a check-mark:
.
When managing shelved files, note the following:
- Basics: To be shelved, a file must be checked out. However, you cannot unshelve a checked-out file.
- Submitting shelved files: As of Perforce Server 2013.1, you can submit a shelved file directly. For previous versions of Perforce Server, you must first unshelve a file to submit it, then delete the shelved copy. (Unshelving does not delete the shelved copy.)
- Managing changelists: 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. For Perforce Server releases that predate version 2013.1, you cannot submit a changelist that contains shelved files; you must delete the shelved copies before submitting. Starting with Perforce Server 2013.1, you can submit shelved files directly, but your changelist must contain only shelved files.
- File history: No file history is created when you shelve or unshelve files.
- Diffing: You can diff shelved copies by right-clicking the shelved file in the Pending dialog (View > Pending Changelists) and selecting Diff Against Source Revision or Diff Against Workspace File.
Shelving checked-out files
To shelve checked-out files in a pending changelist:
-
Open the Shelve dialog by doing one of the following:
- Go to View > Pending Changelists. On the Pending dialog, context-click the changelist and select Shelve….
- In the Solution Explorer, context-click a file that is in a pending changelist and select Shelve….
- In the the Shelve dialog, select the files you want to shelve.
-
Select any of the following options that apply:
- Revert checked-out files after they are shelved: The files in your workspace will revert to the head revision in the depot.
- Clear changelist of all previously shelved files before shelving
- Click Shelve.
-
When prompted, enter a description and click OK.
P4VS 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 unshelve files in a pending changelist:
- Context-click the file in the changelist and select Unshelve…. P4V displays the Unshelve dialog.
- Check the files you want to unshelve and click Unshelve and any other desired options. 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, context-click the file and select Delete. You can also context-click the pending changelist and select Delete Shelved Files….
Submitting shelved files
As of Perforce Server 2013.1, you can submit shelved files directly.
Note
If there are non-shelved files along with shelved files in a pending changelist, you must first revert the non-shelved files or move them to another changelist. You cannot submit shelved files from a task stream.
To submit shelved files in a pending changelist, context-click the changelist and choose Submit Shelved Files….