Copyright: Copyright© 1992-1996, StarBase Corporation
Citation: Copyright© 1992-1996, StarBase Corporation. All rights reserved.


StarTeam command-line overview
 Versions command-line overview

You can perform the following operations from a command-line session using the command stcmd and the appropriate options. These commands also allow you to perform Versions’s version control operations from any development environment that allows you to add tools to menus.

•	Add files (stcmd add)

•	Check in files (stcmd ci)

•	Check out files (stcmd co)

•	Lock or unlock files (stcmd lck)

•	Compress or decompress files (stcmd cmp)

•	Merge files (stcmd mrg)

•	Designate build (stcmd dbd)

•	Designate milestone (stcmd dms)

•	Change description (stcmd dsc)

•	Set maximum number of versions (stcmd mnv)

•	Give versions permanent or non-permanent status (stcmd prm)

•	Delete versions (stcmd dvr)

•	Purging non-permanent versions (stcmd prg)

Use /? to display the options available with the command.

For example, stcmd /? displays the general syntax for stcmd and stcmd add /? Displays the options available when adding files. Using stcmd and stcmd add without the /? also works.

 Related Topics


 Syntax

The syntax for the command line uses the following conventions:

Bold	Information that you must use exactly as shown (if you use it).

Italics	Information that you replace with the names of your files, subprojects, etc.

[     ]	Optional information appears in square brackets.


 stcmd add

Use stcmd add to add files to a project from the command line.

Syntax:

stcmd add [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is] [/un “userName”]  [/pw “password”]  [/q]  [/x]  [/l | /u [/ro]]  [/d “fileDescription”]  [/vl “versionLabel”]  [/k]  [/md maxDelta]  [/mo maxOmega]  [/fo]  [files...]

 Related Topics


 stcmd add example

The following example uses stcmd add to add .doc files to a subproject of StarDraw called User Manual. It locks the files and gives them the description “First draft of chapter”.

stcmd add /p “c:\stardraw.stp” /s “User Manual” /un “NAllis” /pw “password” /l /d “First draft of chapter” *.doc


 stcmd ci

Use stcmd ci to check in project files from the command line.

Syntax:

stcmd ci [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [/l | /u [/ro]] [/vl “versionLabel”]  [/k]  [/f NCI]  [/o]  [/fo]  [/r “reasonCheckIn”]  [files...]

 Related Topics


 stcmd ci example

The following example uses stcmd ci to check in .bmp files to a subproject called On-line Help. On-line Help is a subproject of SourceCode, which is a subproject of StarDraw. The command unlocks the files, makes the working copy read-only, and gives them a reason for check in.

stcmd ci /p “c:\stardraw.stp” /s “SourceCode!On-line Help” /un “NAllis” /pw “password” /u /ro /r “revised for beta” *.bmp


 stcmd co

Use stcmd co to check out project files from the command line.

Syntax:

stcmd co [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [/l | /u [/ro]]  [/vn versionNumber | /vl “versionLabel” | /vd asOfDateTime]  [/f NCO]  [/o]  [/ts]  [files...]

 Related Topics


 stcmd co example

The following example uses stcmd co to lock and check out .doc files from a subproject of StarDraw called User Manual.

stcmd co /p “c:\stardraw.stp” /s “User Manual” /un “NAllis” /pw “password” /l *.doc


 stcmd lck

Use stcmd lck to lock or unlock project files from the command line.

Syntax:

stcmd lck [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [/l | /u [/ro] ]  [files...]

 Related Topics


 stcmd lck example

The following example uses stcmd lck to unlock all the files in SourceCode, a subproject in the project StarDraw, as well as all the files in subprojects of SourceCode.

stcmd lck /p “c:\stardraw.stp” /s “SourceCode” /is /un “NAllis” /pw “password” /u *.*


 stcmd mrg

Use stcmd mrg to merge one or more files from a branch subproject back into the original subproject. For each file, Versions performs a three-way merge and copies the resulting file to the working directory for the original subproject, overwriting the working file that is there. The three file versions that are merged are:

•	The latest version of the specified file in the branch subproject

•	The latest version of the file in the original subproject that corresponds to the file in the branch

•	The version of the file in the original subproject from which the file in the branch was originally derived

When you branch a subproject, the latest version of each file in the original subproject is copied to the branch. Initially these two files are twins. However, both can be checked in and out and have their contents modified. Eventually they are simply two files with the same name and the same parent file version (the version of the file originally copied from the original subproject to the branch). Merging these three files incorporates all the changes made in the original and the branch subproject. You can edit the merged file and then check it in to the original subproject.

Syntax:

stcmd mrg [/p ”projFile.stp” | “serverDesc:projName”]  /s “subproj1!subproj2!...”  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [files...]

 Related Topics


 stcmd mrg example

The following example uses stcmd mrg to merge the file ipframe.cpp from the branch subproject SourceCode RSL with its “sister file” in the root subproject SourceCode. Versions knows that the SourceCode RSL subproject was branched from SourceCode as well as what version of ipframe.cpp in SourceCode became the first version of ipframe.cpp in SourceCode RSL. Versions merges the current versions of ipframe.cpp found in both the root and branch subproject with the parent version from the root project. The results are copied to the working directory for SourceCode as the working file ipframe.cpp.

stcmd mrg /p “c:\stardraw.stp” /s “SourceCode RSL” /un “NAllis” /pw “password” ipframe.cpp


 stcmd prm

Use stcmd prm to make the specified file versions permanent or non-permanent.

Syntax:

stcmd prm [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x] [/vn versionNumber | /vl “versionLabel” | /vd asOfDateTime] [/k]  [files...]

 Related Topics


 stcmd prm example

The following example uses stcmd prm to make permanent the most recent versions of all the files in SourceCode, a subproject in the project StarDraw, as well as all the files in subprojects of SourceCode.

stcmd prm /p “c:\stardraw.stp” /s “SourceCode” /is /un “NAllis” /pw “password” /k *.*


 stcmd prg

Use stcmd prg to purge nonpermanent file versions from the command line.

 When project security is enabled, only an administrator can purge files.

Syntax:

stcmd prg [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [files...]

 Related Topics


 stcmd prg example

The following example uses stcmd prg to purge all the non-permanent versions of the files in SourceCode, a subproject in the project StarDraw, as well as all the non-permanent versions of the files in subprojects of SourceCode.

stcmd prg /p “c:\stardraw.stp” /s “SourceCode” /is /un “NAllis” /pw “password” *.*


 stcmd dvr

Use stcmd dvr to delete versions of project files from the command line.

 When project security is enabled, only an administrator can delete a version.

Syntax:

stcmd dvr [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [/o] [/vn versionNumber | /vl “versionLabel”]  [files...]

 Related Topics


 stcmd dvr example

The following example uses stcmd dvr to delete the most recent versions of all the files in SourceCode, a subproject in the project StarDraw, as well as all the files in subprojects of SourceCode.

stcmd dvr /p “c:\stardraw.stp” /s “SourceCode” /is /un “NAllis” /pw “password” *.*


 stcmd mnv

Use stcmd mnv to set the maximum number of versions for project files from the command line. You can set a maximum for files that use delta storage, files that use omega storage, or both.

 When project security is enabled, only an administrator can set these maximums.

Syntax:

stcmd mnv [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [/md maxDelta]  [/mo maxOmega]  [files...]

 Related Topics


 stcmd mnv example

The following example uses stcmd mnv to set the maximum number of versions to 20 for delta files in SourceCode, a subproject in the project StarDraw, as well as all the files in subprojects of SourceCode.

stcmd mnv /p “c:\stardraw.stp” /s “SourceCode” /is /un “NAllis” /pw “password” /md 20 *.*


 stcmd dsc

Use stcmd dsc to change a file description from the command line.

Syntax:

stcmd dsc [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x] /d “newDescription”  [files...]

 Related Topics


 stcmd dsc example

The following example uses stcmd dsc to change the description of stdafx.cpp in SourceCode, a subproject in the project StarDraw.

stcmd dsc /p “c:\stardraw.stp” /s “SourceCode” /un “NAllis” /pw “password” /d “Source code for StarDraw” stdafx.cpp


 stcmd cmp

Use stcmd cmp to compress or decompress project vault files from the command line.

Syntax:

stcmd cmp [/p ”projFile.stp” | “serverDesc:projName”]  [/s “subproj1!subproj2!...”]  [/is]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  [/c | /dc]  [files...]

 Related Topics


 stcmd cmp example

The following example uses stcmd cmp to compress all the project vault files in SourceCode, a subproject in the project StarDraw, as well as all the files in subprojects of SourceCode.

stcmd cmp /p “c:\stardraw.stp” /s “SourceCode” /is /un “NAllis” /pw “password” /c *.*


 stcmd dbd

Use stcmd dbd to designate a project build from the command line. A build includes all the files in the project.

 When project security is enabled, only an administrator can designate a build.

Syntax:

stcmd dbd [/p ”projFile.stp” | “serverDesc:projName”]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  /nl “buildLabel”  [/vd asOfDateTime]

 Related Topics


 stcmd dbd example

The following example uses stcmd dbd to designate as a build the most recent versions of all the files in the project StarDraw.

stcmd dbd /p “c:\stardraw.stp” /un “NAllis” /pw “password” /nl “Build 14”


 stcmd dms

Use stcmd dms to designate a project milestone from the command line. A milestone includes all the files in the project.

 When project security is enabled, only an administrator can designate a milestone.

Syntax:

stcmd dms [/p ”projFile.stp” | “serverDesc:projName”]  [/un “userName”]  [/pw “password”]  [/q]  [/x]  /nl “milestoneLabel”  [/vl “buildLabel” | /vd asOfDateTime]

 Related Topics


 stcmd dms example

The following example uses stcmd dms to designate as a milestone the most recent versions of all the files in the project StarDraw.

stcmd dms /p “c:\stardraw.stp” /un “NAllis” /pw “password” /nl “Beta”


/p

Indicates what project is to be used by providing one of the following:

•	The name of the project database file for the project. Use the complete pathname to the file and the .stp extension in double quotation marks. For example, “c:\stardraw.stp”.

•	The server description and project name combination. Separate the two with a colon and delimit them with double quotation marks. For example, “Orion:NEF”, where Orion is the server name and NEF is the name of the project. These are case insensitive.


/s(for stcmd add)
/s

Provides the name of the subproject, preceded by the names of any other subprojects that separate it from the root subproject. The names of each subproject in the “path” are separated by exclamation points (!) and the complete string is enclosed in double quotation marks. When /s is not used, the files are assumed to be in or intended for the root subproject’s working directory. Do not include the root subproject in the parameter.


/s(for stcmd mrg)
/s

Provides the name of the branch subproject, preceded by the names of any other subprojects that separate it from the root subproject. The names of each subproject in the “path” are separated by exclamation points (!) and the complete string is enclosed in double quotation marks. Do not include the root subproject in the parameter.


/is (for stcmd mrg)
/is

Includes all the subprojects which are children of the subproject specified with the /s option.

Without the /is option, StarTeam branches only the specified subproject.


/is (for stcmd)
/is

Includes one of the following:

•	All the subprojects which are children of the subproject specified with the /s option

•	All the subprojects in the project when the /s option is not used

Without the /is option, the files are assumed to be in or intended for only the specified subproject or the project root directory.


/un (for stcmd)
/un

Provides the name of the user performing the action in double quotation marks. Without this option, the current network logon name is used.


/pw (for stcmd)
/pw

Provides the password for the user specified with the /un option. This option is required only when project security is enabled and the password is not blank.


/q (for stcmd)
/q

Suppresses progress reporting. Without this option, messages about each action appear on the screen as the action is performed.


/x (for stcmd)
/x

Bypasses error messages. Without this option, you will have to confirm error messages.


/l (for stcmd add)
/l

Locks the files (or keeps them locked) after this action is performed. The locker is the user specified with the /un option. When neither /l nor /u is specified, Versions locks the file.


/u (for stcmd add)
/u

Unlocks the files (or leaves them unlocked) after this action is performed. When neither /l nor /u is specified, Versions locks the file.


/l (for stcmd ci and co)
/l

Locks the files (or keeps them locked) after this action is performed. The locker is the user specified with the /un option. When neither /l nor /u is specified, Versions leaves the lock status of each file as it was before the command was executed.


/u (for stcmd ci and co)
/u

Unlocks the files (or leaves them unlocked) after this action is performed. When neither /l nor /u is specified, Versions leaves the lock status of each file as it was before the command was executed.


/l (for stcmd lck command)
/l

Locks the files.


/u (for stcmd lck command)
/u

Unlocks the files.


/c (for stcmd cmp)
/c

Compresses the files.


/dc (for stcmd cmp)
/dc

Decompresses the files.


/d (for stcmd add)
/d

Changes the description for the specified files to the specified description. The description is enclosed in double quotation marks. Without this option, an error message occurs.


/d (for stcmd dsc)
/d

Provides a description for the files being added. The description is enclosed in double quotation marks. Without this option, no description is provided for the files.


/vl (for stcmd ci)
/vl

Provides a version label. The label is enclosed in double quotation marks.
When adding or checking in files, this label becomes the label for the versions of the files. Without this option, the versions are added to the project or checked in without labels.


/vl (for stcmd dms)
/vl

Provides a build label. The label is enclosed in double quotation marks.
The label is used to identify the file versions to be included in the milestone. Without this option or /vd, the most recent version of the file is included.


/vl (for stcmd co)
/vl

Provides a version label. The label is enclosed in double quotation marks.
The label is used to identify the versions to be checked out. Without this option or /vn or /vd, the most recent version of the file is checked out.


/vl (for stcmd prm)
/vl

Provides a version label. The label is enclosed in double quotation marks.
The label is used to identify the versions to be made permanent. Without this option or /vn or /vd, the most recent version of the file is made permanent.


/vl (for stcmd dvr)
/vl

Provides a version label. The label is enclosed in double quotation marks.
The label is used to identify the versions to be deleted. Without this option or /vn, the most recent version of the file is deleted.


/k (for stcmd add and ci)
/k

Makes the version being added or checked in a permanent version. Without this option, the version is non-permanent.


/k (for stcmd prm)
/k

Makes the specified versions permanent versions. Without this option, the version becomes non-permanent.


/md (for stcmd add)
/md

Specifies the maximum number of versions to be stored for the files using delta storage. Without this option, the maximum number is 32,767.


/mo (for stcmd add)
/mo

Specifies the maximum number of versions to be stored for the files using omega storage. Without this option, the maximum number is 10.


/md (for stcmd mnv)
/md

Specifies the maximum number of versions to be stored for the files using delta storage. Either /mo or /md must be used.


/mo (for stcmd mnv)
/mo

Specifies the maximum number of versions to be stored for the files using omega storage. Either /mo or /md must be used.


/nl (for stcmd dbd and dms)
/nl

Specifies the build label for stcmd dbd or the milestone label for stcmd dms. The label is enclosed in double quotation marks. This option is required.


/fo (for stcmd add and ci)
/fo

Forces text files to be stored using omega storage. Without this option, delta storage is used for text files. (Binary files are always stored using omega storage, regardless of this option.) Once a text file has been stored using omega storage, it will always be stored using omega storage.


/f NCI (for stcmd ci)
/f NCI

Specifies the check in of all the files that need to be checked in (i.e., all the files that match the “Files to Check In” filter. When you use this option, any file specifications at the end of the command are ignored. When neither /f NCI nor Files... is used, the default is *.*


/f NCO (for stcmd co)
/f NCO

Specifies the check out of all the files that need to be checked out (i.e., all the files that match the “Files to Check Out” filter). When you use this option, any file specifications at the end of the command are ignored. When neither /f NCO nor Files... is used, the default is *.*.


/o (for stcmd ci)
/o

When checking in files, allows you to check in files that are identical to the most recently checked in versions.


/o (for stcmd co)
/o

When checking out files, forces the check out when the working file appears to be more recent.
Without this option, either of these cases produces an error, and the files in question are not processed.


/o (for stcmd dvr)
/o

Forces the specified versions to be deleted even if they are permanent.
 Without this option, only nonpermanent versions are deleted.


/r (for stcmd ci)
/r

Provides a reason for checking in the files. The reason is enclosed in double quotation marks. Without this option, no reason is stored for the checked-in versions.


/vn (for stcmd co)
/vn

Specifies the version number to be checked out or made permanent for each of the files specified by this command. Without this option or /vl or /vd, the most recent version of the file is checked out.


/vn (for stcmd prm)
/vn

Specifies the version number to be checked out or made permanent for each of the files specified by this command. Without this option or /vl or /vd, the most recent version of the file is made permanent.


/vn (for stcmd dvr)
/vn

Specifies the version number to be deleted for each of the files specified by this command. Without this option or /vl, the most recent version of the file is deleted.


/vd (for stcmd co)
/vd

Specifies a date and optionally a time to be used to identify the versions of the specified files that are to be checked out. The last version checked in before the specified date is the version used for each file.
The date can be specified as mm/dd/yy or mm/dd/yyyy. The time can be specified in hours; hours and minutes; or hours, minutes, and seconds (separated by colons). The syntax for the time is:  [hh [:mm [:ss]]]
When specifying a time along with the date, they must be separated by a space and within double quotation marks, for example, “11/13/96 12:01:01”.
Without this option or /vl or /vn, the most recent version of the file is checked out or made permanent.


/vd (for stcmd prm)
/vd

Specifies a date and optionally a time to be used to identify the versions of the specified files that are to be made permanent. The last version checked in before the specified date is the version used for each file.
The date can be specified as mm/dd/yy or mm/dd/yyyy. The time can be specified in hours; hours and minutes; or hours, minutes, and seconds (separated by colons). The syntax for the time is:  [hh [:mm [:ss]]]
When specifying a time along with the date, they must be separated by a space and within double quotation marks, for example, “11/13/96 12:01:01”.
Without this option or /vl or /vn, the most recent version of the file is checked out or made permanent.


/vd (for stcmd dms)
/vd

Specifies a date and optionally a time to be used to identify the versions of the files to be included in the milestone. The last version checked in before the specified date is the version used for each file.
The date can be specified as mm/dd/yy or mm/dd/yyyy. The time can be specified in hours; hours and minutes; or hours, minutes, and seconds (separated by colons). The syntax for the time is:  [hh [:mm [:ss]]]
When specifying a time along with the date, they must be separated by a space and within double quotation marks, for example, “11/13/96 12:01:01”.
Without this option or /vl, the most recent version of each file is included.


/vd (for stcmd dbd)
/vd

Specifies a date and optionally a time to be used to identify the versions of the specified files to be included in the build. The last version checked in before the specified date is the version used for each file.
The date can be specified as mm/dd/yy or mm/dd/yyyy. The time can be specified in hours; hours and minutes; or hours, minutes, and seconds (separated by colons). The syntax for the time is:  [hh [:mm [:ss]]]
When specifying a time along with the date, they must be separated by a space and within double quotation marks, for example, “11/13/96 12:01:01”.
Without this option, the most recent version of each file is included.


/ts (for stcmd co)
/ts

Sets each working file’s time stamp to the check-out time. Without this option, the time stamp is the same as for the checked in version that is being copied to the working directory.


/ro (for stcmd add, ci, co, and lck)
/ro

Used with /u to make the unlocked working file read-only after this operation is completed. Without this option, the file is read/write. Use /ro to make it less likely that you will edit a file that is not locked by you.


files...

Specifies the files to be used in the command by name or by file specification (such as *.c). Without this option, the default is *.*. This must always be the last parameter. Any parameters following it are ignored. Files specifications that have embedded spaces should be in quotation marks.


 vault

A directory where versions of the files that are under version control are stored. This directory’s name ends with a .vlt extension and is a subdirectory of the directory where the project database file (.stp) is stored.


 vault file

A file in the project vault that stores versions of a project file.


 version control

Version control is the process of storing and tracking the various changes (versions or revisions) to one or more files. A version control system maintains the version history generated as the files evolve into their final forms.

The main advantage of using an automated version control system is fast, easy recall of previous versions. If you are on a network, Versions also provides a quick, easy-to-use method of obtaining versions of files being generated and maintained by other users working on a project with you.


 project database file

Also referred to as the project file. The database file, designated during the creation of a project, that stores defect information, topics and responses, and other project information. By default, it ends with an .stp extension. See also (but do not confuse with) project file.


 project file

A file under version control; therefore, a file that is in a Versions project. See also (but do not confuse with) project database file.


 administrator

A functional role in the operation of Versions. To become a project administrator, you must create the project, import the project, or have another administrator change your user properties to designate you as an administrator.
When project security is enabled, only project administrators can create or branch subprojects, change project properties, break locks, manage team member information, modify the number of versions for a file, designate or delete permanent versions, purge non-permanent versions, designate builds and milestones, and perform delete operations.