Promoting shelved changelists

Changelists shelved on an edge server, which would normally be inaccessible from other edge servers, can be automatically or explicitly promoted to the commit server. Promoted shelved changelists are available to any edge server.

  • In a shared archive configuration, where the commit server and edge servers have access to the same storage device for the archive content, shelves are automatically promoted to the commit server. See Automatically promoting shelves.
  • You must explicitly promote a shelf when the commit and edge servers do not share the archive. See Explicitly promoting shelves.

You can view a shelf’s promotion status using the -ztag output of the p4 describe, p4 changes, or p4 change -o commands.

See Working with promoted shelves for more information on the limitations of working on promoted shelves.

Automatically promoting shelves

When the edge server and commit server are configured to access the same archive contents, shelf promotion occurs automatically, and promoting shelved files with p4 shelve -p is not required.

To configure the edge server and commit server to access the same archive contents, set server.depot.root to the same path for both the commit and edge server, and set the lbr.replication configurable to shared for the edge server. For example:

$ p4 configure set commit#server.depot.root=/p4/depot/root
$ p4 configure set edge#server.depot.root=/p4/depot/root
$ p4 configure set edge#lbr.replication=shared

Explicitly promoting shelves

Two ways of explicitly promoting shelves:

  • Set the dm.shelve.promote configurable to 1


    This makes edge servers automatically promote shelved files to the commit server. The file content is transferred and stored both on the commit server and the edge server.

    Setting dm.shelve.promote affects performance.

    This does NOT transfer shelves created on the commit server to the edges servers.

    If you are using Helix Swarm on an edge server, automatic promotion is necessary. See "Configure the Helix Server to promote all shelved changes" under Helix Core Server configuration for Swarm in Helix Swarm Guide.

  • Use the -p option with the p4 shelve command.

    See the example below for more information on this option.

For example, given two edge servers, edge1 and edge2:

  1. Shelve and promote a changelist from edge1.

    edge1$ p4 shelve -p -c 89
  2. The shelved changelist is now available to edge2.

    edge2$ p4 describe -S 89
  3. Promotion is only required once.

    Subsequent p4 shelve commands automatically update the shelved changelist on the commit server, using server lock protection. For example, make changes on edge1 and refresh the shelved changelist:

    edge1$ p4 shelve -r -c 89

    The updates can now be seen on edge2:

    edge2$ p4 describe -S 89

Promoting shelves when unloading clients

Use the -p option for the p4 unload command to promote any non-promoted shelves belonging to the specified client that is being unloaded. The shelf is promoted to the commit server where it can be accessed by other edge servers.

Working with promoted shelves

You can:

  • delete the shelved files from the changelist, but you cannot unpromote a shelved changelist
  • unshelve a promoted shelf into open files and branches on a server from where the shelf did not originate
  • run p4 submit -e on a promoted shelf only on the server that owns the change
  • move a promoted shelf from one edge server to another using the p4 unshelve command