Table of Contents


wco - check out (update, get) SnapshotCM files into a local workspace


wco [-BdEflLMnOpqRTuUvVWX] [-i{unix|win|mac}] [-jpatternList] [-kkv|-kk|-kv|-ko] [-o/Path] [-rRev | -cDate] [-tLockComment] [-NWorkspaceName] [-hHost -SSnapshot [-DDir]] name ...


wco checks out or updates files and directories from a SnapshotCM snapshot into a workspace and optionally locks files against simultaneous edits.

Files and directories are stored in a workspace with the same paths as in the snapshot.

Unless overridden by an option, the revision retrieved will be the revision current in the snapshot.

The local file read and execute modes will be set to match those of the archive file. The owner write permission will also be turned on if either the -l or -W options are specified. If an existing local file has write permission, the check out will be aborted, unless -f is specified. If the existing local file does not have write permission or -f is specified, the local file will be overwritten.

Files and directories will only be checked out if they don't exist in the local workspace or are not up-to-date with the revision currently referenced by the mapped snapshot. You can force a check out and compare of file content by using the -f option, but the file will be updated only if different.

If file is a directory, then all the files in the archive directory which are out-of-date or do not currently exist in the local directory are retrieved.

Workspace Mapping

SnapshotCM workspace operations need to know the snapshot and workspace to use, and the paths of the items on which to operate. The workspace and snapshot are typically related by a pre-established mapping (see wmap(1) ), which also relates local file paths and snapshot file paths. As a result, SnapshotCM simply needs to know the mapping and one of the file paths (either local or snapshot) in order to fully determine which objects to operate on.

Values of file are interpreted consistently by all SnapshotCM commands. Several scenarios are possible and are described in detail below. The high-level summary is that file is first treated as a local path and a workspace mapping is searched for in the user's workspace mappings. If there is no match, and file was given as a full path, it is treated as a full snapshot file path.

Relative Path
File is expanded to a full path, and the workspace mapping table is searched for a workspace which contains this full local path name. If found, the full path is used as the local file path. Otherwise, the mapping fails.

Full Path
The workspace mapping table is searched for the workspace which contains file. If found, file is used as the local file path. Otherwise, the current directory is searched in the workspace mapping table for a mapping and file is assumed to be a snapshot file path. If the current directory is not within a workspace, the mapping fails.

Explicit Workspace + Full Path
If file lies within the given workspace, it is used as the local file path. Otherwise, it is used as the snapshot file path.

Explicit Workspace + Relative Path
File is expanded to a full path, and if it lies within the given workspace, it is used as the local file path. Otherwise, the mapping fails.

Default Options

Default options are read and parsed from the file specified in the $SNAPSHOTCM_RC environment variable, if defined, or from $HOME/.snapshotcmrc on unix or %HOMEDRIVE%%HOMEPATH%\.snapshotcmrc on Windows if it exists. Default options are parsed before command options and are overridden by command line options.

Default options are specified by giving a sample command line containing just the command name and default options. For example, to eliminate lock comment prompting from wco(1) , wset(1) and wci(1) , add the following lines to the default options file:

wco -t ""
wset -t ""
wci -t ""

Workspace Options

The workspace mapping is automatically looked up in the user's workspace mapping table for the given files. Override this by specifying an explicit workspace:
Use the named workspace mapping.

Or override with a temporary workspace mapping with these three options:

Use the SnapshotCM server on Host for a workspace mapping.
Use SnapshotPath for a workspace mapping.
The local destination directory for a workspace mapping. This can be a relative or absolute path. If this option is not provided with the other two, the local destination directory defaults to the current directory where the command is executed.

For more information on workspace mappings, see wmap(1) .


Set file I/O mode to 'binary'. This allows you to override the default setting of I/O mode for this check out. (Also see -T option.)
Get the contents as of Date. If multiple branches exist as of Date, only those revisions which are ancestors of the current snapshot revision will be searched. Revisions from branches not merged into the current revision will be ignored. Date is interpreted in the local time zone.

Date consists of a year, month, and day optionally followed by a time specification [hh[:mm[:ss]]]. Omitted time values default to 0. The year, month and day can be in any of the formats illustrated: 1999/04/16, 16Apr00, April 16, 2001, Apr. 16, 2002, 2003. In all formats, the year can be 2 digits (interpreted in the range 1970-2069) or 4 digits.

Operate only on directories. This is a quick way to check out the snapshot directory structure into your local workspace without checking out all the files.
Operate only on existing local files. This is a quick way to update the file contents to the latest revision for files you already have checked out into your workspace.
Force the operation. This allows you to overwrite locally writable files. It also allows you to force a file content compare to verify that the content is up-to-date.
Set the format for writing 'text' (I/O mode) files. Use to override the workspace setting for this check out. (Also, see the -T option.) SnapshotCM supports 3 formats:
unix format: '\n' separated lines.
win format: '\r\n' separated lines.
mac format: '\r' separated lines.
List only files whose name (or path) matches patternList. PatternList consists of one or more patterns separated by a '|' (pipe/or) symbol. Each pattern can contain shell wild cards as follows:

* - match 0 or more characters
? - match any one character
[set] - match any character in set
[!set] - match any character not in set

A pattern not ending in a slash ('/') matches only files. A pattern ending in a slash matches only directories. A pattern containing a slash other than at the end is matched against the full workspace path. Otherwise pattern is matched against the last component of the path. If patternList begins with an '!' (exclamation/bang) character, the normal selection is negated.

Set keyword expansion to 'keyword and value'. Replace any keyword strings with a string containing both the keyword and current value string for the keyword.
Set keyword expansion to 'keyword'. Replace any expanded keyword strings with the original keyword-only string.
Set keyword expansion to 'value'. Replace any keyword strings with the value string. Does not retain the keyword in the string. This is effectively a one-time keyword expansion and if checked in, there will be no reference to the keyword for future expansions.
Set keyword expansion to 'off'. Unexpanded keywords and old keyword expansions will be left unmodified.

If no keyword option is given, keyword expansion occurs according to the keyword expansion mode of each file.

Lock the file on check out.
Operate only on locally locked files. To discard changes since the lock, combine with the -f option.
Print workspace mapping before normal output.
No Execute mode. Show the operations that would happen, but do not really execute them.
Map /Path in the selected snapshot to the specified (-D) local directory, creating a temporary, partial workspace mapping for the command. Normally, the root directory of a snapshot is what is mapped.
Write file contents to 'stdout'. Useful for directing the file contents to a 'stdout' shell pipe feeding directly into another command. This also allows you to check out files without having a local workspace mapped. You can redirect 'stdout' to any local file.
Quiet mode. Do not display status text showing the check out operations being done.
Check out file contents for the revision Rev. Rev can be a file revision number, or can be a full or relative snapshot path. If a snapshot path, the revision referenced by the snapshot will be checked out.
Operate recursively. Recursively traverse all subdirectories and perform the requested operations on all files and directories in each subdirectory.
Set the lock comment to this string. If omitted during a lock, the comment will be prompted for interactively.
Set file I/O mode to 'text'. This allows you to override the default setting of I/O mode for this check out. (Also, see the -B and -i options.)
Unlock and discard any changes. This can be useful to ignore changes to a file and unlock it.
Enable access to recoverable (deleted) files.
Display file revision info during check out.
Print internal version and exit.
Mark the local file writable after check out.
Display 'full archive path' names.


Exit status is 0 if all specified files were successfully checked out or currently up-to-date or ignored, 1 if a file could not be checked out, and >1 if there was a bad option or a network error.


Assume we have created a workspace named "TestWork":

   wmap add -N TestWork -h archiveHost \

   -S /TestProject/TP1.0 -D $HOME/workspace

To check out the latest revisions of all the files below /TestArchive in the snapshot's archive hierarchy, enter the command

   wco -N TestWork -R /TestArchive

To check out a manual page to 'stdout' and format and print it, enter the command

   wco -h archiveHost -S /TestProject/TP1.0 \

   -p /TestArchive/man/doc.1 | nroff -man | lp

See Also

wci(1) , wdiff(1) , whist(1) , wls(1) , wmap(1) , wmerge(1) , wremove(1) , wrename(1) , wset(1) , wupdate(1) .

Table of Contents