Shelve changelists
The P4 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 hand off changes and to perform code reviews.
Example: Shelving a changelist
Maria has made changes to command.c on a UNIX platform,
and now wants others to be able to view and test the changes.
The command:
p4 edit //Acme/dev/command.c
outputs:
//Acme/dev/command.c#9 - opened for edit
...
The command:
p4 shelve
outputs:
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 Maria’s workspace, and Maria can continue to work on the file, or can revert the changes and work on
something else.
To add a file to an existing shelved changelist, you must first open that file in that specific changelist. Shelved files remain open in the changelist from which they were shelved. 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
Maria has requested a code review and a cross-platform compatibility
check on the version of command.c that she shelved in
changelist 123. Olivia, who is using a Windows computer, types:
C:\olivia_ws\dev> p4 unshelve -s 123 //Acme/dev/command.c
//Acme/dev/command.c#9 - unshelved, opened for edit
and Olivia conducts the test in the Windows environment while Maria does 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
Maria’s version of command.c works on UNIX, but Olivia’s
cross-platform check of command.c has revealed a bug.
Olivia can take over the work from here, so Maria reverts her workspace
and works on something else.
The command:
p4 revert //Acme/dev/command.c
outputs:
//Acme/dev/command.c#9 - was edit, reverted
The shelved version of command.c is still available from
Maria’s pending changelist 123, and Olivia opens it in a new changelist,
changelist 124.
The command:
p4 unshelve -s 123 -c 124 //Acme/dev/command.c
outputs:
//Acme/dev/command.c#9 - unshelved, opened for edit
When Olivia is finished with the work, she can either re-shelve the file
for further
review in her own changelist 124, not Maria’s changelist 123, with the p4 reshelve command.
Alternatively, Olivia can discard
the shelved file and submit the version in her 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. To avoid these restrictions, you can 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. Olivia uses p4 shelve -d to
discard the shelved files.
C:\olivia_ws\dev> p4 shelve -d -c 124
Shelve 124 deleted.
All files in the shelved changelist are deleted. Olivia can now submit the changelist:
C:\olivia_ws\dev> p4 submit -c 124
The output is:
Change 124 submitted.
Olivia could have shelved the file in changelist 124, and let Maria unshelve it back into his original changelist 123 to complete the check-in.