Shelve changelists
The Helix Server shelving feature enables you to temporarily make copies of your files available to other users without checking the changelist into the depot.
Shelving is useful for individual developers who are switching between tasks or performing cross-platform testing before checking in their changes. Shelving also enables teams to easily hand off changes and to perform code reviews.
Example Shelving a changelist
Earl has made changes to command.c on a UNIX platform,
and now wants others to be able to view and test his changes.
$ p4 edit //Acme/dev/command.c
//Acme/dev/command.c#9 - opened for edit
...
$ p4 shelve
Change 123 created with 1 open file(s).
Shelving files for change 123.
edit //Acme/dev/command.c#9
Change 123 files shelved.
A pending changelist is created, and the shelved version of
command.c is stored in the server. The file
command.c remains editable in Earl’s workspace, and Earl
can continue to work on the file, or can revert his changes and work on
something else.
Shelved files remain open in the changelist from which they were shelved. (To add a file to an existing shelved changelist, you must first open that file in that specific changelist.) You can continue to work on the files in your workspace without affecting the shelved files. Shelved files can be synced to other workspaces, including workspaces owned by other users. For example:
Example Unshelving a changelist for code review
Earl has asked for code review and a cross-platform compatibility
check on the version of command.c that he shelved in
changelist 123. Bruno, who is using a Windows computer, types:
C:\bruno_ws\dev> p4 unshelve -s 123 //Acme/dev/command.c
//Acme/dev/command.c#9 - unshelved, opened for edit
and conducts the test in the Windows environment while Earl continues on with other work.
When you shelve a file, the version on the shelf is unaffected by commands that you perform in your own workspace, even if you revert the file to work on something else.
Example Handing off files to other users
Earl’s version of command.c works on UNIX, but Bruno’s
cross-platform check of command.c has revealed a bug.
Bruno can take over the work from here, so Earl reverts his workspace
and works on something else:
$ p4 revert //Acme/dev/command.c
//Acme/dev/command.c#9 - was edit, reverted
The shelved version of command.c is still available from
Earl’s pending changelist 123, and Bruno opens it in a new changelist,
changelist 124.
$ p4 unshelve -s 123 -c 124 //Acme/dev/command.c
//Acme/dev/command.c#9 - unshelved, opened for edit
When Bruno is finished with the work, he can either re-shelve the file
(in his own changelist 124, not Earl’s changelist 123) for further
review — with the p4 reshelve command — or discard
the shelved file and submit the version in his workspace by using
p4 submit.
The p4 submit command has a -e option
that enables the submitting of shelved files directly from a changelist.
All files in the shelved change must be up to date and resolved. Other
restrictions can apply in the case of files shelved to stream targets;
see the
Helix Core Command-Line (P4) Reference
for details. (To avoid dealing with these restrictions, you can always
move the shelved files into a new pending changelist before submitting
that changelist.)
Example Discarding shelved files before submitting a change
The Windows cross-platform changes are complete, and changelist 124 is
ready to be submitted. Bruno uses p4 shelve -d to
discard the shelved files.
C:\bruno_ws\dev> p4 shelve -d -c 124
Shelve 124 deleted.
All files in the shelved changelist are deleted. Bruno can now submit the changelist.
C:\bruno_ws\dev> p4 submit -c 124
Change 124 submitted.
Bruno could have shelved the file in changelist 124, and let Earl unshelve it back into his original changelist 123 to complete the check-in.
