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

P4 for Jenkins Documentation | 1.17.3

# p4unshelve: P4 Unshelve

The P4 Plugin plugin supports unshelving of one or more shelved changes into your Jenkins workspace as a build step.

The unshelve event is not recorded in the Jenkins build history.

## Example p4unshelve: P4 Unshelve configuration

### Example generated script for p4unshelve: P4 Unshelve

The form above generates the following script snippet:

    p4unshelve(
        credential: 'publicperforcecom1666',
        ignoreEmpty: false,
        resolve: 'none',
        shelf: '10831',
        tidy: false,
        workspace: manualSpec(
            charset: 'none',
            name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
            pinHost: false,
        spec: clientSpec(
            allwrite: false,
            backup: true,
            changeView: '',
            clobber: true,
            compress: false,
            line: 'LOCAL',
            locked: false,
            modtime: false,
            rmdir: false,
            serverID: '',
            streamName: '',
            type: 'WRITABLE',
            view: '''//depot/projects/alpha/... //${P4_CLIENT}/...
                     //depot/projects/beta/... //${P4_CLIENT}/...'''
            )
        )
    )

If you manually edit your script, remember to keep the single quotes that the snippet generator puts around the variables. Replacing them with full quotes " will expand the variables early and the script will fail. For more information about this, see Variable Expansion.

### Reduce the script snippet size to make it more readable

You can reduce the script size and make it easier to read by removing any options that are set to the default value.

Example script snippet with default values removed:

    p4unshelve(
        credential: 'publicperforcecom1666',
        shelf: '10831',
        workspace: manualSpec(
            name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
            spec: clientSpec(
                view: '''//depot/projects/alpha/... //${P4_CLIENT}/...
                         //depot/projects/beta/... //${P4_CLIENT}/...'''
                )
            )
        )
    )

### Paste the script snippet into a basic script

Example: the script snippet above has been pasted into a basic script:

    pipeline {
        agent any
        stages {
            stage('Unshelve') {
    			steps() {}
    				// unshelve changelist
    				p4unshelve(
    					credential: 'publicperforcecom1666',
    					shelf: '10831',
    					workspace: manualSpec(
    						name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
    						spec: clientSpec(
    							view: '''//depot/projects/alpha/... //${P4_CLIENT}/...
    									 //depot/projects/beta/... //${P4_CLIENT}/...'''
    							)
    						)
    					)
    				)
    			}
            }
        }
    }

## Configure a p4unshelve: P4 Unshelve script

1. To unshelve changes into your workspace, select p4unshelve: P4 Unshelve from the Sample Step dropdown of the snippet generator.

2. Select the credentials for the job from the Perforce credentials dropdown.

### Workspace behavior

- Use a unique workspace name for the Jenkinsfile that will not get reused by the sync steps in the script. A postfix of -script will help to identify the workspace's use and make it unique from code sync steps.
- Only map the Jenkinsfile (and perhaps Pipeline libraries) in the workspace view. Jenkins may create an @script directory on the controller and you don't want to unnecessarily sync code to an area not used for the actual build.

The Workspace behavior you select determines which configurations are available to you.

Many of the workspace fields can include environment variables to help define their value.

To enable you to identify builds, consider using variables in the Workspace name. For more information about environment variables, see Variable Expansion.

Perforce workspaces support the following behaviors:

- Manual (custom view): Manually define the workspace view and sync options. Creates the workspace if it does not already exist or updates the workspace spec by setting the various options if it already exists. Jenkins will fill out the workspace root and may override the clobber option. For details about manually configuring your workspace, see Manual workspace.
- Spec File (load workspace spec from file in Perforce): Loads the workspace configuration from a depot file containing a client workspace spec. This is the same output as p4 client -o and the Spec depot .p4s format. The name of the Workspace must match the name of the client workspace spec. For details about using a spec file for your workspace, see Spec File workspace.
- Static (static view, controller only): Uses a predefined workspace, the workspace must have a valid view and must already exist. The plugin user must either own the workspace or the spec must be unlocked allowing the plugin user to make edits. The workspace view remains static, but Jenkins will update other fields such as the workspace root and clobber option. For details about using a static predefined workspace, see Static workspace.
- Streams (view generated by Perforce for each node): Uses a specified stream to generate the workspace view. The name of the workspace is generated using the Workspace Name Format field. This makes it an ideal choice for Matrix builds. For details about using a stream to generate the workspace, see Streams workspace.
- Template (view generated for each node): Uses a specified template to generate the workspace view. The name of the workspace is generated using the Workspace Name Format field. This makes it an ideal choice for Matrix builds. For details about using a template to generate the workspace, see Template workspace.

### Unshelve Changelist

- Unshelve Changelist: Select the changelist you want to unshelve for the build by entering the change-list number or a custom environment variable ${VAR}. For more information about environment variables, see Variable Expansion.
- Resolve Options: Select the type of resolve to use for the unshelved files. This is needed if the shelved file revisions are different to the files sync'ed in the workspace.
  - Resolve: None: The current workspace files are used for the build.
  - Resolve: Safe (-as): Accepts the file in the depot if it has the only changes. Accepts the file in the workspace if it has the only changes. Doesn’t resolve if both the depot and workspace files have changed.
  - Resolve: Merge (-am): Accepts the file in the depot if it has the only changes. Accepts the workspace file if it has the only changes. Merges changes if both the depot and workspace files have changed and there are no conflicts.
  - Resolve: Force Merge (-af): Accepts the file in the depot if it has the only changes. Accepts the workspace file if it has the only changes. Creates a merged file if both the depot and workspace files have changed, even if there are conflicts. Where there are conflicts, both versions are included with text notations indicating the conflicts.
  - Resolve: Yours (-ay): -- keep your edits: Uses the file that is in the workspace and ignores the version of the file that is in the depot.
  - Resolve: Theirs (-at) -- keep shelf content: Replaces the copy of the file in the workspace with the revision that is in the depot, discards any changes in the workspace file.
- Clean up Review actions: Reverts open files in the pending changelist, but leaves the content in the workspace unchanged. Equivalent to p4 revert -k. If this option is not selected an error is displayed.
- Ignore this step if Changelist value not set: Select to ignore the Perforce: Unshelve build step if Unshelve Changelist has no value. This is useful if you are using a variable that can leave the value unset for some builds.

### Generate Pipeline Script

To generate the pipeline script, click Generate Pipeline Script. The script is generated in the text box below the button.

Copy the generated script and paste it into the Script box on the Jenkins Pipeline Script page.

Your search for returned results