AMF

AutoMergeFiles [True | False]

If True, requests automatic merging of files found in the compare phase in a merge state. When an auto-merge is successful, the result file is retained as part of the VCM session. Otherwise, the result file is discarded and the affected files remain in an unresolved merge state. AutoMergeFiles is ignored for Compare sessions.

AMP

AutoMergeProperties [True | False]

If True, requests automatic merging of properties for items found in the compare phase in a merge state. If property auto-merging is successful, the merged item is retained as part of the VCM session. Otherwise, the merged item is discarded and the items are flagged as being in an unresolved property merge state. AutoMergeProperties is ignored for Compare sessions.

BL

BreakLocks [True | False]

If True, requests that an attempt is made to break any lock found on items used in the compare phase. Breaking a source or target item lock is only required when the lock is owned by another user. Lock breaking requires a special permission and may not be successful. BreakLocks is ignored for Compare sessions.

CSF

CaseSensitiveFilenames [True | False]

If True, considers file names different only by case as unequal for purposes of evaluating the PreventDuplicateFilenames option and for matching files between source and target views.

Checkout

CP

CheckoutPreview <files> [<check-out options>]

This option specifies that files within a "merge preview" are to be checked out to the client workspace. A "merge preview" is a simulation of the target view updated with all changes in the VCM session. The <files> syntax allows file names and/or patterns to be checked out from specified folders in the merge preview. The optional <check-out options> control options such as where files are to be checked-out and what status of files should be checked-out.

When CheckoutPreview is specified, files are checked out after the compare phase, after auto- and manual-merging has occurred, but before a commit occurs. The check-out occurs only if the VCM session has no file content merge conflicts. If merge conflicts exist, an error is displayed, and no merge is performed, regardless of the CommitMerge option. If no merge conflicts exist and CommitMerge is True, the VCM session is committed after the check out is performed.

Example:

CheckoutPreview /src/com/acme/*.java +cwf +eol LF +filter CGMIOU +o +ro
   +rp C:\BuildDir

Commit

CM

CommitMerge [True | False]

Specifies whether or not the results of VCM session should be committed. False specifies that a commit will not be performed. This option can be used to produce a compare/report-only session. True specifies that the commit should occur only if there are no unresolved conflicts. CommitMerge is ignored for Compare sessions.

If specifying this parameter, provide a custom VCM merge type name (created on the Customize VCM tab in the Server Administration Tool) in which individual difference types can be overridden at will.

For instance, Modified In Source, Modified In Target has a default action of Merge. This can be overridden to OVERWRITE. Similarly, Target View has Multiple Floating Shares has a default action of Needs Review. This can be overridden to IGNORE.

Using Custom Difference Types provides an alternative mechanism to specifying either Match States or Session Option Properties, such as Lock Source for Difference and Ignore Merge Points, for example. Specifically, the values of the difference type actions and session properties from Custom Difference Types override anything equivalent specified through the vcmutility command line.

Besides supporting tracking all configuration options through the Server Administration Tool, using this parameter also has the added advantage of simplifying and minimizing the vcmutility parameter set.

Below is an example of content in the vcmutilityoptions.txt file that specifies the following: run a promote from StarDraw Release 1.0 Maintenance to StarDraw in project StarDraw using a custom merge type called vcmutilityConfig. The custom merge type vcmutilityConfig was first created and saved using the Server Administration Tool.

Server Administrator:Administrator@localhost:49201
Project StarDraw
MergeType Promote
TargetView StarDraw
SourceView StarDraw/Release 1.0 Maintenance
CustomDifferenceTypes vcmutilityConfig
CommitMerge False

DA

DefaultAction [MergeType <merge type>] [ItemType <item type>] <match state> <action>

Specifies a default <action> for items that are compared and meet the conditions specified in the given <match state>. The VCM utility uses a rules-based "decision table" to determine what action, if any, should be taken when it finds item differences between the source and target views. The DefaultAction option allows the default rules to be overridden. This option can be specified multiple times to change the default action for multiple differences. However, the order of definition is important: if two overrides are both applicable to an item difference found in the compare phase, the last override specified takes precedence over the prior one.

• If MergeType is specified, the DefaultAction only applies to VCM sessions of the specified <merge type>: Rebase, Promote, or Replicate.
• If MergeType is not specified, the DefaultAction applies to the current VCM session.

Specifying a DefaultAction with a different <merge type> than that of the current session allows rules used by different VCM sessions to be specified in a single options file.

If ItemType is specified, the DefaultAction applies only to items of the specified <item type>: CRs, Files, Folders, Requirements, Tasks, or Topics. By default, a DefaultAction applies to items of all types.

The <match state> determines the conditions that must be met by the source and/or target items during comparison. A <match state> consists of one or more source/target <item condition> definitions, each of which has a <condition name> (for example,source.moved), and a <condition value> (True, False, or Unspecified). The <condition value> is optional and defaults to True. A <match state> is the union of all the conditions defined for it.

The <action> determines how to handle source/target item pairs whose differences match the <match state>. The <action> merely defines the default action for matching items; the actual action can be changed after compare in the StarTeam Cross-Platform Client.

Some example DefaultAction definitions are shown below:

//When a source item has moved, but the target item has not, 
//ignore the move.
DefaultAction source.moved target.moved false Ignore

//In a Rebase, if a file is binary and has been modified in both the 
//source and target, overwrite the target with the source version.
DefaultAction MergeType Rebase
   items.binaryfile
   source.modified
   target.modified
   Overwrite

//In a Promote, if a CR has moved in both the source and target views
//(to different folders), move the target item to the matching folder as
//the source item, but only if the CRs are on the same branch.
DefaultAction MergeType Promote ItemType CR
   source.moved
   target.moved
   items.branched false
   Move

DefaultAction is ignored for Compare sessions.

DC

DefaultComment <comment>

Specifies the default revision comment to be used for new item revisions created in the target view. The <comment> is a free-form text string. Within the comment value, all white space sequences, including line breaks (CRs and LFs), blanks, and tabs, are converted into a single blank for each occurrence. By default, an auto-generated comment is used as the default revision comment for new item revisions. To disable the use of a default revision comment, specify the DefaultComment option with an empty value.

DefaultComment is ignored for Compare sessions.

DR <pathToReportfile>

Specifies a path and file name to which the difference report will be written

Exclude the specified folders from the source scope. Only folders explicitly specified in Exclude <files> or Exclude <folders> are excluded. Consequently, an Exclude <folders> option can be used to "prune" unwanted folders from the source scope.

For Example:

// suppose we decide to explicitly include CRs and files in all folders below /a/b/
Include /a/b/ +all CRs Files

//But we want to exclude CRs in folder /a/b/c/
Exclude /a/b/c/ CRs  OR
Exclude /a/b/c/ +all CRs

//But if this CR is in folder /a/b/c/, it is still included
Include CR 12345

Regardless of declaration order, Exclude options are processed after Include options.

If no Include options are specified, the default VCM session scope is implicitly "all files in the source view". This is equivalent to explicitly specifying include /* +all. If at least one Include option is specified, the scope is explicitly limited to those items selected by Include statements. In both implicit and explicit scopes, all selected source items are pruned by any Exclude options.

All Include and Exclude options must identify objects (labels, files, CRs, and so on) in the source view. Also, selection type names can be singular or plural (RevLabel, CR, and so on), even if multiple values are provided.

Exp

Export <VCM exchange file>

The Export option specifies that all the VCM session information, including merged result files, are to be combined and stored in the given <VCM exchange file>. The exchange file name is always suffixed with a .vcmx extension. A VCM exchange file allows the entire VCM session to be transported to another machine, allowing that machine to perform an Import command, which resumes the session. (See the Import command for more information.)

If the <VCM exchange file> does not contain path information, it is saved in the user's home directory (what Java identifies as user.home).

FFCS

FixFloatingChildShares [True | False]

Specifies whether, in Rebase and Replicate merge operations, each target view item found that is a floating share of a source view item should be “fixed” by pinning it. When a target view item is a floating child share of a source item (which implies that the target item has not branched), differences will not be detected between the source and target item during VCM sessions because changes to the source item immediately float to the child item. VCM best practices suggest that child shares should always be pinned, allowing changes to propagate from the source to target view in a controlled manner. This option allows floating child items found by VCM to be “fixed” by pinning them to the parent item revision. Specifying this option has a performance cost due to the extra commands required to check each target item examined during the compare phase.

IMP

IgnoreMergePoints [True] | [False]

Specifies whether merge points should be ignored during the comparison phase. If True, items with merge conflicts use their branch point as the common ancestor instead of the source revision of the last merge point.

Inc

Include {<change requests> | <files> | <folders> | <process items> | <requirements> | <revision labels | <tasks> | <topics> }

Includes the specified items in the source scope. The Include option can be provided multiple times, causing all selected items to be included. Only one item selection type (revision labels, change requests, and so on) can be specified with each Include option. The selection type keyword, which is optional for files and folders, can be singular or plural, for example, ProcessItem or ProcessItems.

Examples:

Include CRs ALL
Include /src/com/*.java +all *.jar +2 *.jpx Buildnumber.h
Include Folders /docs/api/ +all
Include ProcessItem CR 451
Include Reqs 4515 4516
Include RevLabel "Beta Fix 12.413"
Include Topic 14512
Include Task 413

LMC

LockMergeConflicts {None | Source | Target | Both}

Specifies that items with unresolved conflicts are to be locked exclusively in either the Source, Target, or Both views. Locks are acquired in the compare phase. None is the default, which specifies that no locks are to be created for items with unresolved locks. Note that locks are only applied to source and/or target items for which differences are found. Locks are not applied to items that are compared for which no differences are found. Also, note that this option is not affected by the Project option Require exclusive comment when files are checked in nor the client workstation option Exclusively lock files on check-out. Those options are properly handled by the VCM engine. LockMergeConflicts is ignored for Compare sessions.

MMF

ManualMergeFiles [True | False]

If True, this causes the file merge tool configured for the workstation to be launched for each source/target file pair found in a content merge state.

The ManualMergeFiles option can be used in conjunction with AutoMergeFiles:

• If a merge conflict is detected and AutoMergeFiles is requested, an auto-merge attempt is made first.
• If the conflict is resolved, the merged result file is saved, and a manual merge is not needed.
• If the auto-merge is not successful, or if AutoMergeFiles has not been requested, then if ManualMergeFiles is True, a manual file merge is performed.

Match [Folder] *{<folder path> to <folder path>}

Specifies that for comparison purposes, the folder specified in the first <folder path>, which must reside in the source view, should match the second <folder path>, which must reside in the target view. The Match option is sometimes needed to prevent “ambiguous match” conditions, which can occur when one of the views is a non-derived view. Typically, the Match option is only needed to match the source and target view root folders. However, other folders can be matched to resolve other ambiguous match conditions reported by the compare phase.

Both the source and target <folder path> must begin and end with a forward slash ("/").

By convention, the root folder is represented by a single "/". This means that the root folder name should not be provided in folder paths. For example, if the root folder is named “StarDraw”, the folder path for the immediate child folder “Source Code” is simply "/Source Code/".

Examples:

// Force the source and target root view folders to match.
Match / to /

//Force the source view folder "/Source Code" to match the target view
//folder "/Modules/Materials/src".
Match "/Source Code/" to "/Modules/Materials/src/"

Type

MT

MergeType {Compare | Rebase | Promote | Replicate}

Specifies whether to perform a Compare session or a Rebase, Promote, or Replicate merge session. If only a SourceView is specified, MergeType defaults to Promote. If only a TargetView is specified, MergeType defaults to Rebase. If both SourceView and TargetView are specified, MergeType must be specified. For a Compare session, the source and target views can be the same.

Na

Name <Change Package name>

Specifies the name of the change package associated with the VCM session. For servers that support change packages, a name is automatically chosen when a change package is created by saving or committing the session. This option allows a specific name to be used instead of the default name. However, the name must be unique from all other change package names already saved or committed for the target view, otherwise the save or commit action will fail.

When the Name option is used in conjunction with the Open command, the opened change package is renamed to the given value.

Also see the Save and CommitMerge options.

PostCL

PostCommitLabel <label>

If the VCM session is committed, the given view<label> is created in the target view after all updates are performed. The label reflects the revisions of all target view items used during the compare phase, modified by the changes made by the commit phase. This means the label contains new items, new item revisions, and item moves, but items deleted by the commit will be detached from the label. The post-commit label is essentially identical to the "pre-merge view". PostCommitLabel is ignored for Compare sessions.

By default, a post-commit view label is created with a default name. To disable the post-commit view label, specify PostCommitLabel with a blank value (that is, " ").

PostRL

PostCommitRevLabel <label>

If the VCM session is committed, the given revision<label> is created in the target view, and all items modified by the VCM session, except for deleted items, are attached to it. Consequently, the label contains items that were added, moved, re-pinned, or updated in any other way (except for deletion) by the VCM session. PostCommitRevLabel is ignored for Compare sessions.

By default, a post-commit revision label is not created.

PreCL

PreCommitLabel <label>

The given view <label> is created in the target view, reflecting the snapshot used in the compare phase. The label reflects the revisions of all target items used during the compare phase. PreCommitLabel is ignored for Compare sessions.

By default, a pre-comimt view label is not created.

PreRL

PreCommitRevLabel <label>

If the VCM session is committed, the given revision <label> is created in the target view, and all non-ignored target view items are attached to it in their “before” state. That is, target view items to be modified by the session are attached to the revision label before they are modified. This means that items to be added (for example, shared) to the target view will not be attached, but items to be deleted will be attached. PreCommitRevLabel is ignored for Compare sessions.

By default, a pre-commit revision label is not created.

PDF

PreventDuplicateFilenames [True | False]

If True, it specifies that sharing a new file to the target view is not allowed if it results in two identically-named files to exist in the same folder.

Pro

Project <project>

Specifies the project to be used in the VCM session. This option is required. The source and target views must belong to the same <project>. Project names are case-insensitive.

RD

ReportDiffs [True | False]

If True, causes a report to be generated listing item differences found in the compare phase. The difference report is generated in the user's home directory (what Java identifies as user.home) with the following title:

VCMDiffReport-YYYY-MM-DD_hh-mm-ss.html

where YYYY-MM-DD and hh-mm-ss are the current date and time in the local time zone.

RU

ReportUpdates [True | False]

If True, causes a report to be generated listing all changes made to the target view in the commit phase. The update report is generated in the user's home directory (what Java identifies as user.home) with the following title:

VCMUpdateReport-YYYY-MM-DD_hh-mm-ss.html

where YYYY-MM-DD and hh-mm-ss are the current date and time in the local time zone.

ReportUpdates is ignored for Compare sessions.

Save [<VCM session file>]

Specifies that the VCM session is to be saved. By default, uncommitted VCM sessions are automatically saved to a VCM session (.vcms) file with a default name using the format:

<user home>/VCMSession-YYYY-MM-DD_hh-mm-ss.vcms

where YYYY-MM-DD_hh-mm-ss is the date and time when the session is saved. The folder <user home> is the user's home directory.

If the Save option is specified with a <VCM session file> name, an uncommitted session is saved with the given file name instead of the default name. If needed, .vcms is appended to the name. If the given file name does not contain path information, the session file is stored in the user.home folder. A .vcms file contains VCM session metadata, but not the contents of merged files. Merged file contents are stored in a user-relative temporary folder, referenced by elements in the session file. Consequently, a .vcms file can only be used to resume the VCM session on the same workstation. (See the Resume command.)

When the Save option is specified without a file name, an attempt is made to save an uncommitted VCM session as an active change package in the target view. The change package is saved with the default or user-specified name (see the Name option). A VCM session saved as a change package can later be resumed on any workstation using the Open option. However, if the server does not support change packages or a server-side save is unsuccessful, the session is instead saved to a .vcms file with a default file name as described above.

When a commit is successfully performed, the Save option is ignored. If the server supports change packages, the committed session creates a Committed change package using the default or user-specified name (see the Name option). If a .vcms file was previously created, it is deleted along with all merged result files created by the VCM session.

Also see the Export option.

SrcLabel

SL

SourceLabel <label>

Requests the source view to be used as of a given view label. Label names are case-insensitive. Only one of SourceLabel, SourceState, and SourceTime can be specified. If none of these options is specified, the option SourceTime Now is implicitly used.

SrcState

SS

SourceState <state>

Requests the source view to be used as of a given view promotion state. Promotion state names are case-insensitive. Only one of SourceLabel, SourceState, and SourceTime can be specified. If none of these options is specified, the option SourceTime Now is implicitly used.

SrcTime

ST

SourceTime {<timestamp> | Now}

Requests the source view to be used as of a given timestamp. The keyword Now causes a snapshot of the current time to be used as configuration timestamp. Only one of SourceLabel, SourceState, and SourceTime can be specified. If none of these options is specified, the option SourceTime Now is implicitly used.

Source

SV

SourceView <view>

Specifies the source view to be used in the VCM session. If more than one view within the project has the same <view> name, a slash-separated "view path" can be provided (for example, MainView/ChildView/GrandchildView). If a view name contains embedded slashes, it must be enclosed in quotes.

SourceView is optional for Rebase merges; if specified, it must be the parent of the target view.

TgtLabel

TL

TargetLabel <label>

Requests the target view to be used as of a given view label. TargetLabel can only be used for Compare sessions. Label names are case-insensitive. Only one of TargetLabel, TargetState, and TargetTime can be specified. If none of these options is specified, the option TargetTime Now is implicitly used.

TgtState

TS

TargetState <state>

Requests the target view to be used as of a given view promotion state. TargetState can only be used for Compare sessions. Promotion state names are case-insensitive. Only one of TargetLabel, TargetState, and TargetTime can be specified. If none of these options is specified, the option TargetTime Now is implicitly used

TgtTime

TT

TargetTime {<timestamp> | Now}

Requests the target view to be used as of a given timestamp. TargetTime can only be used for Compare sessions. The keyword Now causes a snapshot of the current time to be used as configuration timestamp. Only one of TargetLabel, TargetState, and TargetTime can be specified. If none of these options is specified, the option TargetTime Now is implicitly used

Target

TV

TargetView <view>

Specifies the target view to be used in the VCM session. If more than one view within the project has the same <view> name, a slash-separated "view path" can be provided (for example, MainView/ChildView/GrandchildView). If the view name contains embedded slashes, it must be enclosed in quotes.

TargetView is optional for Promote merges; if specified, it must be the parent of the source view. For Compare sessions, the target view can be the same as the source view.

UR <pathToReportfile>

Specifies a path and file name to which the update report will be written