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.