Plastic SCM CLI guide


Introduction

Plastic SCM is a visual version control system. But, it can also be used from the command line.

This guide walks you step by step through common command line interface (CLI) scenarios to help you get familiar with Plastic.

Remember, you can always get more info about all the commands using cm help command_name.

Run the cm help objectspec command to learn about the definition of the different object specs supported by Plastic.


Create a new workspace

To create a new workspace, use the cm workspace create command.

>cm workspace create quakewk quake_path --repository=quake@localhost:6060 Workspace quakewk has been correctly created

Then, go to the newly created directory:

>cd quake_path >cm status /main@quake@localhost:6060 (cs:0 - head)

Which is still on changeset 0 because there hasn't been an update yet. By default, the workspace is configured to use the branch main.

You can check what the latest changeset on the branch is by running cm status --head:

>cm status --head cs:573@quake@localhost:6060

You can update to the latest changeset by simply typing:

>cm update

The command then will start dumping all the info about the files being copied until it's up-to-date with latest changeset.

>cm status /main@quake@localhost:6060 (cs:573 - head)

573 in this case.


Create a new branch and switch to it

To create a new branch, run the cm branch (or cm branch create) command:

> cm branch main/fix-1342

As cm status shows, the current branch hasn't been switched to yet:

>cm status /main@quake@localhost:6060 (cs:573 - head)

Since a starting point hadn't been specified, the new branch starts from the latest changeset on the parent branch, in this case, cset 573 at main. You can use the --changeset and --label modifiers to specify a given changeset or label to start the branch from.

Switch the workspace to the branch by using the switch command:

> cm switch main/fix-1342 Performing switch operation... Searching for changed items in the workspace... Setting the new selector... Plastic is updating your workspace. Wait a moment, please... The workspace c:\Users\pablo\wkspaces\quake_path is up-to-date (cset:573@quake@localhost:6060)

The new branch is still empty, so Plastic didn't update anything on the workspace to do the switch because fix-1342 points to the same cset 573.


Do some changes - edit - checkin workflow

To edit a file in your workspace and search for changes to locate it:

>vim code\FileSystem-renamed.cs >cm status /main/fix-1342@quake@localhost:8084 (cs:573 - head) Changed Status Size Last Modified Path Changed 80 bytes 6 seconds ago code\FileSystem-renamed.cs

status shows not only the wk configuration (as shown before) but also the files changed, checked-out, moved, deleted, and so on.

To move FileSystem-renamed.cs to a new location:

>move code\FileSystem-renamed.cs code\lib\FileSystem.cs 1 file(s) moved.

Run status to find the moved file:

>cm status /main/fix-1342@quake@localhost:8084 (cs:573 - head) Moved Status Size Similarity Path Moved locally 86 bytes 99% code\FileSystem-renamed.cs -> code\lib\FileSystem.cs

Where Moved locally means the file was moved outside of Plastic control, but it is able to find the moved file because it is still 99% similar to the previous version.

Then I can checkin my change easily:

>cm ci --all The selected items are about to be checked in. Please wait ... Assembling checkin data Validating checkin data Uploading file data Uploaded 0 bytes of 2.77 KB (0%) Confirming checkin operation Modified c:\Users\pablo\wkspaces\quake_path\code Modified c:\Users\pablo\wkspaces\quake_path\code\lib Modified and moved from c:\Users\pablo\wkspaces\quake_path\code\FileSystem-renamed.cs to c:\Users\pablo\wkspaces\quake_path\code\lib\FileSystem.cs Created changeset cs:575@br:/main/fix-1342@quake@localhost:6060 (mount:'/')

The default ci command checks in all added files. With ci --all you're telling Plastic: detect everything that changed and perform a checkin. And all means: files that are changed, deleted or moved. We can also include private files by using ci --all --private.

Note: This is a very simple workflow: Editing the file and running a checkin. This is the typical edit-checkin workflow made popular by version controls like SVN and Git.

Plastic SCM also supports the checkout-edit-checkin workflow.


Check the history with log and diff

The cm log command shows the changes made on a given cset or in a specific cset range:

>cm log cs:575 Changeset number: 575 Branch: /main/fix-1342 Owner: pablo Date: 7/18/2015 19:41:29 Comment: Changes: C code\lib\FileSystem.cs M code\lib\FileSystem.cs

In the last changeset checked in, the file FileSystem.cs was modified and moved.

The command cm diff does something similar, but it is always limited to a given cset:

>cm diff cs:575 C "code\lib\FileSystem.cs" M "code\FileSystem-renamed.cs" "code\lib\FileSystem.cs"

Clean up all changes in the workspace

You can throw away all your pending changes and start from scratch.

Check the current status:

>cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 49.23 KB 2 hours ago code\bsp-renamed.c Changed 23.42 KB 2 hours ago code\cgame\cg_drawtools.c Changed 61.23 KB 8 minutes ago libs\cmdlib.h Changed 398 bytes 7 minutes ago libs\str.h

To undo changes, run the undo command recursively:

>cm undo -r c:\Users\pablo\wkspaces\quake_path\libs\str.h unchecked out correctly c:\Users\pablo\wkspaces\quake_path\libs\cmdlib.h unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\cgame\cg_drawtools.c unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\bsp-renamed.c unchecked out correctly

The current status with no changes:

>cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head)

Note:

  • By default, undo applies to all changes, whether they're real "checkouts" or simply changed files, but you can limit the undo to specific change types. In Plastic, a "changed file" and a "checkedout file" are slightly different, and some commands reflect that.

    You can restrict the undo to specific change types by using the filter options:

    Suppose you have the same changes as above, but this time, you have added and deleted a couple of files:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 49.23 KB 2 hours ago code\bsp-renamed.c Changed 23.42 KB 2 hours ago code\cgame\cg_drawtools.c Changed 61.23 KB 9 minutes ago libs\cmdlib.h Changed 398 bytes 8 minutes ago libs\str.h Deleted Status Size Path Removed 12.41 KB code\bsp-temp.c Added Status Size Last Modified Path Added 4.42 KB 17 seconds ago code\bsp-experimental.c

    To undo the Add and the Remove, but leave the changes untouched, use the filters:

    >cm undo --added --deleted -r c:\Users\pablo\wkspaces\quake_path\code\bsp-experimental.c unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\bsp-temp.c unchecked out correctly

    And now the status is:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 49.23 KB 2 hours ago code\bsp-renamed.c Changed 23.42 KB 2 hours ago code\cgame\cg_drawtools.c Changed 61.23 KB 10 minutes ago libs\cmdlib.h Changed 398 bytes 9 minutes ago libs\str.h

  • Undo a single change

    What if you just want to undo a single changed file?

    Here, a couple of files have been modified:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 15.83 KB 50 seconds ago code\cgame\cg_ents.c Changed 35.27 KB 30 seconds ago code\cgame\cg_main.c

    To only undo the changes to cg_main.c, run the following command:

    >cm undo code\cgame\cg_main.c c:\Users\pablo\wkspaces\quake_path\code\cgame\cg_main.c unchecked out correctly >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 15.83 KB 50 seconds ago code\cgame\cg_ents.c

    Undo changes filtering by path

    You can undo a few changes under certain paths:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 15.83 KB 50 seconds ago code\lib\be_aas_cluster.c Changed 35.27 KB 5 minutes ago code\cgame\cg_ents.c Changed 73.15 KB 5 minutes ago code\cgame\cg_localents.c Changed 62.62 KB 5 minutes ago code\renderer\tr_cmds.c Changed 12.26 KB 5 minutes ago merge\Socket.cs

    To undo the changes under code but leave the one under merge:

    >cm unco code -r c:\Users\pablo\wkspaces\quake_path\code\renderer\tr_cmds.c unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\cgame\cg_localents.c unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\cgame\cg_ents.c unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\lib\be_aas_cluster.c unchecked out correctly

    And now the status is as expected:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 12.26 KB 5 minutes ago merge\Socket.cs

    You can target the undo even more precisely using wildcards:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 15.83 KB 4 minutes ago code\lib\be_aas_cluster.c Changed 3.14 KB 4 minutes ago code\lib\be_aas_cluster.h Changed 35.27 KB 8 minutes ago code\cgame\cg_ents.c Changed 3.24 KB 2 minutes ago code\cgame\cg_ents.h Changed 73.15 KB 8 minutes ago code\cgame\cg_localents.c Changed 6.14 KB 2 minutes ago code\cgame\cg_localents.h Changed 62.62 KB 8 minutes ago code\renderer\tr_cmds.c Changed 1.98 KB 2 minutes ago code\renderer\tr_cmds.h Changed 12.26 KB 8 minutes ago merge\Socket.cs

    This time, to undo the header files under code but leave the source files:

    >cm unco code\*.h -r c:\Users\pablo\wkspaces\quake_path\code\renderer\tr_cmds.h unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\cgame\cg_localents.h unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\cgame\cg_ents.h unchecked out correctly c:\Users\pablo\wkspaces\quake_path\code\lib\be_aas_cluster.h unchecked out correctly

    And now the status is as expected:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 15.83 KB 5 minutes ago code\lib\be_aas_cluster.c Changed 35.27 KB 9 minutes ago code\cgame\cg_ents.c Changed 73.15 KB 9 minutes ago code\cgame\cg_localents.c Changed 62.62 KB 9 minutes ago code\renderer\tr_cmds.c Changed 12.26 KB 9 minutes ago merge\Socket.cs

    Checkin changes inside a given path

    You can checkin specific modified files on a given path:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:575 - head) Changed Status Size Last Modified Path Changed 12.26 KB 5 minutes ago merge\Socket.cs Changed 42.26 KB 5 minutes ago q3radiant\alpha\osf\tst\sort.sbk Changed 86.27 KB 5 minutes ago q3radiant\alpha\osf\tst\spill.2bk Changed 85.27 KB 5 minutes ago q3radiant\alpha\osf\tst\spill.sbk Changed 34.26 KB 5 minutes ago q3radiant\alpha\osf\tst\stdarg.1bk Changed 34.26 KB 5 minutes ago q3radiant\alpha\osf\tst\stdarg.2bk Changed 34.26 KB 5 minutes ago q3radiant\alpha\osf\tst\stdarg.sbk

    To only checkin the ones inside q3radiant\alpha, run the checkin command:

    >cm ci q3radiant\alpha\* -c "osf files checked in" --all The selected items are about to be checked in. Please wait ... Assembling checkin data Validating checkin data Uploading file data Uploaded 0 bytes of 14.53 KB (0%) Uploaded 0 bytes of 14.53 KB (0%) Uploaded 0 bytes of 14.53 KB (0%) Uploaded 0 bytes of 14.53 KB (0%) Uploaded 0 bytes of 14.53 KB (0%) Uploaded 0 bytes of 14.53 KB (0%) Confirming checkin operation Modified c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\sort.sbk Modified c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.2bk Modified c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.sbk Modified c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.1bk Modified c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.2bk Modified c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.sbk Created changeset cs:576@br:/main/fix-1342@quake@localhost:6060 (mount:'/')

    Changed vs checkedout

    In Plastic SCM, files can be changed, or they can be checked out. Hence you can follow two workflows: edit-checkin or checkout-edit-checkin.

    Checking out a file just means telling Plastic "hey, I'm going to modify the file" so it adds the file to an internal list of checked out files.

    There are 3 main reasons to work with checkouts:

    1. You're used to working this way because you come from Perforce (p4 edit) or ClearCase (checkout). If you work this way, chances are that you also like setting all your files as read-only in your workspace as some sort of "protection" so that the filesystem will warn you if you modify a file before checking it out.

      Set files as readonly

    2. If you need to work with exclusive checkouts (locks), you need to checkout files before editing them. Read more about locks here.
    3. If you're working on a huge codebase (>500k files), you might use checkouts to speed up all operations. cm status walks through your workspace looking for changes. If you use checkouts, the status command lists the files in the checkout list, no disk access is required.

    Checkout-edit-checkin workflow

    Working in checkout-edit-checkin fashion is simple: run a cm co command before editing any file.

    >cm co q3radiant\Bmp.cpp The selected items are about to be checked out. Please wait ... Item q3radiant\Bmp.cpp was correctly checked out >cm status /main/fix-1342@quake@localhost:8084 (cs:576 - head) Changed Status Size Last Modified Path Changed 12.26 KB 5 minutes ago merge\Socket.cs Checked-out 12.21 KB 65 minutes ago q3radiant\Bmp.cpp

    Bmp.cpp is marked as checked-out instead of just changed.

    Files moved using the cm mv command are considered to be another form of checked-out, as you can see in the following example:

    >cm mv common\aselib.c q3asm common\aselib.c has been moved to q3asm >cm status /main/fix-1342@quake@localhost:8084 (cs:576 - head) Changed Status Size Last Modified Path Changed 12.26 KB 5 minutes ago merge\Socket.cs Checked-out 12.21 KB 65 minutes ago q3radiant\Bmp.cpp Moved Status Size Similarity Path Moved 88 bytes common\aselib.c -> q3asm\aselib.c

    You see that aselib.c is not "locally moved" but simply moved.

    You can checkin the two checked-out files as follows:

    >cm ci -c "changed bmp and moved aselib" The selected items are about to be checked in. Please wait ... Assembling checkin data Validating checkin data Uploading file data Uploaded 0 bytes of 9.26 KB (0%) Confirming checkin operation Modified c:\Users\pablo\wkspaces\quake_path\q3radiant\Bmp.cpp Modified c:\Users\pablo\wkspaces\quake_path\common Modified c:\Users\pablo\wkspaces\quake_path\q3asm Move from c:\Users\pablo\wkspaces\quake_path\common\aselib.c to c:\Users\pablo\wkspaces\quake_path\q3asm\aselib.c Created changeset cs:577@br:/main/fix-1342@quake@localhost:6060 (mount:'/')

    Since the --all modifier hadn't been specified in the checkin, only the checked-out files were checked-in, and the Socket.cs file is still a pending change:

    >cm status /main/fix-1342@quake@localhost:8084 (cs:577 - head) Changed Status Size Last Modified Path Changed 12.26 KB 5 minutes ago merge\Socket.cs

    Merging

    Merging from the CLI is straightforward: run the cm merge command.

    So far, changes were made in the main/fix-1342 branch, so they'll be merged in the main branch.

    Status prior to cli merge

    Switch to main:

    >cm switch main Performing switch operation... Searching for changed items in the workspace... Cannot perform the switch to branch/label/changeset since there are pending changes. Please review the pending changes and retry the operation again.

    The switch can't happen because the Socket.cs file is left behind. You would undo the change first and try to switch again:

    >cm undo merge\Socket.cs c:\Users\pablo\wkspaces\quake_path\merge\Socket.cs unchecked out correctly >cm switch main Performing switch operation... Searching for changed items in the workspace... Setting the new selector... Plastic is updating your workspace. Wait a moment, please... Downloading block of 8 files (26.57 KB) Copied c:\Users\pablo\wkspaces\quake_path\q3radiant\Bmp.cpp Copied c:\Users\pablo\wkspaces\quake_path\code\FileSystem-renamed.cs Copied c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\sort.sbk Copied c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.2bk Copied c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.sbk Copied c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.1bk Copied c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.2bk Copied c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.sbk

    The switch command updates the workspace, replacing all the files changed on the branch with the versions in main.

    Now the status is as follows:

    >cm status /main@quake@localhost:6060 (cs:573 - head)

    Which is also reflected in the Branch Explorer:

    Status prior to cli merge on main

    Run the merge command:

    >cm merge main/fix-1342 The file /q3radiant/Bmp.cpp#cs:577 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/sort.sbk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/spill.2bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/spill.sbk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.1bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.2bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.sbk#cs:576 was modified on source and will replace the destination version The file /code/lib/FileSystem.cs#cs:575 was modified on source and will replace the destination version The item /common/aselib.c has been moved to /q3asm/aselib.c on source and will be moved as result of the merge The item /code/FileSystem-renamed.cs has been moved to /code/lib/FileSystem.cs on source and will be moved as result of the merge

    Merging without any modifier just prints a preview of what's going to be merged so it is very useful to understand what is going to happen.

    In order to make the merge more interesting, the FileSystem-renamed.cs file is modified (it was moved and renamed on the branch):

    >cm co code\FileSystem-renamed.cs The selected items are about to be checked out. Please wait ... Item code\FileSystem-renamed.cs was correctly checked out >vim code\FileSystem-renamed.cs >cm ci code\FileSystem-renamed.cs The selected items are about to be checked in. Please wait ... Assembling checkin data Validating checkin data Uploading file data Uploaded 0 bytes of 2.82 KB (0%) Confirming checkin operation Modified c:\Users\pablo\wkspaces\quake_path\code\FileSystem-renamed.cs Created changeset cs:578@br:/main@quake@localhost:6060 (mount:'/')

    Re-run the merge and add a comment:

    >cm merge main/fix-1342 -c="Added changes and fixes to the interface" The file /q3radiant/Bmp.cpp#cs:577 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/sort.sbk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/spill.2bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/spill.sbk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.1bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.2bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.sbk#cs:576 was modified on source and will replace the destination version The item /common/aselib.c has been moved to /q3asm/aselib.c on source and will be moved as result of the merge The item /code/FileSystem-renamed.cs has been moved to /code/lib/FileSystem.cs on source and will be moved as result of the merge The file /code/FileSystem-renamed.cs needs to be merged from cs:575 to cs:578 base cs:573. Changed by both contributors.

    In the last line, FileSystem-renamed.cs now needs a 3-way merge since it was modified by the two contributors.

    Run the merge adding the --merge (to actually perform the merge), and the --commentsfile (to set the new changeset's comment from the file content) modifiers to the merge command:

    >cm merge main/fix-1342 --merge --commentsfile=comment-merge-fix-1342.txt The file /q3radiant/Bmp.cpp#cs:577 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/sort.sbk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/spill.2bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/spill.sbk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.1bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.2bk#cs:576 was modified on source and will replace the destination version The file /q3radiant/alpha/osf/tst/stdarg.sbk#cs:576 was modified on source and will replace the destination version The item /common/aselib.c has been moved to /q3asm/aselib.c on source and will be moved as result of the merge The item /code/FileSystem-renamed.cs has been moved to /code/lib/FileSystem.cs on source and will be moved as result of the merge The file /code/FileSystem-renamed.cs needs to be merged from cs:575 to cs:578 base cs:573. Changed by both contributors. Merging c:\Users\pablo\wkspaces\quake_path\q3asm\aselib.c c:\Users\pablo\wkspaces\quake_path\common\aselib.c has been moved to c:\Users\pablo\wkspaces\quake_path\q3asm\aselib.c Merging c:\Users\pablo\wkspaces\quake_path\code\lib\FileSystem.cs c:\Users\pablo\wkspaces\quake_path\code\FileSystem-renamed.cs has been moved to c:\Users\pablo\wkspaces\quake_path\code\lib\FileSystem.cs Merging c:\Users\pablo\wkspaces\quake_path\q3radiant\Bmp.cpp The revision c:\Users\pablo\wkspaces\quake_path\q3radiant\Bmp.cpp@cs:577 has been loaded Merging c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\sort.sbk The revision c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\sort.sbk@cs:576 has been loaded Merging c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.2bk The revision c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.2bk@cs:576 has been loaded Merging c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.sbk The revision c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.sbk@cs:576 has been loaded Merging c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.1bk The revision c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.1bk@cs:576 has been loaded Merging c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.2bk The revision c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.2bk@cs:576 has been loaded Merging c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.sbk The revision c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.sbk@cs:576 has been loaded Merging c:\Users\pablo\wkspaces\quake_path\code\lib\FileSystem.cs Merge done

    Plastic applies all merges to the workspace, and it launches the 3-way merge tool you've configured (by default, Plastic's Xmerge) to solve the conflicts in FileSystem.cs. Note how FileSystem.cs has been properly moved and renamed and that the file contents were correctly merged.

    Now, if you run a status command, all merged files are in a checked-out status:

    >cm status /main@quake@localhost:6060 (cs:578 - head) Pending merge links Merge from cs:577 at /main/fix-1432@test@localhost:8084 Changed Status Size Last Modified Path Checked-out (Merge from 577) 41.32 KB 6 hours ago code\lib\FileSystem.cs Replaced (Merge from 577) 42.26 KB 6 hours ago q3radiant\alpha\osf\tst\sort.sbk Replaced (Merge from 577) 86.27 KB 6 hours ago q3radiant\alpha\osf\tst\spill.2bk Replaced (Merge from 577) 85.27 KB 6 hours ago q3radiant\alpha\osf\tst\spill.sbk Replaced (Merge from 577) 34.26 KB 6 hours ago q3radiant\alpha\osf\tst\stdarg.1bk Replaced (Merge from 577) 34.26 KB 6 hours ago q3radiant\alpha\osf\tst\stdarg.2bk Replaced (Merge from 577) 34.26 KB 6 hours ago q3radiant\alpha\osf\tst\stdarg.sbk Replaced (Merge from 577) 12.21 KB 6 hours ago q3radiant\Bmp.cpp Moved Status Size Similarity Path Moved 14.41 KB code\FileSystem-renamed.cs -> code\lib\FileSystem.cs Moved 88 bytes common\aselib.c -> q3asm\aselib.c

    You see new statuses in use now: Replaced which means that, for efficency, rather than copy the file in version control, a pointer to the original location on the branch is stored, and then the FileSystem.cs file marked as a real Checked-out since it was merged.

    At this point, the Branch Explorer looks like this:

    Status after merge before ci

    The dashed-line means the merge is still in progress and it is not yet checked-in.

    Now you can simply check-in using the cm ci command:

    >cm ci -m "merged from fix-1342" The selected items are about to be checked in. Please wait ... Assembling checkin data Validating checkin data Uploading file data Uploaded 0 bytes of 2.80 KB (0%) Confirming checkin operation Modified c:\Users\pablo\wkspaces\quake_path\common Modified c:\Users\pablo\wkspaces\quake_path\q3asm Move from c:\Users\pablo\wkspaces\quake_path\common\aselib.c to c:\Users\pablo\wkspaces\quake_path\q3asm\aselib.c Modified c:\Users\pablo\wkspaces\quake_path\code Modified c:\Users\pablo\wkspaces\quake_path\code\lib Modified and moved from c:\Users\pablo\wkspaces\quake_path\code\FileSystem-renamed.cs to c:\Users\pablo\wkspaces\quake_path\code\lib\FileSystem.cs Modified c:\Users\pablo\wkspaces\quake_path\q3radiant Replaced c:\Users\pablo\wkspaces\quake_path\q3radiant\Bmp.cpp Replaced c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\sort.sbk Replaced c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.2bk Replaced c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\spill.sbk Replaced c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.1bk Replaced c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.2bk Replaced c:\Users\pablo\wkspaces\quake_path\q3radiant\alpha\osf\tst\stdarg.sbk Created changeset cs:579@br:/main@quake@localhost:6060 (mount:'/')

    Applying a label

    To label the newly merged code, run the cm label command:

    >cm label BL612 cs:579

    And the Branch Explorer now appears as:

    Status after label


    List the available repos

    To listing the repos on a given server, use the repository [list] command:

    >cm repository codice@localhost:6060 pnunit@localhost:6060 nervathirdparty@localhost:6060 quake@localhost:6060

    By default repository shows the repos in the default server, which is the server you configure in your config wizard and is written in your client.conf:

    > type client.conf <ClientConfigData> <Language>en</Language> <WorkspaceServer>localhost:6060</WorkspaceServer> <WorkingMode>UPWorkingMode</WorkingMode> <SecurityConfig>pablo:dM629yb8hWO6qD+8jAqaag==</SecurityConfig> <CurrentWorkspace>c:\Users\pablo\wkspaces\four</CurrentWorkspace> <MergeTools> <MergeToolData> <FileExtensions>.cs</FileExtensions> <Tools> ...

    The repository list command is extremely helpful to diagnose connection issues with your server because you can also type different servers as follows:

    >cm repository list tube:dianaserver@codice.es --format=TABLE 4 codice tube:dianaserver@codice.es 4_1 codice/unitymerge tube:dianaserver@codice.es 5 pnunit tube:dianaserver@codice.es 6 nervathirdparty tube:dianaserver@codice.es 6_1 nervathirdparty/yamldotnet tube:dianaserver@codice.es 6_2 nervathirdparty/yamldotnet_buildutils tube:dianaserver@codice.es 35 licensetools tube:dianaserver@codice.es 55 plasticscm.com tube:dianaserver@codice.es 64 indexertest tube:dianaserver@codice.es 1741 tts tube:dianaserver@codice.es

    List the available workspaces

    Plastic SCM keeps a list of the workspaces you have on your machine (at least the ones it knows about because you can always copy a workspace from somewhere and Plastic will not have it on the list).

    >cm workspace list codebase@MODOK c:\Users\pablo\wkspaces\four doc@MODOK c:\Users\pablo\wkspaces\doc mkt@MODOK c:\Users\pablo\wkspaces\marketing quakecode@MODOK c:\Users\pablo\wkspaces\testwkspaces\quakewk codicediana@MODOK c:\Users\pablo\wkspaces\codicediana

    Getting help

    This guide is just a small piece of all the things you can do with the CLI. To find out what other commands are available, you can run cm showcommands.

    Also, all commands come with built-in documentation of their options cm <command> --usage, and comprehensive help with examples cm <command> --help

    There may be an occasion when the CLI isn't behaving as you expect, and you want to get in touch with our wonderful support team. To help them diagnose your issue, you can send them a zip-file full of useful diagnostic information, which you can generate using the cm support command as follows.

    >cm support bundle c:\supportbundle.zip Creating a new support bundle... Adding clientinfo.txt... Adding clientprocessinfo.txt... Adding client.conf... Adding filetypes.conf... Adding guiclient.conf... Adding mergetool.conf... Adding plastic.uisettings.conf... Adding plasticgui.conf... Adding syncviews.conf... Adding logs\plastic.debug.log.txt... Adding logs\plastic.relevant.log.txt... Support bundle created at c:\supportbundle.zip CommandResult 0

    Local changes

    A script has been run which has made a bunch of changes to the source files, including a local move and delete. The status looks like this:

    >cm status /main@quake@localhost:6060 (cs:578 - head) Deleted Status Size Path Removed locally 34.26 KB q3radiant\alpha\osf\tst\stdarg.sbk Moved Status Size Similarity Path Moved locally 88 bytes 100% q3asm\aselib.c -> q3asm\aselib_fixed.c

    To bring these changes under source control, now that the files have moved or been deleted, run the move or remove commands and create controlled changes:

    >cm remove q3radiant\alpha\osf\tst\stdarg.sbk Item q3radiant\alpha\osf\tst\stdarg.sbk has been removed. >cm move q3asm\aselib.c -> q3asm\aselib_fixed.c q3asm\aselib.c has been moved to q3asm\aselib_fixed.c >cm status /main@quake@localhost:6060 (cs:578 - head) Deleted Status Size Path Removed 34.26 KB q3radiant\alpha\osf\tst\stdarg.sbk Moved Status Size Similarity Path Moved 88 bytes q3asm\aselib.c -> q3asm\aselib_fixed.c

    Shelving changes

    When working on some experimental code changes, you may want to save them in source control and share them with teammates, but you don't want to check them into any branch because they are experimental.

    In this situation, use the shelveset command to, in effect, commit a changeset not associated with any branch.

    >cm shelveset src\experimental_changes Uploading file data Confirming checkin operation Modified src\experimental_changes Created shelve sh:25@myrepo@localhost:8080 (mount:'/')

    To get back those experimental changes, use the apply subcommand to apply the shelveset to my workspace.

    >cm shelveset apply sh:25 The item /newtonraphson.cs#sh:25 has been added on source and will be added as result of the merge Merging \src\experimental_changes\newtonraphson.cs The revision \src\experimental_changes\newtonraphson.cs@sh:25 has been loaded

    Using pipe

    An often overlooked feature of the Plastic CLI is that it can read arguments from stdin one-by-one, using the - option, like this:

    >cm add - a.txt b.txt c.txt The selected items are about to be added. Please wait ... Item c:\Users\pablo\wkspaces\mcga\a.txt was correctly added Item c:\Users\pablo\wkspaces\mcga\b.txt was correctly added Item c:\Users\pablo\wkspaces\mcga\c.txt was correctly added >cm ci - a.txt b.txt c.txt The selected items are about to be checked in. Please wait ... \ Checkin finished 12 bytes/12 bytes [##################################] 100 % Modified c:\mcga Added c:\Users\pablo\wkspaces\mcga\a.txt Added c:\Users\pablo\wkspaces\mcga\b.txt Added c:\Users\pablo\wkspaces\mcga\c.txt Created changeset cs:22@br:/main@test@localhost:8084 (mount:'/') >cm rm - a.txt Item a.txt has been removed. b.txt Item b.txt has been removed. c.txt Item c.txt has been removed.

    This is useful because it means you can pipe output from other commands into cm.

    The following commands accept piped paths:

    • add
    • applylocalchanges
    • checkin
    • checkout
    • getstatus
    • partialcheckin
    • remove
    • shelveset create
    • undocheckout
    • undochange
    • uncounchanged
    • wktreenodestatus

    • You can pipe from the Windows dir command to easily remove all files matching a pattern from my workspace: >dir /S /B *.txt | cm rm - Item c:\Users\pablo\wkspaces\mcga\a.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\b.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\c.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\z.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\lockwkB\file.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\src_dir\dest_dir\a.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\src_dir\dest_dir\b.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\src_dir\dest_dir\c.txt has been removed.
    • The checkout command can recurse into piped directory arguments: Directory of c:/mcga/pipe 11/05/2020 19:48 <DIR> . 11/05/2020 19:48 <DIR> .. 11/05/2020 17:57 <DIR> dir 11/05/2020 19:46 <DIR> dir2 11/05/2020 19:47 12 dirlist 1 File(s) 12 bytes 4 Dir(s) 23,714,631,680 bytes free c:/mcga/pipe>type dirlist dir dir2 c:/mcga/pipe>type dirlist | cm partial co -r - The selected items are about to be checked out. Please wait ... Item c:/mcga/pipe/dir was correctly checked out Item c:/mcga/pipe/dir/file was correctly checked out Item c:/mcga/pipe/dir2 was correctly checked out Item c:/mcga/pipe/dir2/file2 was correctly checked out

    Now there's nothing stopping you building cool scripts using pipe and cm together!


    Last updated

    June 10, 2020
  • In the Using pipe chapter, you can now find an example about how the checkout command can recurse into piped directory arguments.
  • June 08, 2020
  • We edited the cm status examples because its output now includes the head changeset by default.
  • January 21, 2020
  • Now, it's possible to update the whole current workspace without specifying any path .
  • May 16, 2019
  • We added a section about using pipe with the Plastic CLI.
  • March 26, 2019
  • We updated the examples of how to undo changes to use the new cm undo command.
  • May 14, 2019
  • We replaced the references to deprecated workspace administration commands like cm mkwk with their new counterparts.
  • March 22, 2019
  • We replaced the references to deprecated repository administration commands like cm lrep with their new counterparts.
  • We edited the chapter Create a new branch and switch to it to replace the deprecated cm mkbr command with cm branch.
  • March 21, 2019
  • We updated a section about shelving changes using the cm shelveset command.
  • March 13, 2019
  • We changed a reference to cm mklabel to cm label inline with the new label related commands in the CLI.
  • February 8, 2019
  • We updated the output of cm status throughout the guide to reflect the new output format and changes to the options.
  • We edited the Create a new workspace chapter to show you how to use cm status --head to view the head changeset.
  • We added a new chapter Getting help to show you how to use cm support to generate diagnostic information.
  • We added a new chapter Local changes to show you how to use cm mv and cm rm to bring local changes under source control.
  • We shortened a few paths in the examples to improve readability.
  • September 4, 2018
  • We edited the Merging chapter to show you how to include comments (-c and --commentsfile modifiers) during the merge operation.
  • February 26, 2018
  • Run the cm help objectspec command to learn about the definition of the different object specs supported by Plastic.
  • August 24, 2015
  • The cm log and cm diff examples have been updated: now these commands print the workspace root relative paths by default, instead of the full workspace paths.
  • Improved format string for lrep and lwk commands.