Source control command line reference

Engineering Workflow Management source control includes a command line interface that provides flexible, scriptable access to essential Engineering Workflow Management source control operations from any command shell.

Engineering Workflow Management source control command line tools are installed in JazzInstallDir/scmtools/eclipse, where JazzInstallDir is the folder in which Engineering Workflow Management is installed (for example, C:\Program Files\IBM\TeamConcert on Windows). To use these tools from a command shell on Windows, the UNIX System, or Linux®, set your PATH environment variable to include this directory.
Note: On some hosts running the UNIX System or Linux, you must also add the Eclipse Java™ runtime environment to the system's LD_LIBRARY_PATH environment variable. Run a command line of the form:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:JazzInstallDir/jdk/jre/bin
before you start using scm subcommands, or embed the command in a shell startup script.
Note: For improved performance, you can run the command line using lscm.bat or lscm. This lightweight command line version creates a daemon process on your machine that reduces the startup time and improves the execution time for most commands. You might need to replace the JAVA variable in these scripts to point towards the java that you run on your machine. You can also launch a daemon process manually by running the scm daemon start. For more information, see daemon_start.html
License note: To perform the task described here, you must be assigned the Developer Client Access License.

Command syntax

The reference page for each scm subcommand provides a synopsis of command syntax using the following conventions. Options that have alternate forms are delimited by brackets. For example:

-P  |  --password ] 
indicates that you can type either -P or --password for this option. Optional options are delimited by braces. For example:
scm load [-r/--repository-uri arg] [-d/--directory arg]  [-q/--quiet] [--all] [-f/--force] [-i/--include-root] [-R/--remote-rules arg] [-L/--local-rules arg] [-t/--target arg] [-a/--alternative-name arg] workspace [remote-path...]
indicates that for the scm load subcommand, you must specify the repository workspace to load. All other options are optional. If you do not specify which components to load, all components are loaded by default.

Commands take the general form:

scm [options] [subcommand [subcommand options]]

Quoting and other shell conventions

When arguments to scm subcommand options contain spaces, they must be quoted. Shell wildcards are permitted where applicable (specifying files to check in, for example).

Creating and storing login credentials

While many of the scm subcommands have options that support a one-time connection to a repository, it is generally more convenient to use the scm login command to store a repository URI and credentials, which can then be used by other scm commands. Credentials stored in this manner are difficult, but not impossible, to discover. You can remove stored credentials with the scm logout command.

Sandboxes and scm subcommands

The scm load and scm share commands create a sandbox for use by Engineering Workflow Management source control command line tools. You can run Engineering Workflow Management source control command line tools in a sandbox or specify it using the -d option, which is common to all scm subcommands that require a sandbox context. If you are running the subcommand in a sandbox, you do not need to specify -d.

These subcommands do not allow you to specify a repository URI on the command line. Instead, they derive it from metadata associated with the sandbox in which you are running the command (or which you have specified using -d). If you have used scm login to store credentials for this repository, the subcommand does not prompt for them.

Do not use Engineering Workflow Management source control command line tools to work in an Eclipse workspace.

UUIDs and aliases

Many scm subcommands take an argument that refers to a repository object. These references can take the form of a name (such as the name of a sandbox), a UUID ( a unique identifier assigned to each repository object), or an alias. Aliases are short strings of digits that you can use to refer to repository objects wherever such references are accepted by an scm subcommand. The scm command automatically creates these aliases whenever you run a subcommand that returns the name or UUID of a repository object. To use them, you must type the entire alias (they are not integers, so you must include leading zeroes when they are present). Aliases are unique to a sandbox. You cannot share them with other team members. You cannot list them. They are not persistent over long spans of time (any alias can be re-used to refer to another object after the set of unused aliases has been exhausted).

You can also show/hide aliases and UUIDs by passing -a yes/no and -u yes/no to scm. For example, scm -a y -u y list ws ... shows the alias/UUID of all sandboxes. Substituting -a n shows just the UUIDs, and -a n -y n shows neither.

Examples presented in scm subcommand reference pages display and use aliases where appropriate.

Status flags

Several scm subcommands display the status of files and folders using the characters shown in Table 1.
Table 1. SCM status flags
Flag Status
* The change set is current
@ The change set is active
# The incoming resource conflicts with the version of the resource in the sandbox
! The incoming resource has a potential conflict with the resource in the sandbox
$ The change set is completed
a The resource has been added
c The content of a file has been modified.
p The properties of a file have been modified, or the properties of a directory have changed.
d The resource has been deleted.
m The resource has been renamed or moved.
A The change can be automatically merged.
C Manually merge the conflict.
I Apply other dependent changes or conflicts.
G There is a gap related to this change.
M A new (merged) change set that is created in a merge gap scenario.
S The original (source) change set that is accepted at the start of a merge gap scenario.
l The incoming and outgoing change sets are linked.
> The current port target. All of the changes being ported are targeted for this change set.
Status flags are combined where appropriate. For example:
C:\local-workspaces\HelloJazz> lscm show status
(1009) --#@ nobody 32424 "degauss the flux capacitor" - "most recent changes"
indicates that the change set with alias 1009 is active (@) and has a conflict (#).