options

CLI Reference > CLI Usage Overview > options

options

applicable to CLI commands

Description

Some CLI commands (si, im, aa, integrity) share general options, while all take certain universal options. This reference page is provided as a guide to these common options.

This reference page contains the following information:

• Specifying Members, Sandboxes and Projects for Configuration Management Commands

• Specifying Sandboxes Explicitly or Implicitly for Configuration Management Commands

• Specifying Configuration Management Projects

• Specifying Rules

• General Options

• Universal Options

Specifying Members, Sandboxes and Projects for Configuration Management Commands

There are three types of configuration management commands, and therefore the way you specify the member varies:

1. Some commands can only be executed on members in the context of a Sandbox, because they manipulate the member's working file. These are noted as requiring a sandbox member..., such as si ci, si co, and si merge. These take a Sandbox member, and you may not perform the operation against a project member. If you try to specify a project for these commands, you will see an error message.

2. Other commands do not manipulate a member's working file, and therefore can be performed directly in the context of a project. If you specify a Sandbox, it is simply used as a pointer to find the project itself. The fact that you specify the Sandbox is only incidental. These are noted as requiring a project member..., and most of the commands that say member... fall into this category; for example, si updaterevision, si updatearchive, and si addlabel.

3. There are also some commands that perform differently depending on whether they are given a sandbox or a project. Examples for this would be si diff and si edit.

Specifying Sandboxes Explicitly or Implicitly for Configuration Management Commands

You can explicitly specify either -P or -S options for most commands. For -P you must specify a project or subproject, the -P option does not accept the filename of a Sandbox. For -S you must specify a Sandbox or sub Sandbox, -S does not accept the filename of a project.

PTC RV&S also allows for implicit Sandbox selection. This means that you can use commands without explicitly specifying a -S sandbox option, and PTC RV&S determines the Sandbox to operate on based on the directory you are working in.

For example, suppose you are working in the directory C:/test/sbx/sub1/sub2, and suppose you have a Sandbox only in the /sbx directory. Using the -S option to explicitly specify the Sandbox, you might enter the following to check in a file:

si ci -S c:/test/sbx/project.pj header.c

Using implicit Sandbox location to check in a file, you might enter:

si ci header.c

If the Sandbox is not specified explicitly through -S, PTC RV&S tries to locate one by starting in the current working directory and seeing if there is a Sandbox registered in that directory. If there isn't, it searches up the directory tree until it either finds one, or until it reaches the root of the drive. In the example provided, PTC RV&S first determines there is no Sandbox in /sub2, then /sub1, then finds the Sandbox in /sbx and uses that Sandbox.

Now suppose you have Sandboxes in each of /sbx, /sub1, and /sub2. This implicit Sandbox selection allows you to work with multiple Sandboxes in one command line entry, and without having to explicitly specify lengthy locations for each one. If you're working in the C:/test/sbx directory and decide to check in files to each Sandbox, for example, you might enter:

si ci header.c sub1/comp.c sub1/sub2/img.c

This checks in the file header.c to the Sandbox at C:/test/sbx, checks in the file comp.c to the Sandbox at C:/test/sbx/sub1, and checks in the file img.c to the Sandbox at C:/test/sbx/sub1/sub2.

A requirement for implicit Sandbox location to operate correctly is that there can be no more than one Sandbox (or sub Sandbox) in a single directory. If you create two or more Sandboxes in the same directory, the implicit Sandbox location algorithm cannot unambiguously determine which Sandbox to use in that directory, and it prompts you to clarify by specifying the name of the Sandbox that you want to use in that case. In general, you shouldn't create multiple Sandboxes in the same directory.

Certain si commands do not operate on Build Sandboxes, which are created as read-only for the purpose of building a programming artifact. Using inappropriate commands with a Build Sandbox causes error messages to appear.

Specifying Configuration Management Projects

This section provides information on the two available syntaxes for specifying projects, followed by examples of their usage. The following two syntaxes are available:

• Source Configuration Path

A keyword-based string that provides the ability to specify subprojects within the context of a project tree (see examples that follow).

• Flat Path

The legacy syntax that may not be supported in future releases. It takes the form of a simple pathname string, possibly accompanied by a development path name or a project checkpoint.

WELL FORMED PROJECTS: PTC recommends using well formed projects wherever possible. A well formed project is one where every directory contains a subproject (if not possible, then all members should belong to the nearest enclosing subproject), and that subproject is named project.pj.

BENEFIT: Well formed projects use more compact paths. Using a well formed project eliminates the need to use hash (#) values for specifying projects (refer to Path ambiguity example).

When specifying Sandbox subproject scope, to avoid potential ambiguities, PTC recommends that the subproject name is specified using a Sandbox-relative source configuration path to specify subprojects within the context of a project tree. Use explicit non-compact keyword string syntax to match the path definition defined in the GUI instead of using compact hash syntax.

For example, the following source configuration path:

#s=sub/project.pj#s=sub2/project.pj#s=sub3/project.pj

is the same as the following compact source configuration path:

#sub/sub2/sub3 or #sub#sub2#sub3

however, the non-compact keyword string syntax is recommended to account for cases where project paths are not necessarily well-formed. For more details on specifying Sandbox subproject scope, see the si createsandbox command man page.

SCENARIOS WHERE SOURCE CONFIGURATION PATH IS SUPERIOR TO FLAT PATH SPECIFICATION

The following scenarios are documented in this section, and illustrate how using the source configuration path syntax is the superior choice compared to flat path specification:

• Subproject not on main development path

• Path ambiguity

• Ambiguous co-located subprojects

The following keywords are used in the examples:

• The # keyword specifies the well-formed project or subproject name. Well-formed project and subproject names end with project.pj.

• The #a keyword specifies the date of the project configuration.

• The #d keyword specifies the development path name.

• The #s keyword specifies the subproject in a poorly-formed project tree. A poorly-formed project tree has co-located subprojects or subprojects located more than one directory level deep. Using this keyword, you can only specify one subproject for each occurrence of the keyword.

For a description of all keywords, see the -P option under General Options.

SUBPROJECT NOT ON MAIN DEVELOPMENT PATH

The flat path cannot handle the case where the object (in this case a sub project on a variant) PTC RV&S is locating does not exist in the main project tree (on the main devpath).

In the following diagram, user needs to specify project sub2 on devpath Dev.

• Tree 1

/aurora_project/project.pj

--- sub/project.pj

• Tree 2

/aurora_project/project.pj (Development Path Dev)

---sub/project.pj

---sub2/project.pj

Flat Path: -P /aurora_project/sub2/project.pj --devpath Dev

This syntax does not work because PTC RV&S attempts to find /aurora_project/sub2/project.pj on the main devpath first, and then jumps from there into the development path, but in this case that subproject does not exist in the main devpath.

Source Configuration Path: -P"#/aurora_project#d=Dev#sub2"

This syntax works because it instructs PTC RV&S to start with /aurora_project (which does exist in main devpath), then jump to devpath Dev, then move into sub2.

Summary: In this scenario, there is no way to specify sub2 using the flat path syntax because it is not on the main development path. You must use the source configuration path syntax to specify sub2.

PATH AMBIGUITY

In some cases, the flat path lacks the ability to specify the desired project with no ambiguity.

In the following diagram, the user needs to specify subproject beta/project.pj (but only from the location in Tree 1 below).

• Tree 1

/aurora_project/project.pj

---codebase/project.pj (Development Path Dev1)

---beta/project.pj (Development Path Dev2)

• Tree 2

/aurora_project/codebase/project.pj [Reg as top-level proj]

---beta/project.pj

Flat Path: -P/aurora_project/codebase/beta/project.pj

This syntax is ambiguous, because it could be specifying the project on either node. PTC RV&S picks the first project it finds in the registry, which may not be the one desired. The contents of each project are not the same because one is on devpath Dev2, while the other is on the main devpath.

Source Configuration Path:

-P "#/aurora_project#codebase#beta"

-P "#/aurora_project/codebase#beta"

This syntax method is unambiguous. It is completely clear which beta subproject location is specified.

The short form is used because the projects are assumed to be well formed. The long form example would be: -P #p=/aurora_project/project.pj#s=codebase/project.pj#s=beta/project.pj

-P #p=/aurora_project/codebase/project.pj#s=beta/project.pj

Summary: In this scenario, the flat path method is ambiguous while the source configuration path is not. The source configuration path can never be ambiguous.

AMBIGUOUS CO-LOCATED SUBPROJECTS

The flat path syntax cannot specify co-located subprojects (subprojects located in same directory).

In the following diagram, two subprojects are located in the same directory.

• Tree 1

/aurora_project/source_code/root.pj

/colocatedsub.pj

Project colocatedsub.pj is in the same directory as root.pj but is the subproject of root.pj in hierarchy.

• Tree 2

/aurora_project/source_code/base.pj

/colocatedsub.pj

Project colocatedsub.pj is in the same directory as base.pj but is the subproject of base.pj in the hierarchy.

In this scenario, root.pj, base.pj, and colocated.pj are all in the same directory.

File Path:-P /aurora_project/source_code/colocatedsub.pj

This syntax method is ambiguous because it is unclear which project the co-located project belongs to. There might be different policies that affect how colocatedsub.pj is administered or used.

Source Configuration Path -P #/aurora_project/source_code/root.pj#s=colocatedsub.pj

This syntax method clearly specifies a registered project and a subproject where there are co-located subprojects

Summary: In this scenario, the flat path syntax method is unable to specify the co-located subproject. Only the source configuration path syntax can specify the desired path.

Rules for Jumps

When jumping to a specific configuration in a project path, the following rules apply:

• You cannot jump anywhere from a build project

• You can jump from a normal project to a variant only if it is the root of the variant (the project through which the development path was created)

• You cannot jump to a variant if it differs from the closest variant higher in the project hierarchy (if there is a higher variant). When no subprojects are configured as variants in the hierarchy, the closest variant is the variant of the top-level project. When at least one subproject in the hierarchy is configured as a variant, the closest variant is the variant of the lowest configured subproject. This does not include the variant of the subproject on which the jump is specified, if it is currently configured as a variant.

The last two rules are verified based on the type of the parent project. You can always jump to the current configuration of a subproject, even if it violates the rules listed above.

The following provides examples of how jump rules are applied when jumping to a variant. If you had the following project setup:

/projects/aurora_project/source_code/savings_tool/project.pj

where source_code is a subproject currently configured as beta_variant and savings_tool is a shared subproject currently configured as normal.

The following jump would be allowed:

-P #/projects/aurora_project#source_code/savings_tool#d=beta_variant

The following jump would not be allowed:

-P #/projects/aurora_project#source_code/savings_tool#d=prod_variant

You can specify a jump to beta_variant from the subproject savings_tool because it is the same as the variant for source_code, and because as a shared subproject it is accepted as the local variant root (the project through which the development path was created). You cannot jump to prod_variant because it is different than the variant of source_code.

The following jumps would also be allowed:

-P #/projects/aurora_project#d=SP4#source_code#d=SP4

-P #/projects/aurora_project#d=SP4#source_code#d=beta_variant

The following jump would not be allowed:

-P #/projects/aurora_project#d=SP4#source_code#d=prod_variant

You can specify a jump to SP4 from the subproject source_code because it is the same as the variant for aurora_project. You can specify a jump to beta_variant because source_code is currently configured as beta_variant. You cannot jump to prod_variant because it is different than the variant of aurora_project.

If you are using a case-insensitive database repository, you can use case-insensitive keyword-based strings.

If the path contains a hash character (#), use a second hash character to escape it. For example:

-P #/projects/C##/aurora_project#d=SP4#source_code#d=SP4

Specifying Rules

Some CLI commands share the same rule syntax. The rule is of the following form:

A <rule> rule is defined as an <expression>

An <expression> is defined as one of the following:

( <expression> and <expression> and <expression> )

( <expr> or <expr> or <expr> )

( <user op> )

( <field> <operator> <value> )

where for users and groups:

<user op>rule is defined as a user is not a member of "<group>"

<user op>rule is defined as a user is a member of "<group>"

<value>rule is defined as a <field> | "<text>" | "<number>"

<field> rule is defined as a field[<fieldname>]

<fieldname> rule is defined as a ID | Summary | Priority | ...

<group> rule is defined as a (everyone | im-dev | ...)

<operator> rule is defined as a ( = | > | >= | <= | < | <> )

<number> rule is defined as a ( .. | -1 | 0 | 1 | ..)

For example:

(((field[Summary] = "Hello") or (user is a member of "everyone") )

and

((field[ID] = "1") or (field[ID] = "2") or (field[ID] = "5"))

and

(field[Summary] <> field[Description]))

For trigger rules, same syntax applies but:

<value> is defined as <field> | "<text>" | "<number>"

<field> is defined as field'[<fieldname>]

<field> is defined as field[<fieldname>]

<fieldname> is defined as ID | Summary | Priority | ...

<operator> is defined as ( = | > | >= | <= | < | <> )

<number> is defined as ( .. | -1 | 0 | 1 | ..)

For example:

(((field[Summary] = "Hello") or (field'[Summary] = field[Summary]))

and

((field[ID] = "1") or (field[ID] = "2") or (field[ID] = "5"))

and

(field[Priority] <> field'[Priority]))

To prevent the field from being displayed, specify the rule value to be "(false)". This option is useful if you want to hide read-only custom fields (i.e. phase, range, computed) in Issue Detail and Issues views, but still be able to query on them and use them in column sets. Enabling this option replaces any existing rules with "(false)".

To specify a date and time for a date field, use the MM/dd/yyyy h:mm:ss [AM|PM] format. You can specify a time only if the date field is configured to display the time. To specify the current date for a date or date/time field, type today. To specify an empty value for the date field, type none.

For rules specified in commands that use the --notificationRule, --notificationRuleFile, --rule, and --ruleFile options, you can also compare the value of a field with another field or constant, by specifying an apostrophe ('). For example, Created Date' compares the value of the field with another field (Created Date), but Created Date'="01/26/2009 1:45:33 PM" compares the value of a field with a constant (an actual date).

When specifying a user, you can choose yourself by specifying "me". "me" is a symbolic user which refers to the currently logged in user. For example, you could create a relevance rule that specifies the Requirements field is visible only if the currently logged in user is one of the users defined in the multi-valued Stakeholders field.

Specifying Rules for Live and Versioned Document Model Items

If document versioning is enabled, you can specify conditions for live and versioned document model items. For example, you can create an event trigger rule to run on versioned items only or an e-mail notification rule that sends an e-mail when a user edits a specific live item.

With items, you can:

• define a rule to match live items only. For example, "(item is live)" matches live items only.

• define a rule to match versioned items only. For example, "(item is versioned)" matches versioned items only.

As a best practice, PTC recommends including the (item is live) condition in all rules for live items. This improves the accuracy of rules.

With item IDs, you can:

• define a rule using a live item ID to match a single live item. For example, "((field[ID]=123) and (item is live))" matches 123.

• define a rule using a versioned item ID to match a single versioned item. For example, "(field[ID]=123-1.0)" matches 123-1.0.

• You cannot define a rule using a live item ID to match the live item and all versions of the item.

• You cannot define a rule using live or versioned item IDs to match a range of live or versioned items, for example,

"(field[ID]>123-1.0 and 128-1.0)".

General Options

Some CLI commands share the following general options.

• --devpath=path

identifies the development path of a variant project. This is a label that was associated with a branch of the project by si createdevpath. Paths that include spaces must be enclosed by quotes. The following characters may not be used in a development path: \n, \r, \t, :, [', '], #.

This option is always used in conjunction with the -P option and a flat string project path. It cannot be used if you specify a project using a keyword string for the -P option. It is also mutually exclusive with the --projectRevision and --sandbox options.

• --changePackageId=ID

identifies a change package that is notified of this action, for example, 1452:1. Note the following about using this option:

◦ This option can only be specified if change packages are enabled.

◦ You must specify this option if you have requested to obtain a lock and your administrator has set up locks to be tracked in change packages.

◦ You must specify this option if your administrator has made change packages mandatory.

◦ If your administrator has given you permission, you can bypass mandatory change packages by specifying --changePackageId=:bypass.

◦ If change packages are enabled but it is not mandatory to specify a change package, or if no change package is applicable, you must specify --changePackageId=:none.

• --[no]failOnAmbiguousProject

if you specify the project using a flat string for the -P option, this option displays an error message when multiple projects correspond to the specified path.

• --filter=filteroptions

allows you to select members for all commands that take a list of members, using filteroptions, which can be one or more of the following:

◦ archiveshared

selects members that share another member's archive.

◦ attribute:name[=value]

selects members based on an attribute name and, optionally, value.

selects changed members based on: changes to working files, those that are out of sync with the project, those where a newer revision exists in the project, or based on all changes.

◦ rule [:memberrevdiffers|:defined|:invalid]

selects members based on a revision rule filter. :memberrevdiffers selects all members for which the rule does not match the member revision. :defined selects all members with a revision rule. :invalid selects all members for which the rule does not expand to any existing revision.

◦ file:expression

selects members with a specific file name. This allows you to specify wild cards for file naming, such as the asterisk (*) to match any number of characters, and the question mark (?) to match a single character. For example, *.java or *RB.properties would be valid expressions.

◦ caseinsensitivefile:expression

selects members with a specific case-insensitive file name. This allows you to specify wild cards for file naming, such as the asterisk (*) to match any number of characters, and the question mark (?) to match a single character. For example, *.java or *rb.properties would be valid expressions.

◦ frozen

selects frozen members.

◦ label[:name]

selects any member whose member revision has the specified label.

◦ anylabel[:name]

selects any member that contains a revision that has the specified label.

◦ locked[:name]

selects all locked members or those locked by a particular user.

◦ locktype[:exclusive|:nonexclusive|:any]

selects members that are locked with the specified lock type. If no lock type or any is specified, all locked members are displayed.

◦ outofscope

selects members that are outside of the scope definition of the Sandbox (if the Sandbox is a Scoped Sandbox). Specifying a Sandbox scope allows you to define what project members are included in a Sandbox, transferring specific members from the PTC RV&S Server to the Sandbox directory when the Sandbox is created and controlling what members display in the Sandbox view.

◦ state[:name]

selects members based on state.

◦ format[:text|:binary]

selects members based on storage format.

◦ workingbranch

selects members where the working file is on a branch from a given development path that is not the trunk development path.

This filter applies only to sandboxes.

selects deferred members based on: add, addfromarchive, checkin, drop, import, move, rename, updaterevision, or all operations.

◦ memberonbranch

shows only members that are off the main development trunk.

◦ unresolvedmerges

selects members affected by unresolved merges.

selects pending members based on add, addfromarchive, drop, import, movememberfrom, movememberto, renamefrom, renameto, update, updaterevision, or all operations.

◦ workinprogress

combines the deferred (all), locked (all), and changed (all) filters to select members that are considered work in progress.

◦ sparsecontents

shows only existing working files and deferred operations in a sparse sandbox.

◦ changedsincelastcheckpoint

selects members that have changed since the project was last checkpointed. This filter selects members that have changed due to operations that caused a change in member revision. These operations include Add Member, Rename Member, Move Member, Update Member Revision, and so on.

◦ potentiallyModified

displays members in the sandbox whose working files are potentially modified. For more information, see Checksum Collision and Potentially Modified Files.

Using commas between the filteroptions serves to build logical "OR" statements between them, allowing you to create powerful filters. You may also specify multiple --filter=filteroptions on the command line, which effectively creates logical "AND" statements between them.

For example, you can resynchronize all modified JAVA files through:

si resync --filter=changed --filter=file:*.java

or you can resynchronize all files with label a or b through:

si resync --filter=label:a,label:b

You can also negate a filter using the ! character.

For example, you can check out all JAVA files that are not labelled Beta by typing:

si co --filter=file:*.java --filter=!label:Beta

• --hostname=server

identifies the name of the host server where the PTC RV&S Server is located.

• --issueid=id

for configuration management commands, specifies the issue ID that corresponds to the change package that records the changes(s). This option can only be specified if the integration between configuration management, and workflow and document management is enabled. See your administrator for details on using the integration.

The terms item and issue refer to the same object and are indistinguishable. Issue is a term embedded in legacy command and option names; therefore, item and issue are used interchangeably in the CLI documentation.

If you have an issue assigned to you that contains only one open change package, you can specify the issue ID instead of the change package ID.

• --password=password

identifies the password to use for connecting to the PTC RV&S Server.

• --port=number

identifies the port on the host server where the PTC RV&S Server is located.

• -P project

• --project=project

specifies the path and name of a project. You can specify the project using a flat string or a keyword string. It is recommended that you use a keyword string, especially when you are writing scripts, since flat strings can be ambiguous as to which project is being specified. Use the following keywords to identify the project.

◦ #value

#wp=value

#wproject=value

specifies the well-formed project or subproject name. Well-formed project or subproject names end with project.pj. For example, #/aurora_project/source_code. Do not specify a trailing project.pj.

◦ #p=value

#project=value

specifies the full name of the project, when it does not end with project.pj. For example, #p=/aurora_project/source_code/root.pj

◦ #value

#ws=value

#wsubs=value

specifies the subproject in a well-formed project tree. A well-formed project tree has one subproject per directory. Using this keyword, you can specify several levels of subprojects at the same time. For example, #/aurora_project/source_code/#applications/savings_tool. Do not specify a trailing project.pj.

◦ #s=value

#sub=value

specifies the subproject in a poorly-formed project tree. A poorly-formed project tree has co-located subprojects or subprojects located more than one directory level deep. Using this keyword, you can only specify one subproject for each occurrence of the keyword. For example:

#/aurora_project/source_code/#s=applications/savings_tool/project.pj#s=colocated.pj.

The #s and # keywords do not interpret sub subprojects in the same way. For example, #/aurora_project#source_code/applications is not the same as #/aurora_project#s=source_code/applications/project.pj but is the same as #/aurora_project#s=source_code/project.pj#s=applications/project.pj

◦ #d=value

#devpath=value

specifies the development path name, for example, #/aurora_project/source_code/#applications/savings_tool#d=beta_variant. You can only jump to a variant for a subproject if the subproject is the root of the variant (the project through which the development path was created). You cannot jump to a variant if it differs from the closest variant higher in the project hierarchy (if there is a higher variant).

This keyword is not supported on Sandbox commands that specify subproject scope using a Sandbox-relative source configuration path.

◦ #a=value

specifies the project configuration as of a date (timestamp), for example, #p=aurora/project.pj#a="April 28, 2014 3:33:45 AM GMT-05:00". PTC RV&S recognizes all current time zones whatever your locale (country), for example, CEST, CET, EDT, PST, or GMT+/-hours:minutes. The following information illustrates North American timestamps recognized by PTC RV&S:

US GMT -5 (where E is the day of the week, M is the month, d is the numerical day of the month, y is the year, h is the time in hours, m is the time in minutes, s is the time in seconds, a is the AM or PM indicator, z is the time zone difference from Greenwich Mean Time.

EEEE, MMMM d, yyyy h:mm:ss a z | Monday, April 28, 2014 3:33:45 AM GMT-05:00

EEEE, MMMM d, yyyy h:mm:ss a | Monday, April 28, 2014 3:33:45 AM

EEEE, MMMM d, yyyy h:mm a | Monday, April 28, 2014 3:33 AM

MMMM d, yyyy h:mm:ss a z | April 28, 2014 3:33:45 AM GMT-05:00

MMMM d, yyyy h:mm:ss a | April 28, 2014 3:33:45 AM

MMMM d, yyyy h:mm a | April 28, 2014 3:33 AM

MMM d, yyyy h:mm:ss a z | Apr 28, 2014 3:33:45 AM GMT-05:00

MMM d, yyyy h:mm:ss a | Apr 28, 2014 3:33:45 AM

MMM d, yyyy h:mm a | Apr 28, 2014 3:33 AM

M/d/yy h:mm:ss a z | 4/28/14 3:33:45 AM GMT-05:00

M/d/yy h:mm:ss a | 4/28/14 3:33:45 AM

M/d/yy h:mm a | 4/28/14 3:33 AM

h:mm:ss a z | 3:33:45 AM GMT-05:00

h:mm:ss a | 3:33:45 AM

h:mm a | 3:33 AM

EEEE, MMMM d, yyyy | Monday, April 28, 2014

MMMM d, yyyy | April 28, 2014

MMM d, yyyy | Apr 28, 2014

M/d/yy | 4/28/14

MMM d, yyyy - h:mm:ss a | Apr 28, 2014 - 3:33:45 AM

MMM d, yyyy - h:mm a | Apr 28, 2014 - 3:33 AM

Because keywords are processed from left to right, ensure the placement of the #a keyword with other keywords will provide the desired result. The following example

-P#p=aurora/project.pj#s=sub/project.pj#a="April 28, 2014 3:33:45 AM GMT-05:00"

specifies to start at aurora/project.pj as it is configured now, then move into its subproject sub/project.pj as it exists in that configuration, and then access that configuration as of April 28, 2014 3:33:45 AM GMT-05:00. The result is that sub/project.pj is the configuration it has now, but includes the project contents as of April 28. A potential consequence is that if sub/project.pj is currently configured as a variant subproject in the parent aurora/project.pj project, it is the variant project contents as of April 28 that is returned, even if sub/project.pj was configured as a mainline subproject in the parent aurora/project.pj on April 28. Instead, following example,

-P#p=aurora/project.pj#a="April 28, 2014 3:33:45 AM GMT-05:00"#s=sub/project.pj

specifies specifies to start at aurora/project.pj as it is configured now, then move into its subproject sub/project.pj as it exists in that configuration, and then access that configuration as of April 28, 2014 3:33:45 AM GMT-05:00.

Project configurations specified using #a appear as date-based build Project views and date-based build Sandbox views in the GUI.

◦ #b=value

#build=value

specifies the number, label or symbolic of the revision, for example,

#/aurora_project/source_code/#applications/savings_tool#b=:head

Timestamps may also display in project paths that specify the #b keyword; for the date format, see the documentation for the #a keyword. The date may also appear in the form: ts=timestamp.number.

This keyword is not supported on Sandbox commands that specify subproject scope using a Sandbox-relative source configuration path.

◦ #n=

#normal=

specifies that the subproject is a normal subproject. Do not enter a value.

This keyword is not supported on Sandbox commands that specify subproject scope using a Sandbox-relative source configuration path.

• #l=value

#location=value

specifies the absolute path of the target subproject (rather than the configuration path). This keyword can be used for commands where the subproject context is not needed and the subproject is not part of any configuration (si configuresubproject and si sharesubproject).

Note the following about the use of keywords:

◦ The order of the keywords is important. Keywords are processed from left to right to build the project specification.

◦ If you need to specify a '#' or '=' symbol in a keyword value, specify the symbol twice ('##', '==').

◦ If you are specifying a variant subproject, you must specify its path starting at the root of the variant project (the project through which the development path was created).

• --projectRevision=rev

identifies a particular revision of a build project.

This option cannot be used if you specify a project using a keyword string for the -P option. This option is also mututally exclusive with the --devpath option.

This option can also take the "asof:" identifier with a date, to return the project configuration as of a specific date. For example, --projectrevision asof:"April 28, 2014 3:33:45 AM GMT-05:00".

It is possible to specify the branch with the identifier, for example --projectrevision asof:"April 28, 2014 3:33:45 AM GMT-05:00"@1.3.1. Specifying the branch returns contents of the project at the specified date on the specified project branch.

It is possible to specify the development path with the identifier using the form asof:date:@:devpath, for example --projectrevision asof:"April 28, 2014 3:33:45 AM GMT-05:00"@:Release2. Specifying the development path returns contents of the project at the specified date on the specified project development path.

If the branch or development path is not specified, the current branch for the specified project configuration is used.

The following are additional forms may be displayed for configuration paths, and are represented here for information purposes:

asof:ts=timestamp.number
asof:ts=timestamp.number@branch
asof:ts=timestamp.number@:devpath

• -R

--[no|confirm]recurse

controls whether to recursively apply this command to any subprojects; used in all commands which take a list of members.

• -r rev

--revision=rev

uses a specified revision for the member. rev can be a valid revision number or a label. You may also facilitate automation with special keyword identifiers, specified using a colon (:) prefix (except for the state keyword). Acceptable identifiers are:

◦ :head

identifies the head revision.

◦ :member

identifies the member revision.

◦ :locked

identifies locked revisions.

◦ :master

identifies the member revision in the master project. This option is only applicable to variant projects.

◦ time:timestamp

uses the most recent revision on any branch at the specified timestamp. For example, -rtime:December 22, 2007 3:33:34 PM GMT-05:00. PTC RV&S recognizes all current timezones whatever your locale (country), for example, CEST, CET, EDT, PST, or GMT+/-hours:minutes. The following examples illustrate North American and German timestamps recognized by PTC RV&S:

Example 1: US GMT -5 (where E is the day of the week, M is the month, d is the numerical day of the month, y is the year, h is the time in hours, m is the time in minutes, s is the time in seconds, a is Greenwich Mean Time (GMT), z is the time zone difference from Greenwich Mean Time.

EEEE, MMMM d, yyyy h:mm:ss a z | Wednesday, April 28, 2007 3:33:45 AM GMT-05:00

EEEE, MMMM d, yyyy h:mm:ss a | Wednesday, April 28, 2007 3:33:45 AM

EEEE, MMMM d, yyyy h:mm a | Wednesday, April 28, 2007 3:33 AM

MMMM d, yyyy h:mm:ss a z | April 28, 2007 3:33:45 AM GMT-05:00

MMMM d, yyyy h:mm:ss a | April 28, 2007 3:33:45 AM

MMMM d, yyyy h:mm a | April 28, 2007 3:33 AM

MMM d, yyyy h:mm:ss a z | Apr 28, 2007 3:33:45 AM GMT-05:00

MMM d, yyyy h:mm:ss a | Apr 28, 2007 3:33:45 AM

MMM d, yyyy h:mm a | Apr 28, 2007 3:33 AM

M/d/yy h:mm:ss a z | 4/28/04 3:33:45 AM GMT-05:00

M/d/yy h:mm:ss a | 4/28/04 3:33:45 AM

M/d/yy h:mm a | 4/28/04 3:33 AM

h:mm:ss a z | 3:33:45 AM GMT-05:00

h:mm:ss a | 3:33:45 AM

h:mm a | 3:33 AM

EEEE, MMMM d, yyyy | Wednesday, April 28, 2007

MMMM d, yyyy | April 28, 2007

MMM d, yyyy | Apr 28, 2007

M/d/yy | 4/28/04

MMM d, yyyy - h:mm:ss a | Apr 28, 2007 - 3:33:45 AM

MMM d, yyyy - h:mm a | Apr 28, 2007 - 3:33 AM

Example 2: Germany CEST (where E is the day of the week, M is the month, d is the numerical day of the month, y is the year, H is the time in hours, m is the time in minutes, s is the time in seconds, Uhr 'z is Central European Summer Time (CEST).

EEEE, d. MMMM yyyy H.mm' Uhr 'z | Montag, 26. Juli 2007 22.26 Uhr CEST

EEEE, d. MMMM yyyy HH:mm:ss z | Montag, 26. Juli 2007 22:26:29 CEST

EEEE, d. MMMM yyyy HH:mm:ss | Montag, 26. Juli 2007 22:26:29

EEEE, d. MMMM yyyy HH:mm | Montag, 26. Juli 2007 22:26

d. MMMM yyyy H.mm' Uhr 'z | 26. Juli 2007 22.26 Uhr CEST

d. MMMM yyyy HH:mm:ss z | 26. Juli 2007 22:26:29 CEST

d. MMMM yyyy HH:mm:ss | 26. Juli 2007 22:26:29

d. MMMM yyyy HH:mm | 26. Juli 2007 22:26

dd.MM.yyyy H.mm' Uhr 'z | 26.07.2007 22.26 Uhr CEST

dd.MM.yyyy HH:mm:ss z | 26.07.2007 22:26:29 CEST

dd.MM.yyyy HH:mm:ss | 26.07.2007 22:26:29

dd.MM.yyyy HH:mm | 26.07.2007 22:26

dd.MM.yy H.mm' Uhr 'z | 26.07.04 22.26 Uhr CEST

dd.MM.yy HH:mm:ss z | 26.07.04 22:26:29 CEST

dd.MM.yy HH:mm:ss | 26.07.04 22:26:29

dd.MM.yy HH:mm | 26.07.04 22:26

H.mm' Uhr 'z | 22.26 Uhr CEST

HH:mm:ss z | 22:26:29 CEST

HH:mm:ss | 22:26:29

HH:mm | 22:26

EEEE, d. MMMM yyyy | Montag, 26. Juli 2007

d. MMMM yyyy | 26. Juli 2007

dd.MM.yyyy | 26.07.2007

dd.MM.yy | 26.07.04

MMM d, yyyy - h:mm:ss a | Jul 26, 2007 - 10:26:29 PM

MMM d, yyyy - h:mm a | Jul 26, 2007 - 10:26 PM

◦ timeonbranch:timestamp@branchnumber

uses the most recent revision on a specific branch at a specific timestamp. -rtimeonbranch:timestamp uses the most recent revision on the branch where the member revision currently resides. For example, -rtimeonbranch:December 22, 2007 3:33:34 PM GMT-05:00. -rtimeonbranch:timestamp@branchnumber uses the most recent revision on the specified branch at the specified timestamp. For example, -rtimeonbranch:December 22, 2007 3:33:34 PM GMT-05:00@1.5.1. PTC RV&S recognizes all current time zones whatever your locale (country), for example, CEST, CET, EDT, PST, or GMT+/-hours:minutes. For timestamp examples, see the :time:timestamp option.

Updating a revision by timestamp makes the most recent revision at the specified timestamp the member revision.

◦ :memberbranchtip

identifies the tip revision on the member revision branch.

◦ :working

identifies the working revision.

◦ :trunktip

identifies the tip revision on the trunk.

◦ state:statename

identifies the state, for example, Beta. This option is useful when you want to select revisions in a project that are in a specific state.

For each project member, PTC RV&S searches from the member revision on the development path to the root of the archive to find a revision that corresponds to the specified state. If the member revision is on a branch, PTC RV&S starts from the tip revision and searches to the root of the archive; other branches in the archive are not searched. If no revision on the development path matches the specified state, the command fails, stating “Revision does not exist.”

◦ devpath:devpathname

identifies the development path. This keyword only operates on member commands.

◦ build:revisionnumber

identifies the build revision number, which must be a valid project checkpoint number or project label in which a given member is contained. Must specify a registered project. This keyword only operates on member commands.

◦ :rule

identifies a rule defined with the si setmemberrule command.

◦ link:p=project[::d=devpath][::m=member][::recurse][::b=buildrevnumber]

allows you to set the member revision to whatever is the member revision for the corresponding member in a specific external project configuration (normal, variant, build). Links the project that the member belongs to (the target project) with the master project where:

▪ project is the master project

▪ devpath is the development path for the master project

▪ member is a member in the target project. If not provided, the project is searched for a member with the same backing archive. If recurse is specified, the search is recursive throughout the subprojects. There must be exactly one backing archive for each member.

A possible application is to update all members to the same revision, even if they do not have the same backing archive.

• -S sandbox

--sandbox=sandbox

specifies the location of a Sandbox. In some cases, the commands that take this option do something with the Sandbox contents themselves. In other cases, specifying the Sandbox location is simply a way to locate, or "point to", the corresponding project file. This option is mutually exclusive with -P project|--project = project.

Locations that include spaces must be enclosed by quotes.

• --user=name

identifies the user to use for connecting to the PTC RV&S Server.

• --customFieldDefinition=value

specifies the definition of custom fields.

To define a custom field on an item, a Custom Fields field must be added as a visible field on a type. The data type of a custom field can be Integer, Floating Point, Date, Pick, Logical, or Short Text.

name

specifies the name of the custom field.

type

specifies the data type of the custom field.

After a custom field is defined, the user cannot change the type.

description

specifies the description of the custom field.

default

specifies the default value.

values

specifies the pick values in the format text=value:text1=value1. Text is an alphanumeric string and value is its associated integer value.

newname

specifies the new name for the field. This attribute cannot be specified while defining the custom field.

For example:

◦ im createissue --customFieldDefinition="name=field1,type=integer,default=100,description=some sample desc”

creates a custom field: field1 of integer data type with default value set to 100

◦ im createissue--customFieldDefinition="name=field2,type=pick,default=a,values=a=1:b=2:c=3,description=some sample desc”

creates a custom field: field2 of pick data type with pick values as a, b, c and having default value set to a.

To specify more than one custom field definition, specify this option multiple times for each custom field that you want to add or modify on the issue.

When there are multiple custom field definitions using the same name, the most recent one is displayed.

When the name, description or any of the attributes are used multiple times in the same option, the most recent one is displayed. For example, --customFieldDefinition=name=a10,type=shorttext --customFieldDefinition=name=a10,type=logical,

the field a10 with logical data type is displayed.

• --customFieldValue=value

specifies value to the Custom Fields field.

To set the custom field values on an item for a custom field defined on a project, the field Custom Field Values must be added as a visible field on a type, and Project field must be set to a valid project.

The format to set a custom field value is described below:

‘name=<name>,value=<value>’

name

specifies the name of the custom field defined on a project item.

value

specifies the value for the custom field in a specific format. For example:

im createissue --customFieldValue=name=field1,value=200

sets the value of field1 to "200".

im createissue --customFieldValue=name=field2,value=c

sets the value of field2 to "c".

To set multiple custom field values, specify this option multiple times for each Custom Field Value that you want to set on the issue.

• --field="Custom Fields=value"

specifies creating multiple Custom Field values in a single command using the --field option.

When a user specifies --field="Custom Fields”=”<semi colon delimited custom field definitions>”, the custom fields are added, or removed depending on following scenario:

When a user specifies all the custom field definitions on the item along with the new definitions that conflict with the existing custom fields, the existing custom field definitions are removed and the new custom field definitions are added.

For example, there are fields such as field1 of integer type, field2 of pick type, and field3 of date type existing on a server. Specify the option along with field4 of logical data type as, --field=”Custom Fields”=”name=field1,type=float,default=0.125;name=field2,type=shorttext,default=sampletext, description=test;name=field3,default= 03/12/2016 10:12:11 PM;name=field4,type=logical,default=false”

This creates new definitions field1, field2, field3 and field4 as specified. Since the fields are created, the type can be changed.

When a user does not specify any custom field definitions, all the existing custom field definitions are removed.

• --[no|confirm]removeCustomFieldDefinitions

controls whether to allow removal of custom field definitions. For example:

im editissue --field="CustomFields=name=c10,type=integer" --removeCustomFieldDefinitions

This removes all the custom fields other than c10 without asking for any confirmation.

im editissue --removeCustomFieldDefinition=c10 --removeCustomFieldDefinition=c11 --removeCustomFieldDefinitions

This removes the custom fields c10 and c11 without asking for any confirmation.

• --[no|confirm]removeCustomFieldPickValues

controls whether to allow removal of pick values for the custom fields.

For example, im editissue --field="Custom Fields=name=c10,type=pick,values=" --removeCustomFieldPickValues

This removes all the pick values of the custom field c10 without asking for any confirmation.

im editissue --customFieldDefinition=name=c10,values= --removeCustomFieldPickValues

This removes the pick values from custom field c10 without asking for any confirmation.

• --field="Custom Field Values=value"

where value is 'value' is 'name=<name>, value=<field value>

specifies creating multiple custom field values in a single command using the --field option.

User can perform this operation by specifying the --customFieldValue option multiple times in a single command.

When a user specifies --field="Custom Field Values=<semi colon delimited custom field values>", the existing custom field values under the field Custom Field Values are added, or removed depending on following scenario:

User specifies all the custom field values along with the new field values, then the new values are set and the other values are cleared. For example, there are fields such as field1 of integer type, field2 of pick type, and field3 of date type existing on the server, and there is field4 of logical type which is not set on server. Specify the option as, --field=”Custom Field Values”=”name=field4,value=true”

This sets the value for field4 to “true”.

User does not specify any of the existing Custom Field Values, then all the values are cleared.

• --removeCustomFieldDefinition=name

removes the custom fields defined on a project backing item.

To remove a custom field from an item field, the Custom Field must be visible on the type.

• --[no|confirm]removeCustomFieldValues

specifies removal of Custom Field Values.

For example, im editissue --field="Custom Field Values=name=c10,value=123" --removeCustomFieldValues

This confirms the removal of all the field values of the Custom Fields fields other than c10.

You must enclose the value for custom field in double-quotes so that it is parsed properly.

• --[no|confirm]projectChangeRemoveCustomField

specifies confirmation to remove the custom fields or the custom field values when the project is changed.

Universal Options

The following universal options apply to all CLI commands.

• --[no]batch

controls batch mode. Batch mode forces the application to process commands without prompting for responses.

• --cwd=directory

acts as if the command is executed in the specified directory. In particular, any files and members in the selection are treated as being relative to that directory.

Suppose you are working in the c:\sandbox directory and you want to issue the check out command so that the implicit Sandbox selection will work in a subdirectory, rather than having to specify the complete path for subdirectory Sandbox names. You could use the --cwd option to do this, for example:

si co --cwd=./demoapp/controls demoappctrl.c

makes PTC RV&S work in the c:\sandbox\demoapp\controls directory and follows implicit Sandbox selection rules from there to find the appropriate Sandbox, then checks out the demoappctrl.c file.

• -F file

--selectionFile=file

provides an alternative way to specify the selection. The specified file is a text file containing a list of file names, members, projects, or sandboxes, one per line. The command operates on all the listed files.

The --selectionFile option is only relevant for commands that have selections and can only be used to specify the command selection (not command options). Be careful to avoid duplications. In some cases if a file, member, project or Sandbox is listed twice in the file, the command may report an error.

• --forceConfirm=[yes|no]

-N

--no

-Y

--yes

controls the responses of either "yes" or "no" to all prompts. Specifying "yes" or "no" can be an easy way to accomplish the same thing as specifying other command options with [no|confirm] prefixes, for example the --[no|confirm]overwriteChanged option in the si co, si resync, and si revert commands. Specifying --yes or --no accomplishes the same thing for --overwriteChanged and --nooverwriteChanged, but further responds "yes" or "no" to all other questions asked.

Be careful to use specific options if you want variations in your responses to prompts. The

--yes and --no options in particular are wide-ranging types of responses and should be used only in rare circumstances.

• -g

--gui

allows user interaction to happen through the GUI (graphical user interface).

• --width

controls the width in pixels of the graphical user interface.

• --height

controls the height in pixels of the graphical user interface.

• -x

specifies the x location in pixels of the graphical user interface window.

• -y

specifies the y location in pixels of the graphical user interface window.

• --quiet

controls the status display to silence most information messages.

• --settingsUI=[gui|default]

controls the GUI for command options.

• --status=[none|gui|default]

controls the status display.

• -?

--usage

shows usage for the command.

Diagnostics

See the diagnostics reference page for possible exit status values.