Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Reference | 2025.1

# p4 shelve

Store files (or a stream spec) from a pending changelist in the depot without submitting them.

## Syntax

    p4 [g-opts] shelve [-As] [-p] [--parallel=threads=N[,batch=N]]
    p4 [g-opts] shelve [-Af] [-p] [--parallel=threads=N[,batch=N]] files]
    p4 [g-opts] shelve [-Af | -As] [-a option] [-p] -i [-f | -r] [--parallel=threads=N[,batch=N]  [,min=N]]]
    p4 [g-opts] shelve [-Af | -As] [-a option] [-p] -r -c changelist# [--parallel=threads=N[,batch=N] [,min=N]]
    p4 [g-opts] shelve [-As] [-a option] [-p] -c changelist# [-f] [--parallel=threads=N[,batch=N] [,min=N]]
    p4 [g-opts] shelve [-Af] [-a option] [-p] -c changelist# [-f] [--parallel=threads=N[,batch=N] [,min=N]] file ...]
    p4 [g-opts] shelve [-As] -d -c changelist# [-f]
    p4 [g-opts] shelve [-Af] -d -c changelist# [-f]  file ...

Syntax conventions

## Description

Shelving is the process of temporarily storing work-in-progress without submitting a changelist. Shelving is useful when you need to:

- Perform multiple development tasks on the same set of files, such as testing across multiple platforms,

  or

- Share files for code review before committing your work to the depot.

The `p4 shelve` command creates, modifies, or discards one or more 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. `p4 shelve` displays the working revision for the files being shelved.

In addition to the files being shelved, `p4 shelve` also shelves any open stream specification. To learn more, see `p4 stream`.

After shelving files, you can:

- Revert or modify them in your client workspace.
- 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 by using the revision specifier `@=`change``, where `change` is the pending changelist number.

If you are working in a multi-server 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 multi-server 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. See Usage notes and "Promoting shelved changelists" in the P4 Server Administration Documentation.

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 FileSpec is given, `p4 shelve` shelves only the files that match the FileSpec.

To add a file to a pre-existing shelf, the file must first be opened in the changelist for the shelved file(s).

To move an opened file from one changelist to another, use the `p4 reopen` command.

### Multiple files

When you create a shelf from files opened in the default changelist, the syntax of [FileSpec] means a single file pattern, such as:

p4 shelve ....html

and wildcards are allowed to specify multiple files.

However, when opened files are in a numbered change, multiple file arguments are possible:

p4 shelve -c 77 ....html "*.c" "*.java"

### Parallel shelving

All parallel processing on the server is regulated using the `net.parallel.max` configurable:

- To disable parallel processing, set to 0 or 1

- To enable parallel processing and specify the maximum number of concurrent threads for a single p4 shelve, p4 sync, or p4 submit command, set a value between 2 and 100. Configuration or command line options that request a greater number of parallel threads than the value of net.parallel.max remain limited to the net.parallel.max value.

Too many threads can degrade performance.

#### Manual shelving in parallel

The p4 shelve --parallel option allows you to use parallel processing for shelving and specify parameters for the shelving operation:

- Specify threads=N to control the number of independent network connections available for concurrent file transfer, so that each thread can transfer its respective file.

- Specify batch=N to control the number of files in a batch that the N threads grab.

- Specify min=N to control the minimum number of files necessary for a parallel shelve operation to occur.

Promoted shelves require an additional file transfer from the edge server to the commit server. Parallel pull threads for this transfer are only used if the ExternalAddress field is set in its edge server spec and pull threads can be used on the commit server.

#### Automatic shelving in parallel

To enable automatic parallel shelving, set the net.parallel.shelve.threads configurable to a value greater than `1`.

Configurable | Default value | For auto parallel shelve
--- | --- | ---
net.parallel.shelve.threads | 0 | The number of threads.
net.parallel.shelve.batch | 8 | The number of files in a batch.
net.parallel.shelve.min | 9 | The mininum number of files.

To learn more, see See Parallel processing for submits, syncs, and shelves in the P4 Server Administration Documentation.

### Delete a shelf

- p4 obliterate myfile does not obliterate a shelf of the file (archive or metadata). Attempting to unshelve a file that has been obliterated results in an error.

- To recover the content of that file, use the p4 print command.

- To get rid of the shelve, delete the shelf.

- A shelf can be partially deleted. See the `-d` option.

### Streams and shelves

By default, if the stream spec is open, it will also be included with any shelved changelist. See the command line output of p4 help streamcmds

By default, a stream spec is not deleted until all files have been deleted.

### Suffix to avoid duplicate archive files

Any new file being shelved that has the same content as an existing shelved file refers to the existing archive file instead of creating a duplicate archive file. To avoid overwriting the content of shelves that share archives, the archives of the new shelved files have an additional numerical suffix. For example, `1.1.1.gz` instead of `1.1.gz`

## Options

-Af | Specifies that only files be shelved with this changelist.
-As | Specifies that only an opened stream specification be shelved with this changelist. By default, if the stream spec is open and neither -Af nor -As is given, the stream specification is included with any shelved files. (See p4 help streamcmds)
`-a option` | The `submitunchanged` (default) option shelves all files. The `leaveunchanged` option shelves only the changed files. It leaves the unchanged files opened at the numbered pending changelist.
`-c change` | Specify the pending changelist in which shelved files are to be created, discarded, or modified. Only the user and client that owns the pending changelist can add or modify its shelved files. (Administrators can use `-f` to discard files.) Any files specified by a file pattern must already be open in the specified changelist. To move an opened file from one changelist to another, use `p4 reopen` .
`-d` | Using -d -c flag deletes the shelved files in the specified changelist so that they are no longer available for `p4 unshelve` operations. For example, `p4 shelve -d -c 77 //depot/proj1/document3.txt` might return: `Shelved change 77 partially deleted, still contains 2 file(s).` By default, only the user and client of the pending changelist can delete its shelved files. A user with admin access can delete shelved files by including the -f flag to force the operation. For example, `p4 shelve -f -d -c 77 //depot/proj1/document3.txt` If the shelved changelist includes a stream spec, by default it is deleted when all the files have been deleted. The combination of -d -As forces the stream spec to be deleted even if files remain. To completely delete a shelved changelist, delete all shelved files, revert any open files in the shelved changelist, then delete the change with the p4 change command: `p4 change -d 77`
`-f` | To force an overwrite any existing shelved files in a pending changelist, use the -f option with the -c or -i option. Force the overwriting of any existing shelved files in a pending changelist with the contents of their client workspace copies. P4 Server administrators can use this option with `-d` to force the discarding of shelved files in a specified changelist. Using this option will delete shelved files that are the source of pending resolves. If this happens, the resolving user will not be able to merge content from the shelf. The user must either ignore (`-ay`) the missing shelf or revert.
`-i` | Reads the pending changelist specification with shelved files from the standard input. The user's editor is not invoked. To modify an existing changelist with shelved files, specify the changelist number using the -c option.
`-p` | Promote a shelved change from an edge server to a commit server where it can be accessed by other edge servers participating in the multi-server 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. The combination of -p -c promotes the shelf without modification unless -f or -r are also used to update the shelved files before promotion.
`-r` | Replace all shelved files in the changelist with the files that are opened in your workspace. The `-r` option (used with `-c` or `-i`) enables you to replace all shelved files in that changelist with the files opened in your own workspace at that changelist number. Previously shelved files will be deleted. Only the user and client workspace of the pending changelist can replace its shelved files.
`--parallel` | Specifies that multiple files should be transferred in parallel, using independent network connections from automatically-invoked child processes. This option can contain a suboption, `batch`, to specify the number of files in a batch, as well as the min suboption to set the minimum number of files required for a parallel shelve. See also the configurables net.parallel.shelve.batch, net.parallel.shelve.min, and net.parallel.shelve.threads.
`g-opts` | See Global options.

## Usage notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required
--- | --- | ---
Yes | Yes | `open` If the user doesn't have open access for all the files in the shelve command, the shelve command fails.

A promoted shelf is a shelf that exists on the commit server of a multi-server configuration because:

- It was directly created on the commit server, or

- It was promoted from the edge server with the `-p` option of the `p4 shelve` command, or

- The edge server and commit server access the same archive contents. See "Automatically promoting shelves" under Promoting shelved changelists in the P4 Server Administration Documentation.

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 is created. A normal shelf can be promoted after it is created by running:

    p4 shelve -p -f -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:

1. Promote the shelf you want to copy on the P4 Server from where you want to copy it, say Server X.
2. Unshelve the shelf in the server to which you want to copy it, say Server Y.
3. 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. However, you can promote it.

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:

- 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.

## Examples

p4 shelve -c 65 Shelve the entire shelve at the specified changelist number.
p4 shelve -c 65 -As Shelve only the stream spec.
p4 shelve -c 65 -Af a1/... Shelve only the files that match the filespec.

## Related commands

To restore shelved files into a workspace | `p4 unshelve`

Your search for returned results