si checkpoint

CLI Reference > Configuration Management Commands > si checkpoint

si checkpoint

checkpoint archives in a project

Synopsis

si checkpoint [--author=name] [(-d desc|--description=desc)] [--descriptionFile=file] [--[no]notify] [(-L label| --label=label)] [--[no]labelUnchangedSubprojects] [--[no]failOnAmbiguousProject] [--asof=date] [(-s state|--state =state)] [(-P project|--project=project)] [(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--hostname=server] [--port=number] [--password=password] [--user=name] [(-?|--usage)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] [--[no]checkpointUnchangedSubprojects]

Description

You can track the evolution of an entire project by preserving the changes made to it from one revision to another. In Integrity Lifecycle Manager, this process is called checkpointing. For example,

si checkpoint --project=c:/Aurora_Program/bin/Libra/project.pj --label="Release Candidate 002" --description="Ready for Review" --notify

Checkpointing a project creates a new revision of the project and adds it to the project history. When you checkpoint a project, you save all the information needed to recreate the project completely at any time in the future. The saved information includes the project structure and the list of members with their revision numbers.

You can either perform a checkpoint on the current configuration of the project, or you can specify a date in the past (using the --asof option) to perform a retroactive checkpoint at that specific date.

Checkpointing as of a date can be useful to reduce the number of total checkpoints on a project by only retroactively checkpointing the exact project configuration that you intend to use as a baseline, instead of creating checkpoints of current project configurations that might never be used. When checkpointing as of a date, the best practice is to specify a label to facilitate later identification of that checkpoint.

Date-based checkpoints (a project configuration as of a specific date) have all of the same capabilities as regular checkpoints, but they are identified differently when they are used or appear in the project history. A regular checkpoint is identified using an Integrity Lifecycle Manager revision ID; for example, checkpointing a project at 1.1 results in revision 1.2. However, a date-based checkpoint for a project whose nearest regular checkpoint (not date-based) prior to that date is at revision 1.1 results in revision of 1.1.0.0.date.identifier, where date is the date of the project configuration (presented in milliseconds since the epoch) and identifier is an integer (usually 0, but higher if there were simultaneous operations). For example, checkpointing a project configuration that was January 5, 2015, 19:51:29 GMT (and no simultaneous operations) results in a revision ID of 1.1.0.0.1420487490.0. For supported date formats, see the description of the --asof option .

All checkpoints are transactional. This means that a checkpoint records the structure and contents of the project at the checkpoint date. It does not include anything added to the project or its subprojects after the checkpoint date, such as check ins or submitted change packages. To ensure that only complete change packages are included in your project checkpoints, your administrator must enable change package reviews. For more information on change package reviews, see the Integrity Lifecycle Manager Help Center.

While the checkpoint is in progress, you can perform member and subproject operations on the project, but you cannot perform any operations that affect project checkpoints, development paths, or labels. You cannot perform the following operations:

• Checkpoint the project on another development path

• Restore the project to a previous checkpoint

• Delete the project from the database

• Add or delete project labels

• Create or remove development paths

Checkpointing a project checkpoints all its subprojects. If you do not want to create subproject checkpoints, configure them as build subprojects first. See the si configuresubproject command for more details.

Options

This command takes the universal options available to all si commands, as well as some general options. See the options reference page for descriptions.

• --author=name

specifies an author name to identify the author of the new revision.

• -d desc

• --description=desc

specifies a description for the checkpointed revisions. These options and the --descriptionFile option are mutually exclusive.

Descriptions that include spaces must be enclosed by quotes.

• --descriptionFile=file

specifies a file name, file, containing the description text for the checkpointed revisions. This option and the -d or --description options are mutually exclusive.

• --[no]notify

controls whether to notify when the checkpoint is complete.

• -Llabel

• --label=label

identifies a label. The label is applied to the checkpointed revision of the project. Note the following about using labels:

• Labels cannot contain colons(:), square brackets ([ ]), or leading spaces.

• Labels cannot have the same format as a valid revision number.

• Labels that include spaces must be enclosed by quotes.

• PTC recommends not using hyphens (-) in labels. Using hyphens may cause some si commands to fail.

• -s state

• --state=state

specifies a state, state, for the checkpointed revisions. The state is applied to the checkpointed revision of the project.

• --[no]labelUnchangedSubprojects

adds the project label to both unchanged subprojects and build subprojects. To reduce the command impact on users, the labels are applied after the lock on the project hierarchy is released.

• --asof=date

specifies the project configuration as of a specific date. For example, --asof="April 28, 2014 3:33:45 AM GMT-05:00".

Integrity Lifecycle Manager recognizes all current timezones whatever your locale (country), for example, CEST, CET, EDT, PST, or GMT+/-hours:minutes. The following information illustrates North American timestamps recognized by Integrity Lifecycle Manager:

• --[no]checkpointUnchangedSubprojects

specifies if to checkpoint unchanged subprojects. If this option is not specified, subprojects that have not changed are not checkpointed; instead the existing revision for the subproject is used in the parent project checkpoint revision.

If this option is not specified, the following is true:

◦ The checkpoint description is not added or appended to the project revision for the unchanged subprojects.

◦ If the --[no]labelUnchangedSubprojects option is not set, the checkpoint label is not added to the revision for the unchanged subprojects.

◦ If the subproject revision was created prior to Integrity 10.7, the unchanged subproject is checkpointed and its revision incremented. Only subproject revisions created by Integrity 10.7 or later can be detected as unchanged.

Diagnostics

See the diagnostics reference page for possible exit status values.

Preferences

Using si setprefs or si viewprefs, you are able to set or view the preference keys for this command.