Example scm commands

The Engineering Workflow Management source control command line interface (CLI) uses the scm command, followed by one or more subcommands. Example commands are scm help and scm create workspace.

Aliases are short names that uniquely identify items in source control. Aliases are four digit long numbers (in brackets ) that are displayed to the left of the item they refer to. For example:

$ lscm show status 
 Workspace: (6377) "My Workspace" <-> (7487) "Stream"
   Component: (6429) "Flux Capacitor"
     Baseline: (8471) 6815 "v20091102"
       Change sets:
		(8459) ---@ 98314 "Degauss Flux Capacitor" - <No comment>

In the example above, each number in brackets (6377, 7487, 6429, 8471, 8459) is an alias.

Each subcommand has a set of return codes. 0 is returned if the subcommand succeeded. Nonzero is returned when there is an error or problem, such as a conflict, or the local sandbox is out of sync with the remote workspace.

Logging in to the repository

The following examples assume you have logged in to a repository with lscm login.

$ lscm login -r https://your.repository.com:9443/ccm -n nickname -u echughes -c
Password (echughes @ https://your.repository.com:9443/ccm):           
Logged in to https://your.repository.com:9443/ccm

You can also refer to the repository https://your.repository.com:9443/ccm with a nickname. For example, pass -r nickname to the subcommand instead of the URL, username, and password.

Getting started

Before you begin a project, you must have a username, password, and the URL of your repository. You should also be a member of a team area.

Locating streams

If you do not know the name of the stream that you are collaborating with, you can use lscm list streams -r nickname to list the streams you have access to. For example:

$ lscm -a y list streams -r l
(1009) DeLorian Upgrades
(1010) Home Energy Converter
(1011) Doc Brown's playpen

Creating and loading a workspace

After you have found the stream that you want to work in, you can create a remote workspace to contain your changes. For example:

$ lscm create workspace -r l myNewWorkspace -s "DeLorian Upgrades"
Workspace (8551) "myNewWorkspace" successfully created

Adding the -s parameter specifies which stream the workspace should collaborate with. The new workspace has that stream as the default flow target, and has the stream's state as its initial state.

To load the remote workspace:

$ lscm load myNewWorkspace -r l
Downloading /flux.capacitor/requirements.txt  (0 B)
Downloading /flux.capacitor/diagrams/design.cad  (0 B)

Working independently

From the source control CLI, you can follow a typical workflow, such as modify files, check in files, accept new changes, and deliver changes.

The CLI check-in and deliver actions are the same as in the Eclipse client. Check-in pushes changes from your local disk to a remote workspace; deliver pushes changes from a remote workspace to stream.

Committing changes

In the following CLI example, you modify several files and determine what was modified by running status:

$ lscm show status
Workspace: (8551) "myNewWorkspace" <-> (8552) "DeLorian Upgrades"
  Component: (8553) "Flux Capacitor"
    Baseline: (8554) 1 "Initial Baseline"
      -c- /flux.capacitor/requirements.txt
      Change sets:
        (8555) ---$ "Initial CAD"

The status command scans all of the shared directories for changes, which can take a long time. If you only want to view how your remote workspace compares to the stream, you can run lscm show status –n, which ignores the local disk scan.

To commit changes, use lscm checkin:

$ lscm checkin flux.capacitor/
Workspace: (8551) "myNewWorkspace" <-> (8552) "DeLorian Upgrades"
  Component: (8553) "Flux Capacitor"
      Change sets:
        (8556) ---@ <No comment>

This example implicitly creates a new change set. The change sets that received files and folders during the commit are listed in the output.

After the change set is created, you can associate it with a work item and add a comment. To assign a work item, use lscm changeset associate. To set the comment, use lscm changeset comment.

Accepting changes

You can periodically view the status of your workspace by running lscm show status:

$ lscm show status -C
Workspace: (8551) "myNewWorkspace" <-> (8552) "stream19_test_max_results_1256765247692134"
  Component: (8553) "Flux Capacitor"
    Baseline: (8554) 1 "Initial Baseline"
      Change sets:
        (8556) ---@ 
            ---c- /flux.capacitor/requirements.txt
      Change sets:
        (8615) ---$ "Initial layout"
            ---c- /flux.capacitor/diagrams/design.cad

The -C flag shows the contents of change sets.

In the example above, there is a single incoming change to design.cad. You can accept this change because it does not modify any of the files in the outgoing change sets.

Run lscm accept:

$ lscm accept -v
Repository: https://hostname.example.com:9443/ccm/
  Workspace: (8551) "myNewWorkspace"
    Component: (8553) "Flux Capacitor"
      Change sets:
        (8615) ADMIN ---$ "Initial layout" 
            ---c- /flux.capacitor/diagrams/design.cad

Resolving conflicts

Occasionally, incoming changes modify files that you have already modified.

In the example below, you modify flux.capacitor/requirements.txt to include a note from a planning meeting, check the file in, and run status:

$ lscm show status -C
Workspace: (8551) "myNewWorkspace" <-> (8552) "stream19_test_max_results_1256765247692134"
  Component: (8553) "Flux Capacitor"
    Baseline: (8554) 1 "Initial Baseline"
      Change sets:
        (8617) -!-@ "Update from November planning meeting"
            !--c- /flux.capacitor/requirements.txt
      Change sets:
        (8616) -!-$ "Results of initial trials"
            !--c- /flux.capacitor/requirements.txt

A collision has occurred. The files that you modified were also modified by another user who delivered changes to the stream. The collision is noted by the ! in front of the participating files and the participating change sets. When you accept the change set with the alias 8616, you have a conflict.

$ lscm accept 8616 -v -i
Repository: https://hostname.example.com:9443/ccm/
  Workspace: (8551) "myNewWorkspace"
    Component: (8553) "Flux Capacitor"
      Change sets:
        (8616) ADMIN --#$ "Results of initial trials" 
            -#-c- /flux.capacitor/requirements.txt
Following workspaces still have conflicts after accept:
Run 'scm resolve' or 'scm conflicts' or 'scm status' for help in resolving the conflicts.

The -i inserts conflict markers into files. The markers are similar to markers that are used by other source control systems.

The # in the list of changes indicates the file has a conflict.

You can get a list of conflicts in the currently loaded sandbox by running scm conflicts.

The file contains in-place conflict markers, indicating the problem:

- Must not need any more than 1.5 gigawatts of power
- Determine minimum necessary speed
<<<<<<< mine
  - Twin Pines parking lot?
  - Initial trials suggest 60kmh
>>>>>>> proposed

The line between the <<<<<<< mine and the equals sign is from the change set in your workspace. The line between the equals signs and the >>>>>>> proposed is from the incoming change set. You can get the original file by running lscm conflicts -m flux.capacitor/requirements.txt. If you want to get the incoming version, you can run lscm conflicts -p flux.capacitor/requirements.txt. The -m is a short form for mine and the -p is a short form for proposed.

Resolve the change with the proposal. Clear the conflict markers out of the file:

- Must not need any more than 1.5 gigawatts of power
- Determine minimum necessary speed
Initial trials suggest 60kmh

Commit the change and communicate to the repository that the conflict has been resolved with the version that was checked in by running lscm resolve conflict:

lscm resolve conflict -c flux.capacitor/requirements.txt

No output indicates that the conflict has been resolved.

The -c indicates that the conflict should be resolved with the version that is checked in. You can also use -p to resolve with the proposed version.

You can now make more changes, or deliver the change set with lscm deliver:

$ lscm deliver
Delivering changes from "myNewWorkspace" into "DeLorian Updates"
  No baselines to flow.

Working with changes

To determine who modified certain lines of a file, run lscm annotate:

$ lscm annotate flux.capacitor/requirements.txt 
1 Marty (8556) 2009-11-04 02:47 PM                    - Must not need any more than 1.5 gigawatts of power 
2 Marty (8556) 2009-11-04 02:47 PM                    - Determine minimum necessary speed 
3 Doc   (8616) 2009-11-04 02:47 PM Results of initial t - Initial trials suggest 60kmh 

The output of annotate has six columns:

  • Line numbers. For example: 1
  • Person who created the change set. For example: Marty
  • Alias of the change set. For example: 8556
  • Date. For example: 2009-11-04
  • Change set comment. For example: Results of initial t
  • Line from file. For example: - Must not need any more than 1.5 gigawatts of power

To compare different versions of a file, use scm diff, which generates a standard patch.

To delete uncommitted changes, use scm undo.

Releng tasks

This section describes advanced commands that are primarily used by administrators who configure Engineering Workflow Management source control for other users. Most users only create and load workspaces off of existing streams.

Adding a new component

A component is a grouping of source trees that keeps logical groupings of source code together.

As a project grows, you occasionally need to add new source trees. If it does not make sense for an existing component to hold the changes, then you need to add a new component:

$ lscm create component "Flux Capacitor" "DeLorian Upgrades" -r l
Component (8553) "Flux Capacitor" successfully created.

In the example above, you created a new component in the stream DeLorian Upgrades. Users who have workspaces collaborating with that stream see the component addition as an incoming change. When they accept the incoming changes, the users receive the content in the component.

If a user wants to add new files into the component created for that purpose, the user can perform this task with the share subcommand. Engineering Workflow Management source control only allows directories and folders to be shared into a workspace. The user must add the new component into a remote workspace:

$ lscm add component -r l myNewWorkspace 8553
Component (8553) "Flux Capacitor" successfully added.

In the example above, the alias 8553 refers to the newly created component from the previous example.

The new component is now in the workspace, so the user must share the source tree into the workspace:

$ lscm share -r l myNewWorkspace 8553 flux.capacitor
Uploading files...
Shared successfully

In the example above, the action uploads the contents of the directory flux.capacitor to the remote workspace named myNewWorkspace and adds it into the component specified by 8553, which is the Flux Capacitor from the previous step.

Listing component changes between two baselines

This example describes how to list all the files that have changed in a component between two baselines. To only list the files (hide component and change set information), use -I f.

lscm compare -r miles baseline v20101025 baseline v20101018b -c Filesystem -I f