515 lines
11 KiB
Markdown
515 lines
11 KiB
Markdown
# PTC Integrity 10.7 CLI (`si`)
|
|
|
|
## Purpose
|
|
|
|
Use this skill when working with source code managed by **PTC Integrity 10.7**, using the `si` command-line client.
|
|
|
|
Target version:
|
|
|
|
```text
|
|
PTC Integrity 10.7.0.7930
|
|
```
|
|
|
|
PTC Integrity is not Git. Do not apply Git concepts or Git commands to an Integrity Sandbox unless the user explicitly states that Git is also being used.
|
|
|
|
The primary command-line tool is:
|
|
|
|
```bash
|
|
si
|
|
```
|
|
|
|
## Core Concepts
|
|
|
|
### Project
|
|
A Project is the server-side source configuration managed by Integrity.
|
|
|
|
### Sandbox
|
|
A Sandbox is a local working representation of an Integrity Project. It normally contains a `project.pj` file and working files corresponding to project members.
|
|
|
|
### Member
|
|
A Member is a version-controlled file belonging to an Integrity Project. A file existing on disk does not necessarily mean that it is a project member.
|
|
|
|
### Working File
|
|
The local filesystem copy of a Member inside a Sandbox. Do not infer Integrity state merely from filesystem permissions or timestamps.
|
|
|
|
### Member Revision
|
|
The revision currently selected by the Project. The working file may be based on a different revision.
|
|
|
|
### Lock / Checkout
|
|
`si co` / `si checkout` checks out a member. Depending on server configuration, checkout normally obtains a lock. Do not assume that making a file writable is equivalent to checking it out.
|
|
|
|
### Change Package
|
|
A Change Package (CP) records source changes associated with an Integrity item. Change package identifiers commonly look like `12345:1`. Never invent a Change Package ID.
|
|
|
|
## General Rules
|
|
|
|
1. Prefer `si` over manipulating Integrity metadata manually.
|
|
2. Never modify `project.pj`.
|
|
3. Never delete Integrity metadata manually.
|
|
4. Never assume Git semantics.
|
|
5. Determine Sandbox context before source-control operations.
|
|
6. Inspect state before changing state.
|
|
7. Operate on explicitly selected files whenever possible.
|
|
8. Avoid recursive operations unless required.
|
|
9. Never invent command options.
|
|
10. If uncertain about Integrity 10.7 syntax, use local CLI help.
|
|
|
|
Use:
|
|
|
|
```bash
|
|
si <command> --usage
|
|
```
|
|
|
|
or:
|
|
|
|
```bash
|
|
si <command> -?
|
|
```
|
|
|
|
The locally installed Integrity 10.7 client is authoritative.
|
|
|
|
## Detecting an Integrity Sandbox
|
|
|
|
Prefer:
|
|
|
|
```bash
|
|
si sandboxinfo
|
|
```
|
|
|
|
When necessary:
|
|
|
|
```bash
|
|
si sandboxinfo --cwd=/path/to/directory
|
|
```
|
|
|
|
Do not use `si sandboxinfo --xmlapi`; `--xmlapi` is not available in Integrity 10.7.
|
|
|
|
A `project.pj` is an indicator of an Integrity-managed tree, but do not rely exclusively on filesystem inspection.
|
|
|
|
## Read-Only Investigation
|
|
|
|
Prefer read-only commands while investigating:
|
|
|
|
```bash
|
|
si sandboxinfo
|
|
si viewsandbox
|
|
si projectinfo
|
|
si viewproject
|
|
si memberinfo
|
|
si history
|
|
si diff
|
|
```
|
|
|
|
Use local help when exact options are uncertain:
|
|
|
|
```bash
|
|
si viewsandbox --usage
|
|
si memberinfo --usage
|
|
si history --usage
|
|
si diff --usage
|
|
```
|
|
|
|
## Inspecting Members
|
|
|
|
Before changing a file, determine its Integrity state:
|
|
|
|
```bash
|
|
si memberinfo path/to/file
|
|
si viewsandbox path/to/file
|
|
```
|
|
|
|
Determine where relevant:
|
|
|
|
- whether the file is a Member
|
|
- working revision
|
|
- member revision
|
|
- lock state
|
|
- whether the working file changed
|
|
- whether a newer member revision exists
|
|
- whether the member belongs to a variant/development path
|
|
|
|
Do not infer these from the filesystem alone.
|
|
|
|
## Viewing Differences
|
|
|
|
Before overwriting, reverting, or checking in a modified file:
|
|
|
|
```bash
|
|
si diff path/to/file
|
|
```
|
|
|
|
If additional options are required:
|
|
|
|
```bash
|
|
si diff --usage
|
|
```
|
|
|
|
Do not replace this with `git diff` unless the directory is explicitly also managed by Git.
|
|
|
|
## History
|
|
|
|
Use:
|
|
|
|
```bash
|
|
si history path/to/file
|
|
```
|
|
|
|
For advanced queries:
|
|
|
|
```bash
|
|
si history --usage
|
|
```
|
|
|
|
## Checkout
|
|
|
|
The common command is:
|
|
|
|
```bash
|
|
si co path/to/file
|
|
```
|
|
|
|
Before checkout, determine:
|
|
|
|
- whether the file is already checked out or locked
|
|
- whether the working file has local modifications
|
|
- whether the member revision is current
|
|
- whether a Change Package is required
|
|
|
|
Never invent a Change Package ID.
|
|
|
|
If unsure:
|
|
|
|
```bash
|
|
si co --usage
|
|
```
|
|
|
|
## Editing Files
|
|
|
|
When a file needs modification:
|
|
|
|
1. Determine Sandbox context.
|
|
2. Determine member state.
|
|
3. Check whether checkout/locking is required.
|
|
4. Check out the member if appropriate.
|
|
5. Modify only the requested files.
|
|
6. Review the resulting diff.
|
|
|
|
Do not automatically resynchronize a modified file merely because it is out of sync.
|
|
|
|
## Check In
|
|
|
|
The common command is:
|
|
|
|
```bash
|
|
si ci path/to/file
|
|
```
|
|
|
|
Before checking in:
|
|
|
|
1. Inspect the member state.
|
|
2. Inspect the diff.
|
|
3. Determine the relevant Change Package.
|
|
4. Ensure only intended files are included.
|
|
5. Determine the check-in description.
|
|
6. Verify that unrelated modifications are not included.
|
|
|
|
Do not automatically check in changes merely because implementation work is complete. Unless the user explicitly requested a check-in, stop after making and reviewing the working-file changes.
|
|
|
|
For exact options:
|
|
|
|
```bash
|
|
si ci --usage
|
|
```
|
|
|
|
## Change Packages
|
|
|
|
A CP identifier typically has the form:
|
|
|
|
```text
|
|
ITEM:CP
|
|
```
|
|
|
|
For example:
|
|
|
|
```text
|
|
4711:1
|
|
```
|
|
|
|
An option may have a form such as:
|
|
|
|
```text
|
|
--changePackageId=4711:1
|
|
```
|
|
|
|
but always verify command-specific syntax using:
|
|
|
|
```bash
|
|
si <command> --usage
|
|
```
|
|
|
|
Never:
|
|
|
|
- invent a CP
|
|
- select an unrelated CP merely because it is open
|
|
- close a CP without explicit instruction
|
|
- create a CP without explicit instruction
|
|
|
|
## Resynchronize
|
|
|
|
`si resync` updates Sandbox working files from member revisions:
|
|
|
|
```bash
|
|
si resync path/to/file
|
|
```
|
|
|
|
This command is potentially destructive and may overwrite local working-file changes.
|
|
|
|
Before resync:
|
|
|
|
1. Inspect Sandbox/member state.
|
|
2. Determine whether working files contain modifications.
|
|
3. Inspect important differences.
|
|
4. Determine exactly which members will be affected.
|
|
5. Avoid recursive resync unless necessary.
|
|
|
|
If the operation could destroy user changes, obtain explicit user approval.
|
|
|
|
Before advanced use:
|
|
|
|
```bash
|
|
si resync --usage
|
|
```
|
|
|
|
## Resync by Change Package
|
|
|
|
Features may include:
|
|
|
|
```bash
|
|
si resync --byCP ...
|
|
si resynccp ...
|
|
```
|
|
|
|
Do not treat them as interchangeable.
|
|
|
|
Before use:
|
|
|
|
```bash
|
|
si resync --usage
|
|
si resynccp --usage
|
|
```
|
|
|
|
## Adding Files
|
|
|
|
New files created inside a Sandbox are not automatically Integrity members.
|
|
|
|
Before adding:
|
|
|
|
1. Confirm the file is intended for source control.
|
|
2. Determine the target Project/Sandbox.
|
|
3. Determine whether a Change Package is required.
|
|
4. Check exact Integrity 10.7 syntax.
|
|
|
|
Use:
|
|
|
|
```bash
|
|
si add --usage
|
|
```
|
|
|
|
Do not add build output, temporary files, editor backup files, or generated files unless required.
|
|
|
|
## Dropping Members
|
|
|
|
Dropping a member removes it from the Integrity Project configuration and is destructive.
|
|
|
|
Before dropping:
|
|
|
|
1. Verify the target member.
|
|
2. Inspect its state.
|
|
3. Determine whether local modifications exist.
|
|
4. Determine the required Change Package.
|
|
5. Obtain explicit user approval if removal was not already explicitly requested.
|
|
|
|
Check syntax:
|
|
|
|
```bash
|
|
si drop --usage
|
|
```
|
|
|
|
## Revert / Discarding Changes
|
|
|
|
Discarding local changes can cause irreversible data loss. Do not assume Git semantics.
|
|
|
|
Before using a revert/discard operation:
|
|
|
|
```bash
|
|
si revert --usage
|
|
```
|
|
|
|
Inspect current member state and diff first. If local modifications would be destroyed, obtain explicit user approval unless the user already explicitly requested that those modifications be discarded.
|
|
|
|
## Recursive Operations
|
|
|
|
Do not automatically use recursive options such as `-R`.
|
|
|
|
Before a recursive operation:
|
|
|
|
1. Determine the Sandbox root.
|
|
2. Determine the expected affected scope.
|
|
3. Prefer filters or explicit member lists where practical.
|
|
4. Inspect the command with `--usage`.
|
|
5. Avoid destructive recursive operations unless explicitly requested.
|
|
|
|
## Selection Files
|
|
|
|
Integrity may support selection files for commands accepting multiple members, using forms such as:
|
|
|
|
```text
|
|
-F file
|
|
--selectionFile=file
|
|
```
|
|
|
|
Verify support first:
|
|
|
|
```bash
|
|
si <command> --usage
|
|
```
|
|
|
|
## `--cwd`
|
|
|
|
Integrity commands can operate relative to another working directory. Example:
|
|
|
|
```bash
|
|
si <command> --cwd=/path/to/sandbox ...
|
|
```
|
|
|
|
Prefer `--cwd` over arbitrary shell `cd` sequences when it makes command context clearer.
|
|
|
|
## Error Handling
|
|
|
|
When an `si` command fails:
|
|
|
|
1. Preserve the complete error output.
|
|
2. Do not immediately retry with destructive flags.
|
|
3. Determine whether the failure concerns authentication, Sandbox context, member state, locks, Change Packages, permissions, project ambiguity, development paths, server connectivity, or unsupported options.
|
|
4. Query local command help if syntax is involved.
|
|
|
|
Never solve an Integrity error by deleting `project.pj` or other Integrity metadata.
|
|
|
|
## Version Compatibility
|
|
|
|
This environment uses:
|
|
|
|
```text
|
|
PTC Integrity 10.7.0.7930
|
|
```
|
|
|
|
Do not assume documentation for Integrity 11, Integrity 12, or Windchill RV&S exactly matches this installation.
|
|
|
|
Newer documentation may help explain concepts, but command-line options must be verified against the installed client.
|
|
|
|
When there is a discrepancy, the local Integrity 10.7 CLI is authoritative:
|
|
|
|
```bash
|
|
si <command> --usage
|
|
```
|
|
|
|
## Safe Investigation Workflow
|
|
|
|
For an unfamiliar working tree:
|
|
|
|
```bash
|
|
pwd
|
|
find .. -name project.pj -print
|
|
si sandboxinfo
|
|
si viewsandbox --usage
|
|
```
|
|
|
|
For a file that needs modification:
|
|
|
|
```bash
|
|
si memberinfo path/to/file
|
|
si diff path/to/file
|
|
```
|
|
|
|
If checkout is required:
|
|
|
|
```bash
|
|
si co --usage
|
|
si co path/to/file
|
|
```
|
|
|
|
After modifying:
|
|
|
|
```bash
|
|
si diff path/to/file
|
|
```
|
|
|
|
Do not automatically check in.
|
|
|
|
## Agent Safety Policy
|
|
|
|
Normally safe for autonomous investigation:
|
|
|
|
```text
|
|
sandboxinfo
|
|
projectinfo
|
|
viewsandbox
|
|
viewproject
|
|
memberinfo
|
|
history
|
|
diff
|
|
help / --usage
|
|
```
|
|
|
|
Commands altering local or server-side Integrity state require additional care:
|
|
|
|
```text
|
|
co / checkout
|
|
ci / checkin
|
|
add
|
|
drop
|
|
resync
|
|
resynccp
|
|
applycp
|
|
revert
|
|
lock
|
|
unlock
|
|
createsandbox
|
|
dropsandbox
|
|
```
|
|
|
|
The agent may perform a checkout when clearly necessary for an explicitly requested code modification and doing so does not discard existing work.
|
|
|
|
The agent must not autonomously:
|
|
|
|
- destroy local modifications
|
|
- drop members
|
|
- perform destructive resyncs
|
|
- close Change Packages
|
|
- create arbitrary Change Packages
|
|
- check in unrelated changes
|
|
- recursively modify a large project without understanding scope
|
|
- suppress safety confirmations merely to make a command succeed
|
|
|
|
## Important Principle
|
|
|
|
Integrity source-control state is more important than filesystem appearance.
|
|
|
|
Never reason:
|
|
|
|
> The file exists and is writable, therefore it is safe to edit.
|
|
|
|
Instead reason:
|
|
|
|
> This is an Integrity Sandbox. Determine the member and working-file state before deciding which operation is appropriate.
|
|
|
|
When in doubt:
|
|
|
|
```bash
|
|
si sandboxinfo
|
|
si memberinfo <member>
|
|
si <command> --usage
|
|
```
|
|
|
|
before modifying source-control state.
|