The Perforce shelving feature enables you to store and share snapshots of your files on the central Perforce server. Shelving is useful, for preserving snapshots of work in progress so you can divert to another effort, for posting code for review by other users, to validate builds on multiple platforms, and to move work in progress to another workspace; yours or another user’s.
Shelving is not a check-in to the file depot. The shelf is just a place to temporarily stash a file and does not include any versioning history contained in the depot files.
Shelved files are always associated with pending changelists with one shelf per changelist. However, there can be multiple files on a shelf.
This feature requires a 9.2 or later version of the Perforce server and client.
Let’s see how the file movement looks in the system. When you sync a file or group of files, you are copying a version, typically the latest, from the file depot on the Perforce server to the client workspace on your local machine. When the file is “checked out,” you are enabling changes to the copy in your workspace. After the file is edited, it is saved back into the workspace. At this point, it still resides on your local storage and not on the Perforce server.
You can use shelving to maintain differing sets of changes to the same file or group of files by shelving to separate pending changelists. For example, you can take a snapshot of a work in progress and shelve it in changelist 21, while making some different edits that represent a new approach to a bug fix and shelving that in changelist 22, while providing a third set of edits that enables build engineers to compile on an alternate platform in yet another changelist.
Shelved files are visible to other users and they can unshelve a copy to their local workspace storage. Additionally, as the person who originally created and shelved the files, you can unshelve a selected snapshot back into your own workspace.
When the files are ready for submission into the depot, the shelved file from the changelist to be sumitted will be deleted, and the new version will be stored in the depot during the submit operation.
Let’s see how shelving operations look in the Perforce Visual Client, P4V.Here we are in the middle of some edits of two files in our default changelist. We receive an urgent request for a bug fix to one of the files currently open for edit, so we decide to shelve those files to preserve our changes without checking them in. We context click the changelist and choose Shelve, and P4V displays the Shelve dialog.
There is one shelf per numbered pending changelist and no shelf for the default changelist. Because we are shelving the files from the default changelist, P4V prompts us to enter a description for a new pending changelist where the files will be shelved. This description can be modified before submission into the depot so we’ll just insert some placeholder text.
Now we see the new changelist with two shelved versions under the Shelved File icon here. We can now fix the bug, knowing that a snapshot of our current work is safely stored on the server.
Let’s say we want to make a minor change to the Enut file before working on the bug. We can reopen the file in the new changelist, makes a quick change (change “1” to “5”), and save it.
Now we shelve the new version. Since it is already shelved in a numbered changelist, we don’t need to create a new one – we can simply replace the currently shelved version with our changed version. Select the file and context-click Shelve. This will overwrite the previously shelved version.
Now we start fixing the problem with the original file that contained the bug. Let’s move ENut back to the pending changelist and open it again. We make a change to the current state declaration (change “on” to “off”) and save it. We want another engineer to review our change before we check it in, so we context-click and choose Shelve. Since this is coming from a default changelist again, we need to enter a changelist description.
Now we return to our original development tasks. To unshelve the files shelved prior to fixing the bug, we can select the changelist containing the shelved files, and context click Unshelve Files. The dialog box will offer destinations to unshelve the files and a few other options related to your workspace configuration resulting from the operation.
Alternatively, you can unshelve the file by simply dragging them back to a selected changelist.
Now the workspace is restored to its original state and we can resume development where we left off. After a quick edit to EWidget, we save the file and choose Submit to check-in the work to the depot. A warning dialog states all shelved files in the changelist must be deleted or moved before we can submit. We no longer need the shelved files so we select Yes to delete them when the changelist is submitted.
Now the Submit dialog appears with the changelist description in place since it was completed previously. After a small mod, (delete “shelve”) we click the Submit button. These changes are now in the depot as new versions.
When other users shelve their files, we can unshelve copies for use in our workspace. For example, let’s say Joe Coder told us about some code in his new DualWidgets file that relevant to our project. It’s a prototype and not checked into the codeline in the depot, but he shelved it. We select the pending changelist pane and browse to his workspaces.
Next, we open the changelist which contains the shelved file and take a quick look at the code. We decide we need the framework he created to use in a new feature set, so we unshelve the file to our workspace and include it in our pending changelist for future modification.
As you can see, shelving enables many new dimensions to your workflow. A series of triggers are also available for use with automating shelving operations including shelve commit, submit and delete.
This concludes our overview of the Shelving feature. You will find additional detail in the P4V online help and the documentation section of the Perforce website.
Thanks for watching.