Fetching, pushing, and changelists

When changelists are added to the target server during a fetch or a push, they are given new change numbers but they retain the same description, user, date, type, workspace and set of files.

When the files are added to the target server during a fetch or a push, they are kept in their same changelists, as new revisions starting after the current head. The new revisions retain the same revision number, file type, action, date, timestamp, digest, and file size.

Although the changelists are new submitted changelists in the target server for a fetch or a push, none of the submit triggers are run in the target server. For more information about submit triggers, see the "Scripting Perforce" chapter in the Helix Versioning Engine Administrator Guide: Fundamentals.

If a particular changelist includes some files that match the filespec or stream restriction, and other files that do not, then only the matching files are included in the fetch or push. Note that if a remote spec is also provided, only the files that match the restriction and are mapped by the remote spec are included in the fetch or push. In other words, not all files in the changelist will necessarily be fetched or pushed. For example, consider the following DepotMap in a remote spec: 

//stream/main/p4/... //depot/main/p4/...

Suppose you have a changelist with the following files:

//stream/main/p4/foo
//stream/jam/bar

Only //stream/main/p4/foo will be pushed or fetched, as it matches the remote spec mapping.

Fetch and push a shelved changelist

The Helix Versioning Engine allows you to fetch, push (and zip) a shelved changelist instead of one or more submitted changelists. This gives you more flexibility if your workflow typically involves shelved changelists.

Note

Both the local and the remote server must be version 2016.1 or higher to support copying a shelved changelist.

Copying a shelf always results in the creation of a new shelf in the destination server; existing shelves, even if similar, are not overwritten.

There are two key differences between copying a submitted changelist and copying a shelved changelist:

  • To copy a submitted changelist, you must have write access to the changelist’s files; by contrast, need to have open access to the shelf’s files in the target server. As a reminder, open access means the user can open add, edit, delete, or integrate the files.
  • The resulting new shelf is owned by the user who issued the push, fetch, or zip command, even if the shelf copied was owned by a different user.

Track a changelist’s identity from server to server

As described earlier, a changelist gets renumbered each time it gets fetched, pushed, or unzipped; as a result, it quickly becomes difficult to determine which changelist is which across a series of servers. Changelist 12 on one server may not be the same as changelist 12 on another server.

The Helix Versioning Engine includes a global changelist ID feature which allows you to assign to a changelist a permanent ID that remains the same from server to server. This is an opt-in feature. There are two workflows for enabling global changelist IDs. They are summarized in the following subsections:

Workflow 1: Let Helix generate global changelist IDs

The majority of Helix users will likely choose to have global changelist IDs system-generated.

To have Helix generate the IDs for you, follow these steps:

On a personal server:

  1. Run the p4 configure command to set submit.identity to whichever of the three possible formats you prefer:

    • uuid: a universally-unique identifier
    • checksum: a checksum
    • serverid: a combination of the serverid + changelist number

    This causes Helix to generate a global changelist ID and write it to the Identity field of the change spec for the changelist in question, each time a change is submitted. For more information, see the description of the submit.identity configurable in the "Configurables" chapter of the P4 Command Reference.

  2. Run p4 submit to submit the changelist. Once you’ve done this, the changelist ID appears in the Identity field of the change spec.
  3. Run p4 describe changelistnumber to find out what changelist ID was generated.

Workflow 2: Enter global changelist ID manually

Choose this workflow if you want to customize your global changelist ID names. For example, you may want to name a changelist according to the bug it corresponds to in your bug database.

On a personal server:

  1. Run p4 submit to submit your changelist.
  2. Edit the change spec to set the value of the Identity field to the desired value.
  3. Run the p4 push, p4 fetch, or p4 unzip command.

On the shared server:

  1. Run p4 describe -I changelistID to retrieve the changelist number of the changelist that was pushed, fetched, or unzipped.

Track who pushed, fetched, or unzipped a changelist

The Helix Versioning Engine includes a feature — relevant only for users of the Helix’s distributed versioning features (DVCS) — that lets you distinguish between who created a particular changelist and who pushed, fetched, or unzipped it later. This gives you more visibility into scenarios in which one user pushes, fetches, or unzips another user’s work.

You use the change spec’s ImportedBy field — via the p4 change command — to specify the name of the user who ran the p4 fetch, p4 push, or p4 unzip command that imported this changelist into the shared server.

The ImportedBy field is filled in at the point when Helix stores the changelist in the target shared server.