Update modes
Update modes work by comparing three pieces of data: the version of a file or resource that is expected to be in the workspace (expected version), the version of the file or resource that is actually in the workspace (actual version) and the version of the file or resource that is coming in due to the update (target version). By comparing these three numbers, the tool can decide which version of the file or resource to update to based on the update mode used.
Helix IPLM supports updates to workspaces that retain local changes, while bringing in changes to untouched files from other releases. These updates are referred to as Update Modes.
When performing workspace updates there are three things we have to consider about any object being updated (either file or resource):
| Update Considerations | Description |
|---|---|
| Original Version | The version of the object specified in the IP that brought the object into the workspace. In the case of files, this is the file version specified by its IP, in the case of Resources it is the version of the resource called for by the top level IPV in the workspaces' release. |
| Current Version | The version of the file or resource currently in the workspace. If the Current version does not match the Original version the object is said to be modified. |
| Target Version | The version of the file or resource that is the target of the update command (the "update to" version) |
Types of conflicts
When a workspace contains various IPs at different versions, there are three kinds of conflicts that are possible:
- File content conflict: in this case, a user edits a file which is also edited by a different user in a different workspace. Most DM tools like Perforce and SVN handle these kinds of conflicts, giving the user multiple resolution options. These conflicts need to be resolved when committing changes back to the DM system ('p4 submit' for example). Users can choose to keep only their local changes, abandon their local changes, or keep some mix of the changes as desired.
- File Version Conflict: In this case, the version of a specific file in a user's workspace is different from the expected version (based on the release of the IP containing that file). This can happen if a user specifically syncs a file or set of files to different versions using native DM commands in the workspace, or makes changes to the file and submits the changes back to the DM system one or more times. In this case, if the user runs a 'pi update' command, then there may be a difference between the target version (the version of the file that is incoming from the update) and the version in the workspace.
- Resource Version Conflict: In this case, the version of a IP in the workspace is different from the expected version (based on the CIPB of the top level IP in the workspace). This can happen if the user specifically updates a resource to a different version than the one in the workspace using 'pi update LIB.IP' command. Now if the user runs a 'pi update' on the top level IP, then there may be a difference between the target version of the resource (the version of the resource that is incoming from the update) and the version in the workspace.
File content conflict is handled by the native DM tool like Perforce and SVN. File and resource version conflicts are handled by Helix IPLM's update modes as described below.
Update mode types
There are three update modes for a workspace:
- Force or exact: This mode, as the name suggests, will update a workspace to the exact contents of a release. This is activated by running 'pi update --force' or 'pi update -f'.
- Keep Local: This mode will keep local changes - files or resources that have been moved away from their current release versions, while updating all the other files and resources that have changed in the target release. This can be activated by using the 'pi update -k' or 'pi update –keep_local' option.
- Promote: This mode is a variation on 'Keep Local'. In this case, all files will be updated to AT LEAST the target release version for the file. This is activated by default, or can be activated by using 'pi update --promote' or 'pi update -p'.
The default update mode in the Helix IPLM CLI is 'promote'. The default update mode can be overridden by running updates using '-f' or '-k' as needed.
Note: None of the update modes are available for an IPV at a Revision Release (release using only a global revision number) - such IPVs are always updated exactly to the specified revision/changelist. A revision release will be used automatically for Subversion IPs.
In the above we can see pi update "Keep Local" mode in action in a workspace. The file versions in green make up release #1, the file versions in gold are release #2 and the file versions in red are local changes. When the workspace is updated to release #2 any submits that result in file versions beyond the file versions in the release #2 (those marked in red above) are preserved in the workspace.
Examples
If a user is working on 'fileA' in his workspace...
Example 1:
- Initial version: fileA at rev 10
- User checks in several changes to fileA, resulting in fileA at rev 20.
- User updates his workspace to the latest release, in which fileA remains at rev 10, but other files and resources have changed.
- User runs an update in the workspace. Helix IPLM will update all other files and resources to their target release version, but for fileA:
- In Promote mode, Helix IPLM will leave fileA at rev 20
- In Keep Local mode, Helix IPLM will leave fileA at rev 20
- In Force or Exact mode, Helix IPLM will sync fileA back to rev 10
Example 2:
- Initial version: fileA at rev 10
- User syncs fileA to rev 8 to recreate a bug
- User updates his workspace to the latest release, which contains fileA at rev 12.
- User runs an update in the workspace. Helix IPLM will update all other files and resources to their target release version, but for fileA:
- In Promote mode, Helix IPLM will sync fileA to rev 12
- In Keep Local mode, Helix IPLM will leave fileA at rev 8
- In Force or Exact mode, Helix IPLM will sync fileA to rev 12
Update modes in detail
For most users, the default 'promote' mode operates correctly, maintaining local modifications that are more recent (both files and resources) than the incoming update data. It is generally not necessary to do a deep dive on the precise mechanics of how update modes work, but it is helpful to have a working understanding. At the file level update modes apply to Perforce type IPs and to DM Handler IPs if the DM integration supports them. Resource update modes apply to all IP types.
Force (or exact) mode updates
The simplest update mode is 'force'. In a force mode update no consideration of the current or original versions of the objects to be updated is taken, the versions dictated by the target are updated into the workspace.
Keep local mode updates
In keep local mode the original version is compared to the current version, if the two are at the same version, there is no modified state, so the incoming target is used for the update. If they are different versions, there is a modified state, and the local version is retained.
Promote mode updates
Promote mode (the default update mode if another is not specified) behaves the same way as keep-local mode in that it checks whether the current version of the object is the same as the original version of the object, if it doesn't then the object is in a modified state. In this case Promote mode goes further and checks whether the current version is higher than the incoming target. Whichever object has the higher version will be selected.
Note: 'modified' (when the current version does not equal the original) refers to file versions that are checked in to the DM system. Locally modified files (modified but not checked into the DM system) will block updates until they are resolved.
Update summary matrix
Helix IPLM workspace update behavior is recorded in the table below. Updates for IPVs at aliases are handled with some special rules, and these are captured in the update matrix below.
In the update matrix below, assume there's an IP 'lib.ip'. Assume also that lib.ip@10.TRUNK is the latest release of this IP on trunk, and lib.ip@5.LINE1 is the latest version of this IP on Line LINE1.
Note: 'pi up' is a shorthand command for 'pi update'.
|
Rule #
|
Update Command(s)
|
Current Status in Workspace
|
Expands to
|
New Status in Workspace
|
Comment
|
|---|---|---|---|---|---|
|
1 |
pi update pi update lib.ip pi update lib.ip@.TRUNK |
lib.ip@HEAD.TRUNK |
pi update lib.ip@HEAD.TRUNK |
lib.ip@HEAD.TRUNK |
Update the workspace to lib.ip's HEAD (all the files at the top of the tree + resources as defined in the latest release of lib.ip) |
| 2 | pi update | lib.ip@<version>.TRUNK |
pi update lib.ip@<LATEST_RELEASE>.TRUNK |
lib.ip@10.TRUNK | Update the workspace to lib.ip's latest release on TRUNK. |
| 3 | pi update | lib.ip@ALIAS.TRUNK |
pi update lib.ip@ALIAS.TRUNK |
lib.ip@ALIAS.TRUNK | Update the workspace to the latest release on TRUNK that has the alias 'ALIAS'. This is a 'sticky' workspace - all updates without arguments will always update to the latest ALIAS. |
| 4 | pi update lib.ip | <Any version, alias or Line, except @HEAD> | pi update lib.ip@<LATEST_RELEASE>.TRUNK | lib.ip@10.TRUNK | Update the workspace to the latest release on TRUNK, even if the workspace has an IP on a different Line, or alias etc. This removes the 'sticky' alias from the workspace. |
| 5 | pi update lib.ip@.TRUNK | <Any version, alias or Line, except @HEAD> | pi update lib.ip@<LATEST_RELEASE>.TRUNK | lib.ip@10.TRUNK | Update the workspace to the latest release on TRUNK, even if the workspace has an IP on a different Line, or alias etc. This removes the 'sticky' alias from the workspace. |
| 6 | pi update lib.ip@.LINE1 | <Any version, alias or Line, except @HEAD> | pi update lib.ip@<LATEST_RELEASE>.LINE1 | lib.ip@5.LINE1 | Update the workspace to the latest release on LINE1, even if the workspace has an IP on a different Line, or alias etc. This removes the 'sticky' alias from the workspace. |
| 7 |
pi update lib.ip@8.TRUNK pi update lib.ip@4.LINE1 |
<Any version, alias or Line> |
No expansion, command is fully specified |
lib.ip@8.TRUNK lib.ip@4.LINE1 |
Any time a user provides a fully qualified name in the form of lib.ip@VERSION.LINE, the workspace will be updated to that exact IPV. |
| 8 | pi update lib.ip@ALIAS | <Any version, alias or Line> | pi update lib.ip@ALIAS.TRUNK | lib.ip@ALIAS.TRUNK | Switches the IP from any Line/version/alias to the latest ALIAS on TRUNK. The workspace is now sticky to this alias. |
| 9 | pi update lib.ip@ALIAS.LINE1 | <Any version, alias or Line> | No expansion, command is fully specified | lib.ip@ALIAS.TRUNK | Switches the IP from any Line/version/alias to the latest ALIAS on LINE1. The workspace is now sticky to this |
Detailed file update table
The table below shows a detailed description of what happen to individual files in various conditions when a workspace is updated in 'force', 'keep local', and 'promote' modes. The table data below matches the update mode flow diagrams show above, with the addition of the special handling of missing files (the flow diagram for which is shown below the table).
Notes
- "MISSING" denotes files that were deleted using the Data Management Systems such as Perforce. If the files were forcefully deleted using unix commands only, Helix IPLM will not be able to keep track of the missing files and the behavior will not reflect that of the table above.
- "MISSING" indicates the file is omitted (no entry) in the release file list or not synced to the workspace. The "MISSING" state is treated as equivalent to being present in the file list at file version #0 (Perforce) or synced to the workspace at file version #0.
- For the purposes of promote mode no distinction is made between a file revision for which the file is deleted and a file revision which is not deleted, higher file versions will be retained in both cases.
- None of the update modes are available for an IPV at a Revision Release (release using only a global revision number) - such IPVs are always updated exactly to the specified revision/changelist. A revision release will be used automatically for Subversion IPs.
|
|
File Version | Update Mode | ||||
|---|---|---|---|---|---|---|
|
|
Original Version | Current Version | Target Version | Exact (or force) | Keep Local | Promote |
| 1 | MISSING | 0 | MISSING | MISSING | 0 | 0 | 0 | 0 |
| 2 | MISSING | 0 | MISSING | 1 | 1 | 1 | 1 ( SPECIAL CURR=MISSING) |
| 4 | MISSING | 0 | MISSING | 2 | See L3 |
|
|
| 5 | MISSING | 0 | MISSING | 3 | See L3 |
|
|
| 6 | MISSING | 0 | 1 | MISSING | 0 | 0 | 1 | 1 |
| 7 | MISSING | 0 | 1 | 1 | 1 | 1 | 1 |
| 8 | MISSING | 0 | 1 | 2 | 2 | 1 | 2 |
| 9 | MISSING | 0 | 1 | 3 | See L8 |
|
|
| 10 | MISSING | 0 | 2 | MISSING | 0 | See L6 |
|
|
| 11 | MISSING | 0 | 2 | 1 | 1 | 2 | 2 |
| 12 | MISSING | 0 | 2 | 2 | See L7 |
|
|
| 13 | MISSING | 0 | 2 | 3 | See L8 |
|
|
| 14 | MISSING | 0 | 3 | MISSING | 0 | See L6 |
|
|
| 15 | MISSING | 0 | 3 | 2 | See L11 |
|
|
| 16 | MISSING | 0 | 3 | 3 | See L7 |
|
|
| 17 | 1 | MISSING | MISSING | 0 | 0 | 0 | 0 |
| 18 | 1 | MISSING | 1 | 1 | 0 | 1 ( SPECIAL CURR=MISSING) |
| 19 | 1 | MISSING | 2 | 2 | 0 | 2 ( SPECIAL CURR=MISSING) |
| 20 | 1 | MISSING | 3 | See L20 |
|
|
| 21 | 1 | 1 | MISSING | 0 | 0 | 0 | 0 |
| 22 | 1 | 1 | 1 | 1 | 1 | 1 |
| 23 | 1 | 1 | 2 | 2 | 2 | 2 |
| 24 | 1 | 1 | 3 | See L24 |
|
|
| 25 | 1 | 2 | MISSING | 0 | 0 | 2 | 2 |
| 26 | 1 | 2 | 1 | 1 | 2 | 2 |
| 27 | 1 | 2 | 2 | 2 | 2 | 2 |
| 28 | 1 | 2 | 3 | 3 | 2 | 3 |
| 29 | 1 | 3 | MISSING | 0 | See L26 |
|
|
| 30 | 1 | 3 | 1 | See L27 |
|
|
| 31 | 1 | 3 | 2 | 2 | 3 | 3 |
| 32 | 1 | 3 | 3 | See L28 |
|
|
| 33 | 2 | MISSING | MISSING | 0 | See L18 |
|
|
| 34 | 2 | MISSING | 1 | 1 | 0 | 1 ( SPECIAL CURR=MISSING) |
| 35 | 2 | MISSING | 2 | See L19 |
|
|
| 36 | 2 | MISSING | 3 | See L20 |
|
|
| 37 | 2 | 1 | MISSING | 0 | 0 | 1 | 1 |
| 38 | 2 | 1 | 1 | 1 | 1 | 1 |
| 39 | 2 | 1 | 2 | 2 | 1 | 2 |
| 40 | 2 | 1 | 3 | 3 | 1 | 3 |
| 41 | 2 | 2 | MISSING | 0 | See L22 |
|
|
| 42 | 2 | 2 | 1 | 1 | 1 | 1 |
| 43 | 2 | 2 | 2 | See L23 |
|
|
| 43 | 2 | 2 | 2 | See L23 |
|
|
| 44 | 2 | 2 | 3 | See L24 |
|
|
| 45 | 2 | 3 | MISSING | 0 | See L26 |
|
|
| 46 | 2 | 3 | 1 | 1 | 3 | 3 |
| 47 | 2 | 3 | 2 | See L27 |
|
|
| 48 | 2 | 3 | 3 | See L28 |
|
|
| 49 | 3 | MISSING | MISSING | 0 | See L18 |
|
|
| 50 | 3 | MISSING | 1 | See L35 |
|
|
| 51 | 3 | MISSING | 2 | See L35 |
|
|
| 52 | 3 | MISSING | 3 | See L19 |
|
|
| 53 | 3 | 1 | MISSING | 0 | See L38 |
|
|
| 54 | 3 | 1 | 1 | See L39 |
|
|
| 55 | 3 | 1 | 2 | 2 | 1 | 2 |
| 56 | 3 | 1 | 3 | See L40 |
|
|
| 57 | 3 | 2 | MISSING | 0 | See L38 |
|
|
| 58 | 3 | 2 | 1 | 1 | 2 | 2 |
| 59 | 3 | 2 | 2 | See L39 |
|
|
| 60 | 3 | 2 | 3 | See L40 |
|
|
| 61 | 3 | 3 | MISSING | 0 | See L22 |
|
|
| 62 | 3 | 3 | 1 | See L43 |
|
|
| 63 | 3 | 3 | 2 | See L43 |
|
|
| 64 | 3 | 3 | 3 | See L23 |
|
|
Special: Perforce File Level CURR=MISSING Decision Tree
File update modes for Perforce IPs require a special decision tree when the current version of the file is not in the workspace. The issue is that when a file is not present in the workspace there are a number of reasons it could be missing, and it is not possible in all cases to tell from perforce why it is missing. Some possibilities include it was p4 synced to #0, or there may be a deleted version at some higher level file version. The decision tree makes an assessment based on the information available.
Detailed resource update table
IP versions (IPVs) in a workspace are also subject to update modes during updates. In most cases, each IPV is treated the way an individual file is treated in update modes.
The information in the Detailed table matches the flow diagrams shown earlier on the page, with the addition of information on the handling of missing resources.
The table below shows a detailed description of what happen to IPVs in the workspace in various conditions when updated in the three modes.
Assuming the same Line for IPVs in the workspace
| IP Version (IPV) | Update Mode | |||||
|---|---|---|---|---|---|---|
| # |
IPV defined in the project |
Current IPV (prior to update) |
Target IPV (after update) |
Exact (Force) |
Keep Local | Promote |
|
1 |
MISSING | MISSING | MISSING | DELETED | DELETED | DELETED |
| 2 | MISSING | MISSING | 1 | 1 | 1 | 1 |
| 3 | NOT SUPPORTED | |||||
| 4 | 1 | MISSING | MISSING | DELETED | DELETED | DELETED |
| 5 | 1 | MISSING | 1 | 1 | 1 | 1 |
| 6 | 1 | MISSING | 2 | 2 | 2 | 2 |
| 7 | 1 | 1 | MISSING | DELETED | DELETED | DELETED |
| 8 | 1 | 1 | 1 | 1 | 1 | 1 |
| 9 | 1 | 1 | 2 | 2 | 2 | 2 |
| 10 | 1 | 2 | MISSING | DELETED | DELETED | DELETED |
| 11 | 1 | 2 | 1 | 1 | 2 | 2 |
| 12 | 1 | 2 | 2 | 2 | 2 | 2 |
| 13 | 1 | 2 | 3 | 3 | 2 | 3 |
| 14 | 1 | 3 | 2 | 2 | 3 | 3 |
| 15 | 2 | MISSING | 1 | 1 | 1 | 1 |
| 16 | 2 | 1 | MISSING | DELETED | DELETED | DELETED |
| 17 | 2 | 1 | 1 | 1 | 1 | 1 |
| 18 | 2 | 1 | 2 | 2 | 1 | 2 |
| 19 | 2 | 1 | 3 | 3 | 1 | 3 |
| 20 | 2 | 2 | 1 | 1 | 1 | 1 |
| 21 | 2 | 3 | 1 | 1 | 3 | 3 |
| 22 | 3 | 1 | 2 | 2 | 1 | 2 |
| 23 | 3 | 2 | 1 | 1 | 2 | 2 |
Original (Expected) Line != Current (Workspace) Line
When the IPV defined in the project (the Expected IPV) is on a different Line than the IPV in the workspace, for example when the IPV in the workspace has already been directly updated to a new Line in the workspace, promote mode will no longer update that resource to a different Line than its current workspace Line. Promote mode decides between the current workspace version and the incoming target version based on which is newer, but when the current workspace and the incoming IPV have different Lines, this comparison is no longer possible because the two IPVs are not sequentially related in a release sequence.
| IP Version (IPV) | Update Mode | |||||
|---|---|---|---|---|---|---|
| # |
IPV defined in the project |
Current IPV (prior to update) |
Target IPV (after update) |
Exact (Force) |
Keep Local | Promote |
| 1 | 1@L1 | 1@L2 | MISSING | DELETED | 1@L2 | 1@L2 |
| 2 | 1@L1 | 1@L2 | 1@L1 | 1@L1 | 1@L2 | 1@L2 |
| 3 | 1@L1 | 1@L2 | 2@L1 | 2@L1 | 1@L2 | 1@L2 |
| 4 | 1@L1 | 2@L2 | MISSING | DELETED | 2@L2 | 2@L2 |
| 5 | 1@L1 | 2@L2 | 1@L1 | 1@L1 | 2@L2 | 2@L2 |
| 6 | 1@L1 | 2@L2 | 2@L1 | 2@L1 | 2@L2 | 2@L2 |
| 7 | 1@L1 | 2@L2 | 3@L1 | 3@L1 | 2@L2 | 2@L2 |
| 8 | 1@L1 | 3@L2 | 2@L1 | 2@L1 | 3@L2 | 3@L2 |
| 9 | 2@L1 | 1@L2 | MISSING | DELETED | 1@L2 | 1@L2 |
| 10 | 2@L1 | 1@L2 | 1@L1 | 1@L1 | 1@L2 | 1@L2 |
| 11 | 2@L1 | 1@L2 | 2@L1 | 2@L1 | 1@L2 | 1@L2 |
| 12 | 2@L1 | 1@L2 | 3@L1 | 3@L1 | 1@L2 | 1@L2 |
| 13 | 2@L1 | 2@L2 | 1@L1 | 1@L1 | 2@L2 | 2@L2 |
| 14 | 2@L1 | 3@L2 | 1@L1 | 1@L1 | 3@L2 | 3@L2 |
| 15 | 3@L1 | 1@L2 | 2@L1 | 2@L1 | 1@L2 | 1@L2 |
| 16 | 3@L1 | 2@L2 | 1@L1 | 1@L1 | 2@L2 | 2@L2 |
Target (Incoming) Line != Current (Workspace) Line
When the IPV in the workspace has already been directly updated to a new version in the workspace that is different than the expected version of the IPV defined in the project (Expected version), promote mode will not update that resource to a different line than its current workspace line. Because promote mode decides between the current workspace version and the incoming target version based on which is newer, when the current workspace and the incoming IPV have different Lines, this comparison is no longer possible because the two IPVs are not sequentially related in a release sequence.
| IP Version (IPV) | Update Mode | |||||
|---|---|---|---|---|---|---|
| # |
IPV defined in the project |
Current IPV (prior to update) |
Target IPV (after update) |
Exact (Force) |
Keep Local | Promote |
| 1 | 1@L1 | 2@L1 | MISSING | DELETED | 2@L1 | 2@L1 |
| 2 | 1@L1 | 2@L1 | 1@L2 | 1@L2 | 2@L1 | 2@L1 |
| 3 | 1@L1 | 2@L1 | 2@L2 | 2@L2 | 2@L1 | 2@L1 |
| 4 | 1@L1 | 2@L1 | 3@L2 | 3@L2 | 2@L1 | 2@L1 |
| 5 | 1@L1 | 3@L1 | 2@L2 | 2@L2 | 3@L1 | 3@L1 |
| 6 | 2@L1 | 1@L1 | 1@L2 | 1@L2 | 1@L1 | 1@L1 |
| 7 | 2@L1 | 1@L1 | 2@L2 | 2@L2 | 1@L1 | 1@L1 |
| 8 | 2@L1 | 1@L1 | 3@L2 | 3@L2 | 1@L1 | 1@L1 |
| 9 | 2@L1 | 3@L1 | 1@L2 | 1@L2 | 3@L1 | 3@L1 |
| 10 | 3@L1 | 1@L1 | 2@L2 | 2@L2 | 1@L1 | 1@L1 |
| 11 | 3@L1 | 2@L1 | 1@L2 | 1@L2 | 2@L1 | 2@L1 |
