Shelving: Pretty Darn Useful!
Posted on Dec 9, 2009 by Laura Wingerd
As of Release 2009.2 (now in beta), Perforce supports “shelving”. That is, you can cache your modified files on the server, without having to check them in as a versioned change. For teams, shelving makes code reviews and code handoffs possible. Individuals can use shelving for multi-tasking, code shunting, incremental snapshots, and safety nets.
Shelved files in Perforce are visible to users who have access to the underlying files, so shelving is a perfect way of exposing the files you are working on to your team. Just use the shelve command to upload your local versions. They’ll be assigned a changelist number that can be used to view and diff your shelved files. In fact, reviewers can even unshelve your files into their own workspaces if they want.
In your workspace, the shelved files are left open. A shelved changelist acts as a pending changelist, so you can continue working on the files during and after code review. You can re-shelve files into the same shelved changelist for another review, or you can submit them as a versioned change.
Perforce’s shelving implementation is different from other implementations in several ways. For one thing, files remain untouched in your workspace when you shelve them. The shelve command creates a changelist that acts both as a pending change in your workspace, and as a public reference to the shelved versions of your files. For another, you can’t submit a shelved changelist. (Not yet, at any rate. There are rumors that we’ll be able to do this in the future.) So before you submit your files you have to tell the server to discard the shelved versions. Or, you can move your opened files to a new pending changelist and submit that instead. If you do the latter, your shelved files remain cached on the server until you discard them.
This makes Perforce’s shelving suitable for handing off work in progress. After shelving your modified files you can use revert to release the shelved changelist from your workspace. This restores your workspace to its pre-modified condition. If you then assign the shelved changelist to a new owner, that user will now see it in her list of pending changes. She can now unshelve the files into her workspace, keeping them in the same pending changelist. After working on the files she can either reshelve them and hand the changelist back to you, or she can submit the changelist herself.
Shelving is also an easy way to shunt code from one machine to another. For example, you’ve done some coding on a Windows machine. But does your new code compile on the Mac? To find out, shelve your files while on Windows, then unshelve them while on a Mac. You can shelve and unshelve code this way as needed before submitting a change.
How about shelving work in progress for multi-tasking? Say you’re burning out on one coding task and want to take break to work on another. No problem — just shelve your files. You can leave a note to yourself about what you were doing in the description of the shelved changelist. Now revert your workspace files to restore your workspace to its unmodified condition; your shelved versions remain cached on the server. You can now start working on another coding task, and when you tire of the second task, shelve again to create a second shelved changelist. To go back to the first task, unshelve the first changelist. You can switch between tasks this way as often as you like.
Shelving gives you a way to make incremental snapshots of unsubmitted work in progress. The trick here is to create a new shelved changelist every time you want to save a snapshot of your files. To do that, your files can’t be in a shelved changelist, which is where the shelve command leaves them. That means that each time you shelve, you must then move your opened files back to the default changelist. Each invocation of the shelve command copies your files to the server and gives you a new, shelved change number that is a reference to a snapshot you can restore.
This is admittedly a bit more cumbersome than using your editor’s autosave. Why not just rely on that? Because for one thing, autosave works only on individual files. Shelving, by contrast, can scoop up all your opened files, creating a snapshot of your entire work in progress. For another, shelving saves all pending check-in data, including new file names, new file types, and resolved or unresolved merges. Your editor’s autosave can’t do that. Nor can your editor restore to a state that’s not in your undo stack. With shelving, you can save any number of important (or seemingly important) states on the server until you discard them explicitly. (Which brings up an important point: If you use shelving to make incremental snapshots, please be considerate and delete shelved changelists once you no longer need them. Your Perforce administrator will thank you for that.)
Even if you don’t need incremental snapshots, you’ll find that shelving makes a great safety net for resolving merges into files you’ve already edited. Just run shelve before you run resolve. After resolving, you can compare your workspace files to the shelved versions to make sure none of your own edits were mangled in the merge. If don’t like the result of a merge, you can revert the file and unshelve it to get your pre-resolved version back. This also restores the file’s pending resolve status, so now you can try resolving it a different way.
To sum up, there remains one question: how did we get by so long without shelving?
I have dream of functionnality like that for few years. I’m very exicting to use it.
Perforce is definitely my favourite Source Control !
Move/rename feature in 2009.1. Shelve feature in 2009.2. What will be the next great feature for 2010 ?
Francois
> To sum up, there remains one question: how did we get by so long without shelving?
Exactly.
This release looks very promising, with (finally) support for handoffs (usually when moving from work to home and back), (finally) support for offline (notebook in the train, anyone?) and (finally) the Dashboard, so you can see all resolve conflicts at once without clicking through every changelist.
Any chance the Dashboard will show files that could not be clobbered in a requested sync?
Looks very useful.
From a quick play, it’s not totally obvious (from the command line) that a changelist is in state ’shelved’. I expected the output of “p4 changes” to show “*shelved*” for status but it doesn’t.
C:\bruno_ws>p4 changes -l -s pending
Change 839 on 2009/12/10 by bruno@bruno_ws *pending*
Some shelved files
Change 833 on 2009/11/03 by bruno@bruno_ws *pending*
My new description
I then saw the following option:
C:\bruno_ws>p4 changes -s shelved
Change 839 on 2009/12/10 by bruno@bruno_ws *pending* ‘Some shelved files ‘
I then thought of:
C:\bruno_ws>p4 -ztag changes -l -s pending
… change 839
… time 1260438086
… user bruno
… client bruno_ws
… status pending
… shelved
… desc Some shelved files
A touch fiddly but workable. Obviously shelved changelists are still pending anyway so perhaps that is the reason (together with backwards compatibility concerns?).
For simple scripting it would be nice if one could pass in the description via a parameter instead of using -i (rather like “submit -d” although -d for shelve is used to delete which is understandable).
One danger if people get too attached to shelving is working out what has been shelved in what order and thus how to sensibly unshelve – guidance perhaps not to go overboard!
Robert
Hello Robert!
Although I’ve been shelving like mad lately, I have to admit I’ve been skirting the fiddly bits by using the Eclipse GUI (i.e., P4WSAD). It inserts a canned description when you shelve files, which you can edit later if you want. Would giving the command-line shelve the same behavior (as an option) make sense?
Laura
Bravo! This will replace the backup/restore perl scripts we use at work!
I am very excited about this. I’ve been using p4tar and p4untar from the Public Depot for some time, and it looks like the p4 shelve option will provide the same functionality. I haven’t used it yet, I’m waiting for the non-Beta 2009.2 since it requires a server update.
Hi Laura
I can imagine this feature getting lots of use, so just want there to be no speed bumps.
Just for completeness and to make scripting that little bit easier for people, the additional option would be useful I think.
Robert
A technical followup to this post that includes information about the method of server storage, space required, etc. might be cool!
“There are rumors that we’ll be able to do this in the future”. Really? I wonder who we could go to for confirmation? Maybe a vice president of product technology at Perforce Software would know for sure.
I’ve only read this quickly but it seems integrate the ‘CodePickle’ function into Perforce.
From my experimentation Matt, the file versions are stored as binary types even if the original is a text.
E.g. for ola.cpp, the submitted versions are stored as ~path/ola.cpp,v while the “shelved” versions are stored as ~path/ola.cpp,d/NNNN.gz where NNNN=changelist number.
Given the change in version numbering to store binary files with .gz rather than .gz this seems pretty simple and straight forward to both understand, and perhaps even to control/manage!
Robert
[...] announced on their blog that they have a new feature in beta testing called “shelve”. [...]
An option to “p4 shelve” to clean up the workspace a after shelving would be very useful.
Sometimes one does not want the modified files around, and instead of doing reverts after a shelve, better pass some flag to shelve to do it.
Also p4 help shelve
should mention how you can get a list of shelved changes.
We have upgraded but for some reason shelving doesn’t work.
We get this error:
Operation ‘open’ failed.
Database open error on db.resolvex!
open: db.resolvex: Permission denied
and haven’t worked it out yet. Found nothing in the documentation about having to change anything
@Eric: it looks like you have a more fundamental problem than what’s involved with shelving. Please contact our Support organization for assistance: http://www.perforce.com/perforce/support.html
-Marc
Will it be possible to use a shelved changelist as a source for integration?
Use case: I start work on a bug fix in branch 1.0. Subsequently, the decision is made to fix this in branch 2.0.
At this point, it would be really sweet to be able to shelve my change in 1.0 and integrate it into my 2.0 workspace.
What would be the syntax for accessing a shelved file using p4 print?
@Anders: no, you cannot use shelved files as the source for an integration. For your scenario, please see the KB article, “Branching Work In Progress”: http://kb.perforce.com/?article=56
@ChrisL: ‘p4 help shelve’ gives a hint: ‘p4 print //depot/path/to/file@=12345′ (just replace 12345 with the shelved changelist number of interest).
If you have any questions, please contact us in Support: http://www.perforce.com/perforce/support.html
Cheers,
-Marc
I heard a rumour… cracked it huh? Great move Laura / Perforce.
You implied here that a shelved changelist can be assigned to another user, “If you then assign the shelved changelist to a new owner, that user will now see it in her list of pending changes.” I’m unable to figure out how to do that in P4V or on the command line.
Any help you could provide would be greatly appreciated!
@Tyrel: Right now, you can use the p4 command line client to change ownership of a shelved changelist to another user; however, the next release of P4V (2010.1) will have the ability to do this within the tool.
@Marc: how exactly can you use the p4 command line client to change ownership of a shelved changelist?
What command does one use?
@Maria: After shelving some changes, ensure you first revert those files in your workspace, and then issue ‘p4 change 12345′ (where 12345 is the shelved changelist number). Simply edit the form and change the user field from your username to another user’s. Save and exit, and the shelved changelist will now belong to that other user.
@Anders: Further to your question about using a shelved changelist as a source for integration, Sam’s recent post on <a href="http://blog.perforce.com/blog/?p=2651"?p4 move -f: What It’s For may be of interest to you.