p4 shelve
Synopsis
Store files from a pending changelist in the depot, without submitting them.
Syntax
p4 [g-opts] shelve [-p] [files]
p4 [g-opts] shelve [-a option] [-p] -i [-f | -r ]
p4 [g-opts] shelve [-a option] [-p] -r -c changelist
p4 [g-opts] shelve [-a option] [-p] -c changelist [-f] [file ...]
p4 [g-opts] shelve -d -c changelist [-f] [file ...]
Description
Shelving is the process of temporarily storing work in progress in the Perforce versioning service without submitting a changelist. Shelving is useful when you need to perform multiple development tasks (such as interruptions from higher-priority work, testing across multiple platforms) on the same set of files, or when you need to share files for code review before committing your work to the depot.
The p4 shelve command creates, modifies, or discards shelved files in a pending changelist. Shelved files persist in the depot until they are discarded (by means of p4 shelve -d) or replaced by subsequent p4 shelve commands.
After shelving files, you can revert or modify them in your client workspace. You can also restore the shelved versions of those files to your workspace with the p4 unshelve command.
While files are shelved, other users can unshelve the shelved files into their own workspaces, or into other client workspaces.
Files that have been shelved can also be accessed with the
p4 diff,
p4 diff2,
p4 files, and
p4 print commands,
using the revision specifier
@=, where
changechange is the pending changelist number.
If you are working in a distributed environment, use the
-p option to promote a shelved change from an edge server
to a commit server where it can be accessed by other edge servers in the
distributed configuration. When an existing shelved change is promoted, it
is promoted without modification unless the -f or
-r options are also used to change the shelved file
content. For more information about the use of shelves in distributed
environments, see Usage Notes below and also
Perforce
Server Administrator's Guide: Multi-site Deployment.
If no arguments are specified, p4 shelve creates a new changelist, adds files from the user's default changelist, and (after the user completes a form similar to that used by p4 submit), shelves the specified files into the depot. If a file pattern is given, p4 shelve shelves only the files that match the pattern.
In order to add a file to a pre-existing shelve, the file must first be opened in the shelve's changelist; use p4 reopen to move an opened file from one changelist to another.
Options
|
|
Force the overwriting of any existing shelved files in a pending changelist with the contents of their client workspace copies.
Perforce administrators can use this option with
|
|
|
Read a changelist description from standard input. Input must be
in the same format used by the p4 shelve
form. (When modifying an existing changelist with shelved files,
this option also implies |
|
|
The |
|
|
Specify the pending changelist in which shelved files are to be created, discarded, or modified.
Only the user and client workspace that owns the pending
changelist can add or modify its shelved files. (Administrators
can use Any files specified by a file pattern must already be open in the specified changelist; use p4 reopen to move an opened file from one changelist to another. |
|
|
Discard the shelved files in the specified changelist so that they are no longer available for p4 unshelve operations.
Only the user and workspace that owns the pending changelist can
discard its shelved files. (Administrators can use
|
|
|
Replace all shelved files in the changelist with the files that
are opened in your workspace. (To replace the files in the
changelist with files open at a specific change number, use the
|
|
|
Promote a shelved change from an Edge server to a Commit server where it can be accessed by other edge servers participating in the distributed configuration. Once a shelved change has been promoted, all subsequent local modifications to the shelf are also pushed to the commit server and remain until the shelf is deleted. See Usage Notes for more information. |
|
|
See the “Global Options” section. |
Usage Notes
|
Can File Arguments Use Revision Specifier? |
Can File Arguments Use Revision Range? |
Minimal Access Level Required |
|---|---|---|
|
Yes |
Yes |
|
A promoted shelf is a shelf that exists on the Commit server of a
distributed configuration. It is there either because it was directly
created on the Commit server or because it was promoted with the
-p option of the p4 shelve command.
Commands that access shelves know how to handle promoted shelves.
To unpromote a shelf, delete the shelf and create a new one.
A shelf can be promoted when it's first created. A normal shelf can be promoted after it is created by running one of the following commands:
shelve -p -f -c myChange shelve -p -r -c myChange
Promoting a shelf gives you a way to move a shelf from one server to another. To do this, you must complete the following steps:
-
Promote the shelf you want to copy on the server from where you want to copy it, say server X.
-
Unshelve the shelf in the server to which you want to copy it, say server Y.
-
Shelve the change on server Y; this opens the files in a change that is owned by server Y. The new shelf is created as a non-promoted shelf; but you can promote it if you like.
To determine whether a shelved change is promoted, you can try to access the shelf on a server other than the server that owns the change, or you can look at the output of the p4 -ztag changes command.
Observe the following limitations when working with promoted shelves:
-
If you're not on the server owning the shelf, you can't unshelve a remote promoted shelve into already-open local files.
-
If you're not on the server owning the shelf, you can't unshelve into a different branch (
-b-S). -
You can't unload an Edge server workspace if you have promoted shelves.
-
Use promoted shelves sparingly; shelf promotion and shelf access are time-consuming operations.