The checkout command co.

over 4 years ago

The syntax for this command is:

stcmd{Ex} co  [–epwdfile “passwordfilepath”] [-p "userName:password@hostName:endpoint/projectName/[viewName/][folderHierarchy/]"] | [-s "userName:password@hostName:endpoint] [-cmp] [-encrypt RC4, RC2_ECB, RC2_CBC, RC2_CFB] [-cacheAgentThreads number] [—useMPXCacheAgent | -useCA host:port | autolocate]] ] [-cfgl "label" | -cfgp "promotion state" | -cfgd "date"] [-is] [-iip] [-pattern "datepattern" [-locale country code]] [-rp "directory" | -fp "directory"] [-frp] [-filter "filter"] [-o] [-e] [-l | -u | -nel] [-break] [-ro | -rw]] [-vl "name" [-attached] | -vd "date" | -vn number | -vp "name"] [-cp "name"] [-exclude <pattern> | #<pattern file>] [-cwf] [-f NCO | NCD] [-ts] [-eol [ on | off | cr | lf | crlf | platform]] [-fs] [-q | -vb | -pf "filterName"] [-cr | -req | -task ] processItemPath] [-uv] [-ofp "resultsOutputFilePath] [-fileid fileviewmemberid [-filedot filedotnotation]] [files...]


Use the checkout command "co" to check out files from a StarTeam repository (or vault) to your working folder via the command line. 

Note: The functionality of the bulk checkout utility (BCO) has been fully subsumed into co

Parameter Descriptions

-attached May be specified, but only in conjunction with -vl "label name". When -vl is
specified, and if -attached is also specified, then only those files which are attached
to the label (identified by -vl) will be checked out, and specifically at the tip revision.
If -attached is not specified, its default value is always false.
-attached used in conjunction with -vl "label name" alters the fundamental
behavior of the co command.
If -attached is false (the default), the files to be checked out are identified by the file(s)
pattern specified by the co command, -vl specifies the revisions of the subset of files
attached to the label.

-break Breaks the current lock by another user if you have the access rights to break locks.

-iip Ignore invalid path. If specified, and if the -p folder path is invalid, then exit quietly and successfully without throwing an exception.

-cr, -req, -task Complete path from the project view's root folder to the change request, requirement, or
task number to be used as a process item. Use the forward slash (/) as a delimiter
between folder names.
For out-of-view process items, specify the project name and view name in front of the
complete folder path. For example:
-cr MyProject/RootView/RootFolder/SourceCode/37
This specifies change request 37 in the SourceCode folder (under the root folder) of
the ChildView view in the MyProject project.
Note: For in-view process items, as long as the change request, requirement, or
task numbers are the unique primary descriptors of their types (true by default), it
is sufficient simply to specify the number, with no path. The project and view
names are assumed from -p.
If a process item is specified, then the files being checked in are attached to the process
item and follow the project process rules.

-cr, -req or -task are mutually exclusive. If any one of them is specified, -filter/-
f are ignored.

-cp Name of the code page used for localization and internationalization of the content, file
and folder names, keyword expansion, etc. Supported code page names are US-ASCII
(the default), UTF-8, UTF-16, windows-1252, ISO-8859-1, ISO-8859-9, ISO-8859-15,
windows-31j, EUC-JP, Shift_JIS, ISO-2022-JP, x-mswin-936, GB18030, x-EUC-CN, GBK.

-cfgd Configures the view as of the specified date/time. Examples include:
"12/29/13 10:52 AM"
"December 29, 2013 10:52:00 AM PST"
"Monday, December 29, 2013 10:52:00 AM PST"
-cfgl Configures the view using the specified label. Without -cfgl, -cfgp, or -cfgd, the
view’s current configuration is used.
-cfgp Configures the view using the specified promotion state.

-cwf Create working folders from StarTeam folders, even if they do not contain any files. This
is supported for compatibility with bulk check out.
Note: -cwf will only create the working folder for the specified folder. Use -is
with -cwf to create working folders for all child folders.

-eol Automatically convert end-of-line markers. Use [cr|lf|crlf|off|platform].
When on, text files are transferred from the StarTeam Server’s repository to the
workstation’s working folder with the end-of-line convention for the platform executing
the command as determined by the Java VM.
When off, the default, no end-of-line conversion is performed. Using off is the same as
not using -eol at all.
For Microsoft Windows clients, the end-of-line marker is a carriage return/line feed
(crlf) combination. For UNIX platforms, it is a line feed (lf). For MAC systems, a
carriage return (cr).
You would set this option to on or lf, for example, when you compare a file from the
repository and a working file on a UNIX system (if the repository stores text files as
Note: If a file has a fixed EOL value set in StarTeam, then cr, lf and crlf are
all ignored, and the file is always checked out using the set (fixed) eol value. To
override this behavior, pick -eol platform.
Note: When -eol platform is selected, then all files are checked out using the
platform specific eol, whether or not they are marked fixed for a different

-exclude <pattern> | #<patternFile>
Exclude files or folders whose names match a pattern (or set of patterns). This is
supported for compatibility with bulk check out. You can either specify the pattern inline
-exclude <pattern> or you can specify a set of patterns in a file -exclude#patternFile.
A pattern can be an exact file or folder name or it may contain wildcard characters (e.g.,
To specify a folder name, precede the pattern name with a forward-slash (e.g., '/
bin'). A single pattern can be provided with -exclude. Alternatively, one or more
patterns can be specified on separate lines of the given <pattern file> (prefixed
with # ).
Pattern file names may be fully qualified with their path on the file system, e.g. #"c:
\temp\patternfile.txt" or relative to the current folder e.g.
In either case, pattern file names must be enclosed in double quotation marks. "…"
If the pattern matches a folder path, then all files in that folder path will be excluded.
Finally, a pattern may also be a fully or partially qualified path to a file in StarTeam
without wildcards, e.g. /StarDraw/External Resources/StarDraw.ico
If the pattern matches an exact file name, then all instance of that file name, no matter
where they are in the folder tree, will be excluded.
In this case, only the file that exactly matches the parent folder path will be excluded.
Note: To exclude a folder tree containing files and sub-folders, append /* to the
'root' of the tree. For example, if your folder tree is /StarDraw/External
resource/Documentation, and you want to exclude the tree rooted at
'External resource', specify /External resource/* in the pattern file.

-f NCD Specifies the check-out of any file whose status is Missing or Out of Date and the
deletion of all not-in-view files in the workspace. NCD stands for "needs check-out and
-f NCD is ignored if -filter is used.
Note: -f NCD and -f NCO are mutually exclusive.

-f NCO Specifies the check-out of any file whose status is Missing or Out of Date. NCO
stands for “needs check-out.” No other files are selected for check-out.
-f NCO is ignored if -filter is used.
Note: -f NCO and -f NCD are mutually exclusive.

-filter Specifies a string of one or more characters, each of which represents a file status.
Never include spaces or other white space in this string. Only files that currently have
the specified status(es) will be actioned. Does not apply to files that are Not In View.
• C = Current
• M = Modified
• O = Out of date
• N = Not In View
• I = Missing
• G = Merge
• U = Unknown
For example, using CM applies a command only to files with a status of Current or Modified.
-filter also takes precedence over -f NCO. If you use G, M, or U, you must also
specify -o to force the checkout operation. Otherwise, the G, M, or U is ignored.

-frp Forces the specified relative path. When used, the -frp parameter ensures that the
entire folder tree is successfully checked out relative to the root folder, either with the
default or via the -rp root path override.
For example, if the default root folder path is c:\stardraw, then the command co -p
"Administrator:Adiministrator@localhost:49201"/StarDraw -is -frp
checks out the entire folder tree recursively to c:\stardraw.
If the path is overridden using the -rp command, such as co -p
"Administrator:Adiministrator@localhost:49201"/StarDraw -is -rp
"c:\temp" -frp, the entire stardraw folder tree gets checked out to c:\temp.
-frp does nothing if the entire folder tree is already relative to the root folder.
However, consider the StarDraw example. If the sub-folder Source Code default path
is set to a mapped drive on a machine, for example, e:\\StarDraw or a UNC path (\
\MicroFocus Build Server\) and you run the command line on a different
machine from where the mapped drive or the UNC path is unreachable, the co
command without -frp will throw an exception.
With -frp, the command will succeed, the Source Code folder and all descendant
sub-folders are created relative to its parent, and the files in the folder hierarchy are
checked out.

-fs Prevents file statuses from being remembered after the check-out occurs. Subsequent
status values for these files will be incorrect and indeterminate. Use this option where a
file’s status is irrelevant. For example, if you routinely delete the working folders before
checking out files for a build, there are no files and their statuses do not matter.
Additionally, with per folder status repository in use on the local machine, if files are
checked out to empty working folders, empty .sbas folders will not be left on disk.
Be aware that the file statuses may never be known, even if you use the updatestatus
command later. You can do a force check out without the -fs option to obtain
current files with correct statuses.

-i Interactively prompts user to confirm check-in or check-out (depending on command used) when file
status is Merge, Out of Date, or Unknown. The user can ignore the file. Not valid in automated backoffice environments. Not supported with stcmdEx

-l Locks the item(s). This is the default when -l, -nel or -u are not used.
-nel Non-exclusively locks the file after it has been checked out.

-o Forces a check-in/check-out depending on which command is used. -o is supported
with -filter and -f NCD, but not with -f NCO.

-e If specified, -e throws an exception if -filter includes M, G, or U and any of the
identified file statuses match Merge, Modified, or Unknown. The thrown exception will
prevent all other files from being checked out as well.

-pattern Qualifies the datetime. It can be specified wherever a date-time is specified, such as -
cfgd, -vd, etc. The pattern must match any valid pattern supported by the java JDK in
java.text.SimpleDateFormat.applyLocalizedPattern(String). The
pattern may be localized.
For every command that takes a -pattern parameter, a -locale countryCode parameter is
optionally available. This is the "two character country code".


use,hh:mm:ss in German, or hh:mm:ss in English for the Date/Time Format Pattern, depending upon your platform & locale.

-ro Makes the working file read-only after this operation. Without this option, the file remains
as it was prior to the operation. Usually, you use -ro to prevent yourself from editing a
file that is not locked by you. -ro must be used with -l or-u or -nel. If you use -ro,
you cannot use -rw.

-rw Makes the working file read-write after this operation. Without this option, the file
remains as it was prior to the operation. -rw must be used with -l or -u or -nel. If you
use -rw, you cannot use -ro.

-ts Sets each working file’s time stamp to the check-out time. Without this option, the file is
given the same time stamp as the checked-in revision of the file.

-u Unlocks an item.

-vb Verbose mode kept for backward compatibility with bulk check out. If -vb is specified,
the list of all files considered for checkout is returned with the per file number of bytes
checked out, the time taken for the checkout, and whether a specified cache agent could
be leveraged to check the content out. In addition, if the file was not current prior to the
checkout, the file status on disk is also recorded.

-vd Specifies the as-of date/time used to identify the revisions to be checked out. The last
revision before the specified date/time is the one checked out for each file. See the date/
time examples for -cfgd.
-vl Specifies the revision or view label used to identify the revisions to be checked out.
Without the-vn or -vd or -vl option, the tip revision of each file is checked out.
-vn Specifies the revision number
-vp Specifies the promotion state.

Note the fundamental difference between -vX and -cfgX. The -cfgX set of parameters open a view configuration based on a time associated with X.

So -cfgl opens a configuration based on the label time, and the checkout command checks out all the files in the view at that time. (a rolled back snapshot)

On the other hand, -vl checks out exactly and only the set of files attached to the label at the revisions they are attached (unless -attached is specified, in which case, it checks out the tips)

-uv If this parameter is specified, then only user-visible folders on the local client machine
(set via the StarTeam Cross-Platform Client) will be checked out.


-fileid If this parameter is specified then the file with the specific viewmeberid will be checked out directly to the path specified by -fp or -rp.  Note that in this case, the actual folder tree path in the StarTeam folder hierarchy is ignored.

-filedot If this parameter is optionally specified (concomitant to -fileid being specified) then the file revision associated with the historical dot notation will be checked out from history.

The following example uses co to lock and check out .doc files from User Manual, a child of the root
folder StarDraw (in the StarDraw view of the StarDraw project):
stcmd co -p "JMarsh:password@Orion:1024/StarDraw/StarDraw/User Manual" -l "*.doc"
The next example uses co to merge a readme file:
stcmd co -p "NTesla:@" -encrypt RC4 -fp "/export/home0/johnson/working" -merge "README"
Either use the -p with co (as above) or the stateful connect and set commands (below) to set the
context of the project/view/parent folder:

stmcd connect JMarsh:password@Orion:1024
stcmd set project = StarDraw view = StarDraw folderHierarchy = " StarDraw/User Manual"
stcmd co -l "*.doc"
stcmd disconnect

The next example uses stcmd co to checkout all files, recurse through the entire folder tree (-is) and
return (for the set of checked out files) the set of all property values described by the property filter -pf:
stcmd co -p " JMarsh:password@Orion:1024 /StarDraw" -is -pf \"<All Files By Status>\"
This example checks out files from a historical point in time, rolled back to a view configuration based on
the label label abc:
stcmd co -p "JMarsh:password@Orion:1024 /StarDraw" -cfgl "label abc" -is -pattern "yyyy/MM/dd" -locale en -pf \"<All Files By Status>\"


This example checks out a single file content by viewmemberid 12345 to the explicit folder specified by -rp. The content is rolled back to the revision at dotnotation 1.4

stcmd co -p "JMarsh:password@Orion:1024 /StarDraw" -rp "c:\temp\" -fileid 12345 -fieldot "1.4"

The checkout command "co" is the heart of the StarTeam Jenkins plugin.


Support Tip
Comment List
Related Discussions