A Rational Team Concert command-line reference for software developers

Mark Roberts explains how to use the command-line interface for Rational Team Concert to automate several operations. He covers typical developer, integrator, and configuration manager activities, so this article provides a useful guide to the most common aspects of the command-line interface. It will help those who are new to Rational Team Concert and those who want to develop their skills further.

Share:

Mark Roberts (markroberts@uk.ibm.com), Certified IT Specialist, IBM

Author1 photoMark has more than 20 years experience of software development and the management of IT systems and configuration management environments. He has written software in Fortran, C, assembler, Java, and Perl and has extensive experience in the deployment of Rational ClearCase, Rational ClearQuest, and Rational Team Concert. As a member of the UK technical professionals team, he focuses on helping customers improve the configuration and change management aspects of their development processes.



15 January 2013

Introduction

IBM® Rational Team Concert™ software provides change, configuration, build management, and project planning in a highly efficient and capable graphical user interface. Most users choose the web interface, rather than the Eclipse interface because it is easy to use, the installation footprint is zero, and the connectivity to other elements of the Rational software solution for requirements management, design management, and test management. Many developers also use the software configuration management capabilities of Rational Team Concert that are integrated into Eclipse, or Eclipse-based products (such as IBM® Rational® Application Developer), and the Microsoft Visual Studio .NET development environment.

This guide explains a supporting user interface for Rational Team Concert that is accessible from the command line. The command-line interface (CLI) provides access to a rich set of capabilities for the source code management (SCM) aspects of Rational Team Concert. Many users are already familiar with the command-line interfaces for products such as Rational® ClearCase® or CVS, for which the command line is often used to produce scripts that contain sequences of commands that are performed repeatedly.

The first section investigates the most common commands that a developer uses when first starting to use the command-line interface. This covers the login process, creating a workspace, and loading content. All commands include examples to illustrate specific scenarios. The second section describes the use of commands for more advanced scenarios and some commands that are used only occasionally. The final section shows an example of combining a number of the commands to produce a script that delivers a specific function. The information presented is applicable to both Microsoft Windows and UNIX systems, with occasional differences highlighted where necessary.


Section 1. Common commands

This section describes the most common commands and their results.

Command line interface

Access to the command-line interface is provided by one of two commands that can be considered the interface to the command line. Specific product capability is provided by a subcommand of the interface command. The interface commands are described in the subsections that follow.

SCM executable file

The scm command is in the following default directories of the Rational Team Concert client installation:

  • Windows: TeamConcert\SCMTools\Eclipse\scm.exe
  • UNIX: teamconcert/scmtools/eclipse/scm

The scm command invokes a new command-line process daemon on each invocation. The path indicated above is not added to the system search path during the installation process, so you need to do this manually.

LSCM

The lscm command (lscm.bat on Microsoft Windows systems) is in the same directory as the scm command described previously. The difference between the two is that lscm caches the process daemon, so it operates faster.

It is best to use lscm where possible, which is in most scenarios.

Execution of subcommands

In general, the commands are executed in the following manner:

lscm {options} [subcommands] {subcommand options}

Arguments presented in { } brackets are optional, and arguments presented in [ ] brackets are required for the command to work. Some options are repeatedly used, such as the repository connection and user identification information.

In all examples, the actual text that you must type at the command line is shown in the fixed-width Courier New font:

This is text that the user types at the command line.

Subcommand summary

Table 1 is a summary of the subcommands. Details of frequently used commands and their frequently used arguments and options are displayed in the subsequent sections of this article and in the two subsequent articles in the series. Table 1 indicates which article contains each command.

Table 1. Subcommands with short descriptions
CommandDescription
accept Accept change sets into a remote workspace and download the changes.
annotate Annotates lines of the text file with change history, such as author, time stamp, and comment.
changeaccess Modify the read access permissions for files and folders.
changeset Manipulate change sets (subcommands: associate, comment, complete, current, disassociate, discard, extract, relocate, resume, suspend).
checkin Check changes into the current workspace, add them to the active change set.
compare Compare the contents of workspaces, streams, baselines, or snapshots.
create Create an item (subcommands: baseline, changeset, component, snapshot, workspace)
delete Delete repository items.
deliver Deliver checked-in changes from a remote workspace to another workspace or stream.
diff Show the changes made to a file.
extract Extract a specific version of a file from the repository.
help List available subcommands and provide detailed help on each.
history Show the history for a file or component.
lastmod Return the latest modification time for a folder sub-tree.
list List repository items (subcommands: baselines, changesets, components, credentials, daemons, locks, projectareas, properties, remotefiles, snapshots, states, streams, teamareas, users, workspaces).
load Load a repository workspace onto the local file system.
lock Acquire or release locks in a stream (subcommands: acquire, list, release).
login Store credentials for a repository connection.
logout Delete stored credentials.
property View and update properties on files (Subcommands: get, list, remove, set).
resolve Resolve conflicts.
share Share one or more directories.
snapshot Promote a snapshot from one stream to another. (subcommand: promote).
status Show status and pending changes.
undo Undo changes to files.
version Show versioning information.
workspace Change attributes of a workspace (Subcommands: add-components, change-target, delete, remove-components, replace-components, unload, unset).

User access control

Users are required to log in to the SCM command-line interface with each command. This is necessary to enable Rational Team Concert to maintain a full audit trail of all operations. To make this process easier, it is possible to create a nickname during the login process. It is used to identify the user and the required repository connection during subsequent commands.

Login

This login command uses the arguments shown in Table 2.

Table 2. Login command options
 lscm login [options]
ArgumentDescription
-c [--cache] Cache the password on prompt
-n [--nickname] arg Nickname to identify the repository in future
-P [--password] arg Password for the repository.
-r [--repository-uri] arg URI that specifies the location of repository
-u [--username] arg Username for the repository
lscm login -r https://rational-srv-06:9443/ccm -u mark -n SRV6 -c

This command logs the user in by using the server repository address indicated and the username of mark. The password has not been provided on the command line for the sake of privacy, and the user is prompted to provide it. The password is not displayed onscreen. The combination of repository address, username, and password are cached under the nickname SRV6, which can be used with the –r option on subsequent commands, as indicated in the section that follows.

Logout

To log out of the Rational Team Concert command line, use this command:

lscm logout –r <repository location or nickname>

For example, to log out of the session that was established by using the login command shown previously, you can use either of these commands:

lscm logout –r https://rational-srv-03:9443/ccm

or

lscm logout –r SRV6

Details of frequently used commands

Further details of specific commands that are frequently used are included in this section. Each subsection includes an example and further information about the context, if appropriate. All commands assume that the login command shown previously was used with the nickname SRV6.

create

Create an item specified by a subcommand, as detailed in Table 3.

Table 3. Subcommands for the create command
SubcommandDescription
Baseline Create a baseline in a component
Changeset Create a new change set
Note that this can be done automatically as a result of a checkin operation.
Component Create a new component within the specified workspace or stream
Snapshot Create a new snapshot associated with the workspace or stream
workspace Create a remote repository workspace

To create a new user workspace called MyWorkspace, which will flow changes to the stream called BRM Stream:

lscm create workspace -r SRV6 -d "Command line workspace" --stream "BRM Stream" 
MyWorkspace

Notice that some arguments above have a single hyphen and some have a double hyphen in front of them.

To create a new baseline called Baseline 3 on the Banking component, using the workspace called MRCL, use this command:

lscm create baseline MRCL "Baseline 3" Banking

The newly created baseline then needs to be delivered by using the delivercommand described in a section that follows.

To create a new component called Investment within the context of the project, which will be associated with the BRM Stream, use this command:

lscm create component -r SRV6 Investment "BRM Stream"

Note:
The component name can include spaces if the entire component name is enclosed in quotation marks.

workspace

Change attributes of a workspace by using the subcommands described in Table 4.

Table 4. Subcommands for the workspace command
Sub CommandDescription
add-components Add components to a workspace
Note: Use the load command after this command to actually load content.
change-target Change the flow target of a workspace.
delete Delete a workspace or stream
remove-components Remove components from a workspace
replace-components Replace components from a workspace
unload Unload the workspace, component, or root paths

add-component

To add the component called "C# Samples" to the workspace called MyWorkspace, use this command:

lscm workspace add-components -r SRV6 MyWorkspace "C# Samples"

The display will show the following result:

Following components successfully added: (1017) "C# Samples"

change-target

To change the flow target of a workspace called MRCL to a stream called Integration Stream, which will result in future deliveries being sent to the new target stream:

lscm change-target workspace MRCL "Integration Stream"-r SRV6

The display will show the following result:

Target changed.

load

Load a repository workspace onto the local file system.

On UNIX, to load the configuration of the workspace called MyWorkspace to the MyWorkspace directory in the user's home location:

lscm load -d ~/MyWorkspace -i MyWorkspace -r SRV6

On Windows, to load the configuration of the workspace called MyWorkspace to the c:\workspace directory:

lscm load -d c:\workspace -i MyWorkspace -r SRV6

status

Show the status of the workspace and any pending changes.

The following example shows a workspace in which there are no pending changes:

lscm status

The result of executing this command is shown below:

Workspace: (1006) "BRM Stream Workspace" <-> (1007) "BRM Stream"
  Component: (1008) "Banking Logic" <-> (1007) "BRM Stream"
    Baseline: (1009) 4 "Sprint 1 (Release 1.0)"
  Component: (1010) "Build" <-> (1007) "BRM Stream"
    Baseline: (1011) 2 "Week 1 (Sprint 1, Release 1.0)"
  Component: (1012) "C# UI" <-> (1007) "BRM Stream"
    Baseline: (1013) 4 "Sprint 1 (Release 1.0)"

That information shows that the workspace called BRM Stream Workspace is up to date with respect to the status of the stream called BRM Stream for the Banking logic, Build, and C# UI components. It also shows that the baselines that are referenced for each component.

The status command is frequently used to find pending changes within a workspace. The following example shows a workspace in which several changes have been made. The example shows pending changes that are waiting to be delivered and accepted for the workspace. Outgoing change set 1033 is associated with the task identified by the ID 1317 and the "Update the banking logic code" title:

Workspace: (1006) "BRM Stream Workspace" <-> (1007) "BRM Stream"
  Component: (1008) "Banking Logic" <-> (1007) "BRM Stream"
    Baseline: (1009) 4 "Sprint 1 (Release 1.0)"
    Outgoing:
      Change sets:
        (1033)  *--@  1317 "Update the banking logic code" - <No comment>
    Incoming:
      Change sets:
        (1034)  ---$ Marco 1318 "Extend the transaction processing logic for

The incoming change set shown above is identified as being created by Marco. The change set ID is 1034, which is used to gather information about the change set, such as the content of it. This will be used later in the list command with the changesets subcommand.

Status flags

The change set status flags highlighted in Figure 1 are described in detail in the table in Table 5.

Figure 1. Change set descriptive flags
Display of the status flags for a change set
Table 5. Characters that describe characteristics of the change set.
FlagDescription
* 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 complete.

share

Share one or more directories.

Use this command to share new content into the Rational Team Concert source code management. Do not use this to add individual files and directories. Use the checkin command for that purpose, instead.

The following example shares the content of the c:\Release\Attributes directory into the root of the component called C# Samples, using the MyWorkspace workspace"

lscm share -r SRV6 MyWorkspace "C# Samples" c:\Release\Attributes

The display shows:

Shared successfully.

checkin

This command is used to check in changes made within the current workspace. The checked-in items are added to the active change set. Files to be checked in will appear in the Unresolved section of the report from the status command as shown here:

C:\workspace>lscm status
Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1005) "Build"
    Baseline: (1006) 3 "Iteration 1"
    Unresolved:
      -c- /Build/JKEBuildScripts/start/jke.client.windows.bat

For example:

lscm checkin Build/JKEBuildScripts/start/jke.client.windows.bat

The result is shown below. It indicates that a new change set identified by the ID 1018 has been created.

Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1005) "Build"
    Baseline: (1006) 3 "Iteration 1"
    Outgoing:
      Change sets:
        (1018) *--@  "<No comment>" 24-Jul-2012 11:21 AM
          Changes:
            ---c- \JKEBuildScripts\start\jke.client.windows.bat

Working with removed file content

If a file has been removed from the workspace, it is not possible to check in that change to the file, because any command issued against a missing file will not work. Instead, the directory that contains the removed file needs to be checked in by using this command (assuming that the file was removed from the current working directory):

lscm checkin .

Working with new file content

There is no need to add new files to source control as an explicit action. Instead, the new file is simply checked in by using this command:

lscm checkin jke.client.linux.sh

The result of these commands is shown below:

Committing...
Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1005) "Build"
    Baseline: (1006) 3 "Iteration 1"
    Outgoing:
      Change sets:
        (1018) *--@  "<No comment>" 24-Jul-2012 11:21 AM
          Changes:
            --a-- /JKEBuildScripts/start/jke.client.linux.sh

The change information presented above is described in Table 6.

Table 6. Characters that describe characteristics of the resource
FlagDescription
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.

changeset

Manipulate change sets.

Several subcommands are available for the manipulation of change sets. They are listed in Table 7.

Table 7. Changeset subcommands
SubcommandDescription
associate Create an association with a work item.
comment Create a new comment for the work item (generally used rather than the work item association).
complete Close the change set and prevent further changes.
current Make the change set default for the association with new checked in files.
disassociate Remove the work item association.
discard Remove the changes associated with the change set.
extract Extract a specific file from a change set at the version referenced by the change set.
relocate Move the changes from one change set to another change set.
resume Resume working on a suspended change set.
suspend Preserve the change set content and remove the changes listed in the change set. All changes that existed in the change set at the time that it was suspended can be resumed later.

comment

To add the "Changes to files in the client directory" comment to the change set with the ID of 1019, use this command:

lscm changeset comment -r SRV6 1018 "Changes to files in the client directory"

When the status command is then used, the comment appears as shown below:

Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1005) "Build"
    Baseline: (1006) 3 "Iteration 1"
    Outgoing:
      Change sets:
        (1018) *--@  "Changes to files in the client directory" 24-Jul-2012 11:>

associate

To associate the change set, which has the ID 1018, with the work item with the ID of 117, use this command:

lscm changeset associate -r SRV6 1018 117

The result shows "Link created."

When the status command is used, the comment appears as shown below:

Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1005) "Build"
    Baseline: (1006) 3 "Iteration 1"
    Outgoing:
      Change sets:
        (1018) *--@  117 "Donors should have the ability to choose allocation o>

suspend

To suspend the 1018 change set, enter this command:

lscm changeset suspend -r SRV6 1018

The result is reported:

Change sets successfully suspended.

When the status command is then used, the comment appears as shown below:

Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1005) "Build"
    Baseline: (1006) 3 "Iteration 1"
    Suspended:
      Change sets:
        (1018) ---@  117 "Donors should have the ability to choose allocation o>

resume

After suspending a change set, it can be resumed by using the following command:

lscm changeset resume -r SRV6 1018

The result of executing the resume command is shown below, where the content of the change set is displayed together with the associated work-item:

Resuming change sets:
Repository: https://rational-srv-06:9443/ccm/
Workspace: (1000) "MyWorkspace"
  Component: (1005) "Build"
    Change sets:
      (1018) ---@  "Changes to files in …." 24-Jul-2012 11:21 AM
        Changes:
          ---c- \Build\JKEBuildScripts\start\jke.client.windows.bat
        Work items:
          (1019) 117 "Donors should have the ability to choose..."

extract

This command extracts the content of a specific version of a file from the change set and loads the extracted contents onto a specified disk path. Table 8 describes arguments for the command, and Table 9 describes command options.

lscm changeset extract [options] <change set> <path-to-item> <path-on-disk>
Table 8. Arguments for the changeset extract command
ArgumentDescription
[options] See Table 9.
<change set> The change set. To specify the change set, use its alias or UUID[@repo].
<path-to-item> The path or UUID of the item to be extracted. If the path is specified and if the change set exists locally, use the relative path of the file from the current working directory. If the path is specified and the change set is incoming, use the relative path of the file from the sandbox root.
<path-on-disk> The path where the extracted content must be loaded. The path can be an absolute or a relative path from the current working directory.
Table 9. Options for the changeset extract command
ArgumentDescription
-d [--directory] arg Specifies the root of the shared file system.
-o [--overwrite] Overwrites the existing disk file.

diff

This shows the changes made to a file during editing (italics = variables):

lscm diff [options] aftertype afterselector [beforetype] [beforeselector]

Arguments for the command are described in Table 10, and command options are described in Table 11.

Table 10. Arguments for the diff command
ArgumentDescription
aftertype The type of item to use for the after state (file, workspace, stream, changeset)
afterselector The selector for the item for the after state
beforetype The type of item to use for the before state (workspace, stream, baseline, changeset)
beforeselector The selector for the item for the before state
Table 11. Options for the diff command
ArgumentDescription
-d [--directory] arg Specify the root of the shared file system.
-p [--fullpatch] Produce a full Jazz patch.
-w [--workspace] arg The workspace or stream (name, alias or UUID) to show history. The workspace is inferred from the local file system if this option is omitted.

Example:

lscm diff file Build\JKEBuildScripts\start\jke.client.windows.bat baseline "Iteration 1"

The result of running the above comparison of a file with local changes compared to the state of the file in Baseline 3 is shown below:

lscm diff -u -N Build/JKEBuildScripts
/start/jke.client.windows.bat Build/JKEBuildScripts/start/jke.client.windows.bat
--- Build/JKEBuildScripts/start/jke.client.windows.bat  2012-06-13 16:33:14.000000769
 +0100
+++ Build/JKEBuildScripts/start/jke.client.windows.bat  2012-07-24 10:58:50.000000343
 +0100
@@ -1,9 +1,10 @@
-@rem ***************************************************************************
+@rem **********************************************************************

Note:
The hyphen (-) shows a line that has been removed, and the plus sign (+) shows the new line that replaces it.


Section 2. Advanced commands

Some of the commands presented in this section are used only under specific circumstances that a user is likely to encounter after using the product for a while. All commands include examples to illustrate specific scenarios. In the last section, several additional commands are presented with a Perl script that shows how a customers' requirement for extracting a set of file changes to a temporary location were accommodated. The information presented is applicable to both Microsoft Windows and UNIX systems, with occasional differences highlighted where necessary.

Subcommand summary

A summary of the subcommands presented in this section is in the table in Table 12. Details of frequently used commands and their frequently used arguments and options are displayed in the subsequent sections.

Table 12. Subcommands with a short description
CommandDescription
accept Accept change sets into a remote workspace, and download the changes.
annotate Annotates lines of text file with change history such as author, time stamp, comment etc.
changeaccess Modifies the read access permissions for files and folders.
compare Compare the contents of workspaces, streams, baselines, or snapshots.
delete Delete repository items.
deliver Deliver checked-in changes from a remote workspace to another workspace or stream.
extract Extract a specific version of a file from the repository.
help List available subcommands and provide detailed help on each.
history Shows the history for a file or component.
list List repository items. Subcommands: baselines changesets components credentials daemons locks projectareas properties remotefiles snapshots states streams teamareas users workspaces
undo Undoes changes to files.

Details of frequently used subcommands

Further details of specific commands that are frequently used are included in this section. Each subsection includes an example and further information about the context, if appropriate.

compare

Compare the contents of workspaces, streams, baselines, or snapshots.

Arguments for the command are described in Error: Reference source not found, and command options are described in Error: Reference source not found.

Use:

lscm compare [options] <new-type> <new> <old-type> <old>
Table 13. compare command arguments
ArgumentDescription
new-type, old-type Type of the new item to compare from these options: workspace, stream, baseline, or snapshot
new New item to compare
old Old item to compare against the new
Table 14. compare command options
ArgumentDescription
-c [--component] arg Component for baseline comparisons. Required if the baseline is specified with anything other than an alias or UUID.
-C [--format-contributor] arg Format for contributors.
{userid} expands to the user's repository ID
{name} expands to the user name
{email} expands to the user's email address
{itemid} expands to the user's repository item ID
-D [--format-date] arg Format for dates. Legal values can be found in the Java SimpleDateFormat specification.
-f [--flow-directions] arg Show only changes in the given direction. Must be one of the following:
  • i for incoming
  • for outgoing
  • b for both (default)
-I [--include-types] arg A combination of letters indicating which items to show:
  • d for - flow direction
  • c for component
  • b for baseline
  • w for work item
  • s for change set
  • f for file system (default: dcbsw)
-P [--password] arg Password for repository.
-p [--prune] arg Prune unchanged or empty items. May include:
  • d for empty directions
  • c for unchanged components
-r [--repository-uri] arg URI specifying the location of repository.
-S [--show] arg Indicate what optional values should be displayed.
  • c causes contributor fields to be shown
  • d causes date fields to be shown
  • i causes work items to be shown under change sets
-u [--username] arg Username for repository.
-w [--reroot] arg Root work items under a specific node type. Must be one of the following indicators:
  • r for root
  • d for direction
  • c for component
  • b for baseline

In the example below, two streams are compared, with changes flowing from both streams listed:

lscm compare -c "Banking Logic" -f b -r SRV6 stream "BRM Stream" stream "BRM Code 
Coverage Stream"

The result is:

Outgoing Changes
  Component (1002) "Banking Logic"
  Component (1005) "Build"
  Component (1017) "C# Samples" (added)
  Component (1007) "C# UI"
  Component (1009) "Database"
  Component (1011) "Java UI"
  Component (1013) "Prerequisites"
  Component (1015) "Web UI"
Incoming Changes
  Component (1002) "Banking Logic"
    (1020) Mark Roberts <mark@rational.com> 121: Add support ... analysis 
  Component (1005) "Build"
    (1021) Mark Roberts <mark@rational.com> 121 Add support ... analysis
  Component (1007) "C# UI"
  Component (1009) "Database"
    (1022) Mark Roberts <mark@rational.com> 121: Add support ... analysis
  Component (1011) "Java UI"
    (1023) Mark Roberts <mark@rational.com> 121: Add support ... analysis
  Component (1013) "Prerequisites"
    (1024) Mark Roberts <mark@rational.com> 121: Add support ... analysis
  Component (1015) "Web UI"
    (1025) Mark Roberts <mark@rational.com> 121: Add support ... analysis

Note:

It is possible to restrict the display to just the incoming or outgoing changes with the –f option. The direction of change flow is such that "Incoming" refers to changes flowing from the old to the new.

In the following example, two streams are compared. Changes that need to be sent to each stream are listed. Restrictions are used to display only change sets, and a filter is used to display the full name of the person who delivered the change sets.

lscm compare -c "Banking Logic" -f b -I s -C {name} -r SRV6 stream "BRM Stream" stream 
"BRM Code Coverage Stream"

The result is shown below:

(1024) Mark Roberts <No comment> 2012/07/25
(1022) Mark Roberts <No comment> 2012/07/25
(1023) Mark Roberts <No comment> 2012/07/25
(1025) Mark Roberts <No comment> 2012/07/25
(1021) Mark Roberts <No comment> 2012/07/25
(1020) Mark Roberts <No comment> 2012/07/25

It is also possible to compare streams to workspaces.

accept

Accept change sets into a workspace, and download the changes.

The default behavior is to accept all changes in all components. However, a subset of changes can be selected using the change set ID or work item numbers as described below in the options section. Command options are described in Table 15.

Table 15. accept command options
ArgumentDescription
-b [--baseline] Indicates the given baselines should be accepted.
-C [--components] Accept all changes in the specified components.
-c [--changes] Indicates the specific change sets to be accepted.
-o [--overwrite-uncommitted] Run the accept even though there are uncommitted local changes. Might cause an overwrite of content.
-s [--source] arg Select a source workspace from which changes will flow.
-t [--target] arg Select a target workspace or stream into which changes will flow.

This is an example of the accept command to accept all incoming changes in the workspace associated with the current directory:

lscm accept -r SRV6

The result of the accept command is shown below in which the content of change sets accepted is displayed:

Repository: https://rational-srv-06:9443/ccm/
Workspace: (1000) "MyWorkspace"
  Component: (1002) "Banking Logic"
    Change sets:
      (1004) ---$  "<No comment>" 19-Jul-2012 04:07 PM
        Changes:
          ---c- \Banking Logic\...\AccountBean.java
          ---c- \Banking Logic\JKEBusinessData\...\ContributionBean.java
        Work items:
          (1027) 52 "Implement - Donor Dividend Allocation Criteria"

deliver

Delivers changes from source workspace to target stream.

The default behavior is to deliver all changes in all components; however, a subset of changes can be selected by using the change set ID or work item numbers as described in the options section that follows. Command options are described in Table 16. The deliver command performs any process validation steps that have been switched on as part of the project configuration. For example, the command will validate that an appropriate work item has been associated with the change set if that part of process validation has been enabled.

Table 16. deliver command options
ArgumentDescription
-C [--components] The components for which changes should be delivered
-c [--changes] Indicates the specified change sets to be delivered
-s [--source] arg Select a source workspace/stream from which changes will flow
-t [--target] arg Select a target workspace/stream to which changes will flow

An example of the deliver command to deliver all outgoing changes in the workspace associated with the current directory:

lscm deliver -r SRV6

The result of the deliver command is shown below, in which the content of change sets delivered is displayed:

Delivering changes:
  Repository: https://rational-srv-06:9443/ccm/
  Workspace: (1001) "BRM Stream"
    Component: (1005) "Build"
      Change sets:
        (1018) ---$  "Changes to files in ... directory" 25-Jul-2012 05:51 PM
          Changes:
            ---c- \Build\JKEBuildScripts\start\jke.client.windows.bat
          Work items:
            (1019) 117 "Donors should have the ability to choose..."
Deliver command successfully completed.

history

Shows the history for a file or component.

The default behavior is to show the change set or work item history of a component, unless a specific file name is given.

If the command is executed from the root of a workspace, it will not have any component context. As a result, it will be necessary to change the directory into a location that is the load target for a specific component.

lscm history

When executed within a directory that is the load target for a specific directory, the result below is displayed:

Change sets:
  (1004) ---$ Mark Roberts “File changes for demonstration" 19-Jul-2012 04:07 PM
  (1031) ---$ Deb "Add WAR packaging for server, ... " 13-Jun-2012 11:12 AM
  (1032) ---$ Deb "Donors Can Choose to Support an ..." 11-Jun-2012 02:30 PM
  (1033) ---$ Deb "Dividend Allocation by ..." 08-Jun-2012 03:36 PM
  (1034) ---$ Bob "Donors will receive confirmation..." 06-Jun-2012 03:42 AM
  (1035) ---$ Marco "Donors Can Choose to Support..." 03-Jun-2012 05:51 AM
  (1036) ---$ Deb "Allocate Dividends by Percentage ..." 01-Jun-2012 11:54 PM
There is additional history available before this point.

The final line above shows that there may be additional changes to report. The default behavior is to display up to ten changes but if more are required the –m <n> option may be used to specify how many are required for example:

lscm history -m 2

Results display:

Change sets:
  (1004) ---$ Mark Roberts “File changes for demonstration" 19-Jul-2012 04:07 PM
  (1031) ---$ Deb "Add WAR packaging for server, ... " 13-Jun-2012 11:12 AM
There may be additional history before this point.

Using the –v option for a more verbose output results in the actual files contained within each change set being reported:

lscm history -v                                                           
Change sets:
  (1033)  ---@ Mark Roberts <No comment>
    Changes:
      ---c- /.../ClientLoginAccountType.java
  (1022)  ---$ Mark Roberts "change to client login account type code"
    Changes:
      ---c- /.../ClientLoginAccountType.java
  (1031)  ---$ Mark Roberts <No comment>
    Changes:
      ---c- /.../Adjustments.java
      ---c- /.../GmItemType.java
       --c- /.../Group.java

When used to report on a specific file, the command will show the change sets that contain the specified file, for example:

lscm history java/src/com/client/ClientLoginAccountType.java
Change sets:
  (1033)  ---@ Mark Roberts <No comment>
  (1022)  ---$ Mark Roberts "change to client login account type code"
  (1025)  ---$ Mark Roberts "Share projects"

list

List repository items.

The subcommands detailed in Table 17 identify which specific data is to be listed.

Table 17. Subcommands of the list commands
SubcommandDescription
baselines List baselines
changesets List the changes within the change sets
components List components in a workspace or stream
credentials List credentials stored by scm login
daemons List the user's currently running daemons
locks List the locks held in a stream
projectareas List project areas
properties List the properties currently set on files or folders
remotefiles Show the file tree of a remote workspace
Snapshots List snapshots associated with a workspace or stream
States List the states of the changes that are in the change set
streams List streams for the team areas of a contributor
teamareas List team areas
users List users
workspaces List remote workspaces

baselines

List baselines example:

lscm list baselines -w MRCL

The above command lists the baselines for all components referenced by the specific workspace:

Component: (1010) "Comp2"
  Baseline: (1016) 1 "Initial Baseline"   "Initial Baseline ....
Component: (1013) "Comp3"
  Baseline: (1017) 1 "Initial Baseline"   "Initial Baseline ....
Component: (1001) "Comp1"
  Baseline: (1034) 3 "Baseline 3"   Mark Roberts  Dec 25, 2011 12:35:53 AM
  Baseline: (1012) 2 "Baseline 2"   Mark Roberts  Dec 20, 2011 2:53:41 PM
  Baseline: (1002) 1 "Initial Baseline"   "Initial Baseline ....

The following command lists baselines for just the specified component:

lscm list baselines -C "C# UI"

The result is shown below:

Component: (1007) "C# UI"
  Baseline: (1037) 6 "jke.dev_I20120621-1428"   "Snapshot created by 
  Baseline: (1038) 5 "jke.dev.vs_I20120615-1311"   "Snapshot created by
  Baseline: (1008) 4 "Sprint 1 (Release 1.0)"   ""  Deb  Jun 13, 2012 4:33:31 PM
  Baseline: (1039) 3 "Week 2 (Sprint 1, Release 1.0)"   ""  
  Baseline: (1040) 2 "Week 1 (Sprint 1, Release 1.0)"   
  Baseline: (1041) 1 "Initial Baseline"   "Initial Baseline of Component C# UI

Note:

Some of the commands above are shortened for readability.

The following command lists the baselines and includes the unique identifier for each:

lscm --show-uuid y list baseline -C "Banking Logic"

The result is this:

  Baseline: (1042:_U68PZ9GrEeGtvtbgcxt9lw) 10 "jke.dev_I20120719-1609"   
  Baseline: (1043:_7X4wssUZEeGQS6A_L8KiKQ) 9 "jke.dev_I20120703-1618"   
  Baseline: (1044:_wFAXBMHTEeGQS6A_L8KiKQ) 8 "jke.dev_I20120629-1218"   
  Baseline: (1045:_dHyFErueEeGTsLA1UYI2LA) 7 "jke.dev_I20120621-1441"   
  Baseline: (1046:_wspLM7VkEeGs1coIrWWWhA) 6 "Week 1 (Sprint 2, Release 1.0)"   
  Baseline: (1003:_wIIwCLVkEeGs1coIrWWWhA) 5 "Iteration 1"   
  Baseline: (1047:_v7eM5bVkEeGs1coIrWWWhA) 4 "Sprint 1 (Release 1.0)"  
  Baseline: (1048:_vgDcX7VkEeGs1coIrWWWhA) 3 "Week 2 (Sprint 1, Release 1.0)"  
  Baseline: (1049:_vRc_hbVkEeGs1coIrWWWhA) 2 "Week 1 (Sprint 1, Release 1.0)"  
  Baseline: (1050:_prYH5bVkEeGs1coIrWWWhA) 1 "Initial Baseline"

The UUID values are required for subsequent commands described in this document.

remote files

To list the files held within the repository, use the remotefiles option for the list command. Arguments for the command are described in Table 18, and command options are described in Table 19.

lscm list remotefiles [options] <selector> <component> [remotePath]
Table 18. list remote files command arguments
ArgumentDescription
[options] See Table 19.
<selector> The workspace, stream, snapshot, or baseline (name[@repo], alias, or UUID[@repo]) whose remote files are to be listed.
-workspace, --snapshot or --baseline. By default, the selector will refer to a workspace.
<component> The component for which the remote files are listed.
[remote path] The remote path that specifies the root of the list.
Table 19. list remote files command options
ArgumentDescription
-b [--baseline] Indicates that the selector refers to a baseline.
-s [--snapshot] Indicates that the selector refers to a snapshot.
-w [--workspace] Indicates that the selector refers to a workspace or stream.

List the complete hierarchy of remote files at the indicated baseline of the Banking Logic component.

lscm list remotefiles -r SRV6 --depth - --baseline "jke.dev_I20120719-1609" "Banking
 Logic"

The result of the command is shown below:

/
/JKEBusinessData/
/JKEBusinessData/src/
/JKEBusinessData/src/com/
/JKEBusinessData/src/com/jke/
/JKEBusinessData/src/com/jke/beans/
/JKEBusinessData/src/com/jke/beans/ContributionBean.java
/JKEBusinessData/src/com/jke/beans/AccountTypeBean.java
/JKEBusinessData/src/com/jke/beans/TransactionBean.java
/JKEBusinessData/src/com/jke/beans/AccountBean.java
/JKEBusinessData/src/com/jke/beans/UserBean.java

To execute the same command as above but list the unique identifier for each file and directory:

lscm --show-uuid y list remotefiles -r SRV6 --depth - --baseline "jke.dev_I20120719-1609" 
"Banking Logic"

The result of the command is shown below:

 (_poP7UbVkEeGs1coIrWWWhA:_poP7VLVkEeGs1coIrWWWhA) /
(_tcoL5rVkEeGs1coIrWWWhA:_tj7GsLVkEeGs1coIrWWWhA) /JKEBusinessData/
(_tdE30rVkEeGs1coIrWWWhA:_tj7GxrVkEeGs1coIrWWWhA) /JKEBusinessData/src/
(_tdOBwbVkEeGs1coIrWWWhA:_tj7GybVkEeGs1coIrWWWhA) /JKEBusinessData/src/com/
(_tdXywLVkEeGs1coIrWWWhA:_tj7GzLVkEeGs1coIrWWWhA) /JKEBusinessData/src/com/jke/
(_tdXyw7VkEeGs1coIrWWWhA:_tj7Gz7VkEeGs1coIrWWWhA) /JKEBusinessData/src/com/jke/beans/
(_tdqtsrVkEeGs1coIrWWWhA:_gRyoVNGqEeGtvtbgcxt9lw) /JKEBusinessData/src/com/jke/beans
/ContributionBean.java
(_tdg8tLVkEeGs1coIrWWWhA:_XtUc-7udEeGTsLA1UYI2LA) /JKEBusinessData/src/com/jke/beans
/AccountTypeBean.java
(_td0esLVkEeGs1coIrWWWhA:_vnDcF7VkEeGs1coIrWWWhA) /JKEBusinessData/src/com/jke/beans
/TransactionBean.java
(_tdg8sLVkEeGs1coIrWWWhA:_s8Hl8tGqEeGtvtbgcxt9lw) /JKEBusinessData/src/com/jke/beans
/AccountBean.java
(_td0etLVkEeGs1coIrWWWhA:_tj7G8rVkEeGs1coIrWWWhA) /JKEBusinessData/src/com/jke/beans
/UserBean.jav

The UUID values are required for subsequent commands described in this guide. The UUID fields are explained by examining a specific example. The AccountTypeBean.java file is listed in the above command as:

(_tdg8tLVkEeGs1coIrWWWhA:_XtUc-7udEeGTsLA1UYI2LA) /JKEBusinessData/src/com/jke/beans/
AccountTypeBean.java

The first part of the UUID (_tdg8tLVkEeGs1coIrWWWhA) identifies the object. It remains the same for all commands that report this particular file.

The second part of the UUID (_tdg8tLVkEeGs1coIrWWWhA) is the version selector, which changes as the file evolves.

The history of the file shows the following:

lscm history -r SRV6 JKEBusinessData/src/com/jke/beans/AccountTypeBean.java

The result of the command is shown below:

Change sets:
 (1030) ---$ Mark Roberts "<No comment>" 21-Jun-2012 02:37 PM
 (1051) ---$ Deb "Share projects" 01-Jun-2012 03:51 AM

The above output shows that the file was shared as a new object on 1 June at 03:51 am and then a subsequent change was made to the file on 21 June at 2:37 pm.

The list of baseline creation activity for the component shows the following result:

lscm list baselines -C "Banking Logic"

The result of the command is shown below:

Component: (1002) "Banking Logic"
  Baseline: (1042) 10 "jke.dev_I20120719-1609"  	Jul 19, 2012 4:09:17 PM
  Baseline: (1043) 9 "jke.dev_I20120703-1618"   	Jul 3, 2012 4:18:14 PM
  Baseline: (1044) 8 "jke.dev_I20120629-1218"   	Jun 29, 2012 12:18:20 PM
  Baseline: (1045) 7 "jke.dev_I20120621-1441"   	Jun 21, 2012 2:41:43 PM
  Baseline: (1046) 6 "Week 1 (Sprint 2 ... ) "		Jun 13, 2012 4:33:36 PM
  Baseline: (1003) 5 "Iteration 1"   			Jun 13, 2012 4:33:32 PM
  Baseline: (1047) 4 "Sprint 1 (Release 1.0)"   	Jun 13, 2012 4:33:31 PM
  Baseline: (1048) 3 "Week 2 (Sprint 1, ... ) "	Jun 13, 2012 4:33:28 PM
  Baseline: (1049) 2 "Week 1 (Sprint 1, ... ) "	Jun 13, 2012 4:33:27 PM
  Baseline: (1050) 1 "Initial Baseline"   		Jun 13, 2012 4:32:48 PM

Therefore, the file should report the same version information in all baselines up to Baseline 7 (jke.dev_I20120621-1441) and then a different, but consistent, version identifier on and after Baseline 7.

Before Baseline 7

lscm --show-uuid y list remotefiles -r SRV6 --depth - --baseline "Sprint 1 (Release 1.0)" 
"Banking Logic" JKEBusinessData/src/com/jke/beans/AccountTypeBean.java

The result of the command is shown below:

(_tdg8tLVkEeGs1coIrWWWhA:_tj7G3bVkEeGs1coIrWWWhA) 
/JKEBusinessData/src/com/jke/beans/ AccountTypeBean.java

Before Baseline 7

lscm --show-uuid y list remotefiles -r SRV6 --depth - --baseline "Iteration 1" "Banking
 Logic" JKEBusinessData/src/com/ jke/beans/AccountTypeBean.java

The result of the command is shown below:

(_tdg8tLVkEeGs1coIrWWWhA:_tj7G3bVkEeGs1coIrWWWhA) /JKEBusinessData/src/com/jke/beans/
AccountTypeBean.java

At Baseline 7

lscm --show-uuid y list remotefiles -r SRV6 --depth - --baseline "jke.dev_I20120621-1441"
 "Banking Logic" JKEBusinessData/src/com/jke/beans/AccountTypeBean.java

The result of the command is shown below:

(_tdg8tLVkEeGs1coIrWWWhA:_XtUc-7udEeGTsLA1UYI2LA) /JKEBusinessData/src/com/jke/beans/
AccountTypeBean.java

After Baseline 7

lscm --show-uuid y list remotefiles -r SRV6 --depth - --baseline "jke.dev_I20120629-1218"
 "Banking Logic" JKEBusinessData/src/com/jke/beans/AccountTypeBean.java

The result of the command is shown below:

(_tdg8tLVkEeGs1coIrWWWhA:_XtUc-7udEeGTsLA1UYI2LA) /JKEBusinessData/src/com/jke/beans/
AccountTypeBean.java

States

Lists the states of the changes that are in the change set.

In many developer activities the same file will be checked in to the repository a number of times under the management of the same change set. Typical developer operations often involve the stages shown in Figure 2.

Figure 2. A sample edit, checkin, build, and deliver process
flow diagram of the processes

In Figure 2 there are five separate check-in operations. In situations where the developer has automatic checkin switched on, there will be a check-in for each Save operation (if performed through the graphical user interface Eclipse). As a result, it might occasionally be useful to be able to remove some of these historical checked-in versions.

Listing the states of a file is the first stage in removing the versions. This is done in conjunction with the lscm status command.

The lscm status command will list the change set into which the checkin operations have been performed.

lscm status

The result of the command is shown below:

Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1017) "C# Samples"
    Baseline: (1056) 2 "Baseline 1"
    Outgoing:
      Change sets:
        (1057) *--@  "<No comment>" 26-Jul-2012 08:32 PM

The change set ID is listed above – 1057.

The list states command can now be used with the change set ID as an argument:

lscm list states 1057

The result of the command is shown below:

(1058) /C# Samples/Attributes/not-needed.html
  (1059) Initial 26-Jul-2012 07:31 PM
  (1060) Modified 26-Jul-2012 07:31 PM
  (1061) Modified 26-Jul-2012 07:32 PM
  (1062) Current - Modified 26-Jul-2012 07:32 PM

If necessary, the intermediate versions can now be removed using the lscm delete state-content command described later in this document.

undo

This command undoes changes to files to cancel an unresolved change in a workspace.

In the example, the undo command is used to undo a change to a specific file (path shortened):

lscm undo "C:\workspace\Banking Logic\........\organization.java"

This results in the response of:

Changes successfully undone.

Extract

Extract content from the repository.

This command requires the use of unique identifiers to ensure that the correct file at the correct version is extracted from the repository. The lscm list remote files commands described above can generate the information required for this command. Arguments for the command are described in Table 20, and command options are described in Table 21.

lscm extract file [options] <item> <state> <path-on-disk>
Table 20. extract file command arguments
ArgumentDescription
[options] See Table 21.
<item> The item ID of the item to be extracted. Supports UUID format only.
<state> The state ID of the item to be extracted. Supports UUID format only.
<path-on-disk> The path where the extracted content must be loaded. The path can be an absolute path or a relative path from the current working directory.
Table 21. extract files command options
ArgumentDescription
-o [--overwrite] Overwrites the existing disk file.

After displaying the UUID information by using the list remotefiles command shown below, it is possible to extract a copy of the file to a new location.

lscm --show-uuid y list remotefiles -r SRV6 --depth - --baseline "jke.dev_I20120629-1218"
 "Banking Logic" JKEBusinessData/src/com/jke/beans/AccountTypeBean.java

The result of the command is shown below:

(_tdg8tLVkEeGs1coIrWWWhA:_XtUc-7udEeGTsLA1UYI2LA) /JKEBusinessData/src/com/jke/beans/
AccountTypeBean.java

Extract the file with this command:

lscm extract file -r SRV6 _tdg8tLVkEeGs1coIrWWWhA _XtUc-7udEeGTsLA1UYI2LA c:\temp\
AccountTypeBean.java

The result of the command is shown below:

Successfully extracted file to "C:\temp\AccountTypeBean.java".

Annotate

This command annotates lines of a text file, such as the author, time stamp, and comment.

The command below shows how to generate annotated information for a Java file:

lscm annotate /JKEBusinessData/src/com/jke/beans/AccountTypeBean.java

The result of the command is shown below:

1  Deb          (1051) 2012-06-01 03:51 AM    Share projects /*********
2  Mark Roberts (1030) 2012-06-21 02:37 PM 90
3  Deb          (1051) 2012-06-01 03:51 AM    Share projects  *
4  Deb          (1051) 2012-06-01 03:51 AM    Share projects  ********
5  Deb          (1051) 2012-06-01 03:51 AM    Share projects
6  Deb          (1051) 2012-06-01 03:51 AM    Share projects package com.jke.b
7  Deb          (1051) 2012-06-01 03:51 AM    Share projects
8  Deb          (1051) 2012-06-01 03:51 AM    Share projects public enum Acco
9  Deb          (1051) 2012-06-01 03:51 AM    Share projects    Checking(

In the data presented above, the words "Share Project" refer to a change set identifier for when the content was initially shared into Rational Team Concert. The actual code of the file appears to the right of this section, but to avoid line-wrapping, this has been truncated. The number 90 in line 2 identifies a work item that is associated with the change set that produced the change. In this example, the line was deleted from the file.

Delete

This command deletes items that are in the repository.

The command is used to remove the content of intermediate check-in operations as described in the section regarding the lscm list states command. Arguments for the command are described in Table 22, and command options are described in Table 23.

lscm delete state-content [options] <item> <states...>
Table 22. delete state-content command arguments
ArgumentDescription
[options] See Table 23.
<item> The item for which the specified states are deleted. To specify the item, use its path[@repo], alias, or UUID[@repo]. If you specify the path, it must be within the sandbox.
<state> The states to delete. To specify a state, use its alias or UUID.
Table 23. delete state-content command options
ArgumentDescription
--force Force deletion even if multiple items reference the content.

Identify the change set number.

lscm status

The result of the command is shown below:

Workspace: (1000) "MyWorkspace" <-> (1001) "BRM Stream"
  Component: (1017) "C# Samples"
    Baseline: (1056) 2 "Baseline 1"
    Outgoing:
      Change sets:
        (1057) *--@  "<No comment>" 26-Jul-2012 08:32 PM

The change set ID is listed above – 1057.

The list states command can now be used with the change set ID as an argument:

lscm list states 1057

The result of the command is shown below:

 (1058) /C# Samples/Attributes/not-needed.html
  (1059) Initial 26-Jul-2012 07:31 PM
  (1060) Modified 26-Jul-2012 07:31 PM
  (1061) Modified 26-Jul-2012 07:32 PM
  (1062) Current - Modified 26-Jul-2012 07:32 PM

To remove the intermediate content produced on the 26 July at 7:31 pm, use the command:

lscm delete state-content 1058 1060

The result of the command is shown below:

Successfully deleted content of the item state(s). Now the list states command will show
 the removal of the content: lscm list states 1057

The result of the command is shown below:

(1058) /C# Samples/Attributes/not-needed.html
  (1059) Initial 26-Jul-2012 07:31 PM
  (1060) Modified [Content deleted by mark on 26-Jul-2012 09:36 PM
  (1061) Modified 26-Jul-2012 07:32 PM
  (1062) Current - Modified 26-Jul-2012 07:32 PM

help

Display command help.

For example:

lscm help create

This will result in the subcommands of the create command being displayed:

Help on create
Creates items in the repository. You can create different items, as specified by
 subcommands.
Aliases: cr
Usage: lscm create <baseline|changeset|component|loadrules|snapshot|stream|workspace>
 [subcommand-args]
Subcommands:
  baseline - Creates a baseline in a component.
  changeset - Creates a change set.
  component - Creates a component within the specified workspace or stream.
  loadrules - Creates load rules.
  snapshot - Creates a snapshot that is associated with the workspace or stream.
  stream - Creates a stream.
  workspace - Creates a remote repository workspace.

To display help on a specific subcommand, use:

lscm help create baseline

changeaccess

This modifies the read access permissions for files and folders.

The read access can also be set to a contributor, team area or project area. Arguments for the command are described in Table 24, and command options are described in Table 25.

lscm changeaccess [options] <item...>
Table 24. changeaccess command arguments
ArgumentDescription
[options] See Table 25.
<item...> The path of the item for which read access permission is modified. The path might be a file system path to locally loaded items, or it might be a remote path. If you specify a remote path, you must also specify the workspace/stream and the component.
Table 25. changeaccess command options
ArgumentDescription
--apply-to-child-items Indicates that the modified read access permission must be applied to child files and folders.
--componentaccess Everyone who can access the component has read access.
--contrib arg Only the contributor has read access.
--projectarea arg Everyone who has access to the project area.
--teamarea arg Everyone who has access to the team area.
-C [--component] arg The component to select. Specify the name, alias, or UUID of the component.

To hide a particular file such that it is only visible to a certain team:

lscm changeaccess --teamarea "Energy Efficiency Matters" description\descriptionframe.html

The result of the command is:

Successfully changed read access permissions.

When a new user who is not a member of the Energy Efficiency Matters team loads the workspace, the file is not present.

resolve

Resolve workspace conflicts.

Arguments for the command are described in Table 26.

lscm resolve [options] <path...>
Table 26. resolve arguments
ArgumentDescription
-c {--checkin] Resolves conflicts by using the currently checked in version.
-p [--proposed] Resolves conflicts by using the proposed version.
-o [--overwrite-uncommitted] Continues with the operation even if uncommitted local changes exist. If you use this option, changes might be overwritten.

To illustrate the use of the resolve command, a conflict situation is required. A change was performed using the Rational Team Concert shell interface, using Workspace A, and the change was delivered. In Workspace B, the main workspace for the examples in this document, a change was also made to the same file in the same lines of code to cause a conflict.

The lscm status command shows the change within the current workspace and the incoming change from Workspace A.

Workspace: (1064) "BRM Stream Workspace" <-> (1001) "BRM Stream"
  Component: (1002) "Banking Logic"
    Baseline: (1003) 5 "Iteration 1"
    Outgoing:
      Change sets:
        (1066) *--@  "<No comment>" 09-Aug-2012 04:53 PM
    Incoming:
      Change sets:
        (1065) ---$  128 "Create a conflicted change" - "<No comment>" 09-Aug-2>

When the accept command is issued, the warning concerning the conflict is displayed.

lscm accept

The result of the command is shown below:

Repository: https://rational-srv-06:9443/ccm/
Workspace: (1064) "BRM Stream Workspace"
  Component: (1002) "Banking Logic"
    Change sets:
      (1065) --#$  "<No comment>" 09-Aug-2012 04:50 PM
        Changes:
          -#-c- \JKEBusinessLogic\src\com\jke\organization\Organization.java
        Work items:
          (1074) 128 "Create a conflicted change"
Following workspaces still have conflicts after accept:
  BRM Stream Workspace
Run 'lscm resolve' or 'lscm conflicts' or 'lscm status' for help in resolving the
 conflicts.

After the accept command, the lscm status command reports the files that have a conflict:

Workspace: (1064) "BRM Stream Workspace" <-> (1001) "BRM Stream"
  Component: (1002) "Banking Logic"
    Baseline: (1003) 5 "Iteration 1"
    Conflicts:
      Cc- /JKEBusinessLogic/src/com/jke/organization/Organization.java (Modifie>
    Outgoing:
      Change sets:
        (1066) *--@  "<No comment>" 09-Aug-2012 04:53 PM

To resolve the conflict using the checked-in version created in Workspace B, where the changes have been made to the file, use the command:

lscm resolve -c Organization.java

The result of the command is shown below:

Conflicted items have been successfully resolved.

To resolve the conflict by using the accepted change, which will overwrite the changes made within the current workspace, use this command:

lscm resolve -p Organization.java

The result of the command is shown below:

Conflicted items have been successfully resolved.

snapshot

Promote a snapshot to a workspace or stream.

Arguments for the command are described in Table 27.

lscm snapshot promote [options] <workspace> <snapshots...>
Table 27. snapshot promote arguments
ArgumentDescription
<workspace> The target workspace or stream. To specify the workspace or stream, use its name[@repo], alias, or UUID[@repo].
<snapshots ...> The snapshots to be owned by the workspace or stream. To specify a snapshot, use its name[@repo], alias, or UUID[@repo].

Previously documented, the lscm list snapshot command will be useful in this scenario to list snapshots and the lscm list streams command to list the streams.

To list the snapshots, use:

lscm list snapshot

The result of the command is shown below:

(1078) "jke.dev_I20120802-1328" Aug 2, 2012 1:28 PM
(1079) "jke.dev_I20120723-0849" Jul 23, 2012 8:49 AM
(1080) "jke.dev_CC_I20120722-2020" Jul 22, 2012 8:20 PM
(1081) "jke.dev_I20120721-0908" Jul 21, 2012 9:09 AM
(1082) "jke.dev_I20120719-1609" Jul 19, 2012 4:09 PM
(1083) "jke.dev_I20120719-1407" Jul 19, 2012 2:07 PM

To list possible target streams use the command:

lscm list streams --projectarea "JKE Banking (Change Management)" -r SRV6

The result of the command is shown below:

(1088) "BRM Code Coverage Stream" JKE Banking (Change Management)
(1001) "BRM Stream" Business Recovery Matters
(1089) "EEM Stream" Energy Efficiency Matters
(1090) "JKE Banking Integration Stream" JKE Banking (Change Management)
(1091) "Production Stream" Release Engineering
(1092) "QA Maintenance Stream" Release Engineering
(1093) "QA Stream" Release Engineering
(1094) "RelEng Stream " Release Engineering

To promote two snapshots to a new stream, use:

lscm snapshot promote "JKE Banking Integration Stream" "jke.dev_I20120802-13 28"
 "jke.dev_I20120723-0849"

The result of the command is shown below:

Promoted snapshots: 
    jke.dev_I20120802-1328 
    jke.dev_I20120723-0849

version

List the version identifier of the currently installed Rational Team Concert command line tools.

lscm version

The result of the command is shown below:

Build Id: (unset)
com.ibm.team.filesystem.cli.client, version 3.1.0.v20120519_2357
  Subcommands: ...
com.ibm.team.filesystem.cli.tools, version 3.1.0.v20120510_0526
  Subcommands: tools.verify tools.validate tools.echo.stdin tools.configvalue tools.log
com.ibm.team.filesystem.cli.core, version 3.1.0.v20120519_2357
  Subcommands: help version

lastmod

Calculates the time of most recent modification, based on the latest baselines that modified the given folders.

Arguments for the command are described in Table 28, and command options are described in Table 29.

lscm lastmod [options] <path...>

Table 28. lastmod command arguments
ArgumentDescription
[options] See Table 29.
<path...> A list of folders for which to calculate the time of most recent modification.
Table 29. lastmod command options
ArgumentDescription
-d [--directory] arg Specifies the root of the shared file system.
-f [--format] arg A date formatter that formats the return date. The default is yyyyMMddmm. For example: 200801011131. For details of the date formats, see the Class SimpleDateFormat documentation cited in Resources.

To list the last modification date, due to a baseline change, use the command below for two top-level directories under a workspace:

lscm lastmod "Banking Logic" "C# Samples"

The result of the command is shown below:

/C# Samples=201207260820 
/Banking Logic=201206130433

This is an example of using the format argument described at the web page referenced above:

lscm lastmod -f "dd MMMM yyyy 'at' HH:mm:ss" "Banking Logic" "C# Samples"

The result of the command is shown below:

/Banking Logic=13 June 2012 at 16:33:32 
/C# Samples=26 July 2012 at 20:20:28

lock

Acquires or releases the locks in a stream.

A lock prevents other users from delivering changes to the file on the stream for which you hold the lock. Sub-commands for the command are described in Table 30.

lscm lock <acquire|list|release> [subcommand-args]
Table 30. lock subcommands
ArgumentDescription
acquire Acquires the lock on a specified file in a stream.
list Lists the locks that are held in a stream. It is possible to filter the locks by component and user. If all arguments are omitted, the collaborating stream in the component that is identified by the current working directory is used. The output is formatted by the following information: The path source, which is Local, Remote, or Unknown; the path, which is <unknown> for paths that cannot be resolved; the lock owner's user ID; the component name; and the stream name.
release Releases the lock on a specified file in a stream.

lock list

The lock list command has several options, which are described in Table 31.

Table 31. lock list command options
ArgumentDescription
-c [--component] arg The component to select. Specify the name, alias, or UUID of the component.
-m [--maximum] arg The maximum number of results that can be returned. The number must be greater than 0. Default is 10.
-o [--owner] arg The user ID of the owner of the lock.
-s [--stream] arg Specifies a stream. To specify a stream, use its name[@repo], alias, or UUID[@repo].
-v [--verbose] Shows more information.
-w [--wide] Does not shorten output. If omitted, the width defaults to the value of the COLUMNS environment variable. If the COLUMNS environment variable is not set, the width defaults to 80 characters.

In the simplest format, the command can be used as shown here:

lscm lock list

The result of the command is shown below:

No locks to list.

lock acquire

The lock acquire command has two options, which are described in Table 32.

Table 32. lock acquire command options
ArgumentDescription
-R [--remotePath] Indicates that the provided paths are the remote paths in the specified component and specified stream.
-s [--stream] arg Specifies a stream, as indicated by the name[@repo], alias, or UUID[@repo]. If you use the --remotePath option, you must specify a stream.

In the simplest format, the command can be used as shown below to acquire a lock:

lscm lock acquire "C# samples\Attributes\description.html"

This is the result of the command:

Locks successfully acquired.

When the lock list command is used, the result is as shown below:

L (1063) "/C# Samples/Attributes/description.html" mark (1017) "C# Samples" (10>

When used with the –w option for a wide output the result (wrapped in this document), the result is as shown here:

L (1063) "/C# Samples/Attributes/description.html" mark (1017) "C# Samples"
 (1001) "BRM Stream"

lock release

The lock release command has several options, too, and as described in Table 33.

Table 33. lock release command options
ArgumentDescription
-f [--force] Forces the file to be unlocked with administrator privileges.
-R [--remotePath] Indicates that the provided paths are the remote paths in the specified component and specified stream.
-s [--stream] arg Specifies a stream, as indicated by the name[@repo], alias, or UUID[@repo]. If you use the --remotePath option, you must specify a stream.
-v [--verbose] Shows more information.
-w [--wide] Does not shorten output. If omitted, the width defaults to the value of the COLUMNS environment variable. If the COLUMNS environment variable is not set, the width defaults to 80 characters.

In the simplest format, the command can be used as shown to release a lock:

lscm lock release "C# samples\Attributes\description.html"

The result of the command is shown below:

Locks successfully released.

Administrator: Unlock a file

It might occasionally be necessary to release a lock held by someone else who has locked a file and then left for a period of absence. This requires administrative privileges and is used in the following way:

  1. Use the lscm lock list –w command to identify the lock and the stream for which the file is locked.
  2. Use the lscm lock release command to release a lock on a file by giving the file location and the stream for which it was locked.
lscm lock list –w

The result of the command is shown below:

L (1063) "/C# Samples/Attributes/description.html" mark (1017) "C# Samples"
 (1001) "BRM Stream"

The result above lists the full path, which includes a directory name to represent the component, the user who holds the lock, the component in which the file resides, and the stream for which the lock is held.

Therefore, the required unlock command is:

lscm lock release --force --remotePath "/Attributes/description.html" --stream
 "BRM Stream" --component "C# Samples"

The result of the command is shown below:

Locks successfully released.

property

Modifies the properties of a file or folder.

A number of standard properties are set on a file and additional properties can be set if required. Sub-commands are described in Table 34.

lscm property <sub-command>
Table 34. property subcommands
SubcommandDescription
get Gets the value of the property.
remove Removes the property.
set Sets the property with the specified value.

Four properties are set on all files and one on a directory. They are listed in the table in Table 35.

Table 35. file and directory properties
PropertyApplicable toDescription
jazz.executable File Indicates whether the file is executable. Cannot be directly modified.
jazz.mime File The MIME type of the file, which must be of the form major/minor.
jazz.line-delimiter File Indicates the line delimiter. Shall be one of the following types:
  • platform – Indicates that the file should be given the platform-specific line delimiter on the load or accept command.
  • none – Indicates that the file should not have its line delimiters changed on the load or accept command.
  • crlf – Indicates that the file should always have Windows-style line delimiters.
  • lf – Indicates that line feeds should be used as line delimiters.
  • cr – Indicates that carriage returns should be used as line delimiters.
jazz.read-access File and directory Indicates the access permission to a particular item. The access permission could be one of the following:
  • Public – Everyone who can access the component has read access.
  • Contributor – Only the contributor has read access.
  • Team area – Everyone who has access to the team area.
  • Project area – Everyone who has access to the project area.
jazz.encoding File The character encoding of a file.

In addition, any arbitrary property can be set on a file or directory, as the example that follows shows.

The properties shown above can be viewed through the Eclipse user interface for Rational Team Concert by selecting a file or directory in the Project Explorer view, right-clicking a file, and then selecting Properties. Examples of the use of properties for a file are shown in Figures 3 and 4. The directory properties are presented in a similar manner, but there are fewer properties to display.

Figure 3 shows the Executable, MIME, and Line delimiter, and Figure 4 shows the character encoding of the file.

Figure 3. Eclipse view of the properties of a file, Part 1
Graphical user interface view of the properties
Figure 4. Eclipse view of the properties of a file, Part 2
GUI view of the properties

property get

The property get command has a number of options detailed in Table 36.

Table 36. property get command options
ArgumentDescription
<key> The key used to look up the property.
<files...> The files for which the property should be retrieved.

Examples below show the display of the five standard properties associated with a file.

lscm property get jazz.line-delimiter Organization.java

The result of the command is shown below:

C:\Users\...\JKEBusinessLogic\src\com\jke\organization\Organization.java
 jazz.line-delimiter - LF (Unix) lscm property get jazz.read-access Organization.java

The result of the command is shown below:

C:\Users\...\JKEBusinessLogic\src\com\jke\organization\Organization.java
 jazz.read-access - Public lscm property get jazz.encoding Organization.java

The result of the command is shown below:

C:\Users\...\JKEBusinessLogic\src\com\jke\organization\Organization.java jazz.encoding -
 Cp1252 lscm property get jazz.executable Organization.java

The result of the command is shown below:

C:\Users\...\JKEBusinessLogic\src\com\jke\organization\Organization.java jazz.executable -
 false lscm property get jazz.mime Organization.java

The result of the command is shown below:

C:\Users\...\JKEBusinessLogic\src\com\jke\organization\Organization.java
 jazz.mime - text/text

property set

The property set command has a number of options detailed in Table 37.

Table 37. property set command options
ArgumentDescription
<key> The key used to look up the property.
<Value> The value of the property.
<files...> The files for which the property should be retrieved.

An example below shows the setting of a custom property and then a get method of the property, too.

To set the property:

lscm property set Tested 'Yes' Organization.java

The result of the command is shown below:

Tested successfully set to 'Yes'

To validate that the property has been set:

lscm property get Tested Organization.java 

C:\Users\...\JKEBusinessLogic\src\com\jke\organization\Organization.java Tested - 'Yes'

property remove

Removes the property from the file or folder.

Command arguments are detailed in Table 38.

Table 38. property remove command options
ArgumentDescription
<key> The key used to look up the property.
<files...> The files for which the property should be removed

An example of the removal of a custom property is shown below:

lscm property remove Tested Organization.java

The result of the command is shown below:

Tested property successfully removed.

Section 3. Script scenario

The scenario presented in this section is based on a customer requirement to perform a specific operation. The customers' question was:

How can we compare two streams and physically download the different files into a temporary location?

Description of the operation

In the example, the streams to be compared are the BRM Stream (a development stream) and the JKE Banking Integration Stream (a protected stream to which changes are delivered when they have been through a phase of unit testing). System integration work is to be undertaken on the integration stream.

To compare the two streams, the lscm compare command is used. This allows a number of arguments to be used to restrict the information presented. It is possible that some work is being performed directly on the integration stream, but for the purpose of this example, only the change sets to flow from the BRM stream to the integration stream will be required. For this reason, the –f o for "outgoing flow" will be used, as shown below. Using the –p c option causes unchanged components to be missed from the report.

lscm compare stream "BRM Stream" stream "JKE Banking Integration Stream" -f o –p c

The result of the command is shown below:

Outgoing Changes
  Component (1002) "Banking Logic"
    (1030) Mark Roberts <mark@rational.com> 90: Complete ... Test 2012/06/21
    (1029) Mark Roberts <mark@rational.com> 90: Complete ... Test 2012/06/29
    (1028) Mark Roberts <mark@rational.com> 71: JKE Charity ... 2012/07/03
    (1004) Mark Roberts <mark@rational.com> 52: Implement - ... 2012/07/19
    (1065) Mark Roberts <mark@rational.com> 128: Create ... 2012/08/09
    (1066) Mark Roberts <mark@rational.com> 129: resolve conflict 2012/08/09
    (1076) Mark Roberts <mark@rational.com> 128: Create ... 2012/08/09
    (1077) Mark Roberts <mark@rational.com> 128: Create ... 2012/08/09
  Component (1005) "Build"
    (1095) Mark Roberts <mark@rational.com> 90: Complete ... 2012/07/02
    (1018) Mark Roberts <mark@rational.com> 117: Donors ... 2012/07/25
  Component (1017) "C# Samples" (added)
  Component (1007) "C# UI"
    (1096) Mark Roberts <mark@rational.com> 84: A simple change 2012/06/15
    (1097) Mark Roberts <mark@rational.com> 84: A simple change... 2012/06/15

Because the change set identifiers are all that are required from the above report, a Perl script is used to extract just that information. This task is a multi-step process; therefore, it is reasonable to wrap all of the commands into a single Perl script. Other scripting languages could be used, or compiled languages, such as Java.

The Perl script

The script collects three arguments from the user. The arguments are described in Table 39.

Table 39. Perl script arguments
ArgumentDescription
Stream 1 The first stream to use in the comparison. The flow that will be examined is from Stream 1 to Stream 2.
Stream 2 The second stream to use in the comparison.
Location The location in which the directories and files will be created.
Step 1
Create and execute a command to compare the two streams and then store the result in a variable. Split the result into an array that can then be processed.
 
Step 2
For each line of data from the compare command, the change set ID is extracted. This change set is then examined by using the lscm list changes command, and the results are stored in a variable.
 
Step 3
The results from the lscm list changes command are split into an array that can be processed, line by line, to extract the work item information and the change set content (the files to be extracted).
 
Step 4
The work items associated with the change set are displayed.
 
Step 5
For each file to be extracted, the location and filename are separated and the new location (based on the third argument) is constructed. A function is then used to validate the path, because the Rational Team Concert extract command will not create a full path to the file that is to be extracted.
 
Step 6
The appropriate extract command is then generated and executed.
 

The script is available in the Download section.

Summary

The IBM Rational Team Concert SCM command line is extensive and provides opportunities for the creation of repeatable sets of commands in scripts using a variety of scripting techniques.


Download

DescriptionNameSize
Scriptextract_diff_code.zip1KB

Resources

Learn

Get products and technologies

  • Download Rational Team Concert from Jazz.net and try it free on up to 10 projects for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=854929
ArticleTitle=A Rational Team Concert command-line reference for software developers
publish-date=01152013