Plastic SCM CLI guide

Plastic SCM is a visual version control system. But, it is also meant to 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.

To create a new workspace all you need to do is to use the cm workspace create command.

Then I go to the newly created directory:

Which means I'm still on changeset 0 because I didn't run an update yet. By default the workspace is configured to use the branch main.

I can check what the lastest changeset on the branch is by running cm status --head:

I can update to latest by simply typing:

The command then will start dumping all the info about the files being copied until I am up-to-date with latest.

Now I am on the latest changeset: 573 in my case.

Creating a new branch is just a matter of running the cm branch (or cm branch create) command:

Note that I just created the new branch, but I didn't switch to it yet, as cm status shows:

Since I didn't specify a starting point, the new branch simply starts from the latest changeset on the parent branch, in my case cset 573 at main. I can use the --changeset and --label modifiers to specify a given changeset or label to start my branch from.

Now I'm going to switch the workspace to the branch by simply using the switch command:

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

I'm going to edit a file in my workspace and then I'll search for changes to locate it:

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

Now I'm going to move FileSystem-renamed.cs to a new location:

And I run status to find the moved file:

Where Moved locally means I moved the file 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:

The default ci command checks in all added files. With ci --all I'm basically 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.

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

Here you see how it shows that in the last changeset I checked in I modified and moved the file FileSystem.cs.

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

After working for a while trying some experimental changes I decide to throw away all my pending changes and start from scratch. How I do that?

Check my current status now:

All I want is to undo all changes. In order to do that I simply run the undo command recursively:

And now my status is:

Which means I'm clean.

One remark:

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

I modified a couple of files:

But I only want to undo the changes to cg_main.c. I'll run the following command:

Now suppose I just need to undo a few changes under certain paths:

I just want to undo the changes under code but leave the one under merge:

And now the status is as expected:

I can target the undo even more precisely using wildcards:

This time I just want to undo the header files under code but leave the source files:

And now the status is as expected:

Now suppose I want to checkin only certain files on a given path. I have a number of modified files as follows:

But I only want to checkin the ones inside q3radiant\alpha, so I run the checkin command as follows:

In Plastic SCM files can be simply 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 prior to checking it out.
   

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

Working in checkout-edit-checkin fashion is quite simple: all you have to do is to run a cm co command prior to editing any file.

Now you can see that 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:

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

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

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

Merging from the CLI is quite easy, all you have to do is run the cm merge command.

So far I was making all the changes in the main/fix-1342 branch, so I'll switch to main to merge my changes. My situation at this point is as follows:

I'll switch to main:

Ok, I can't switch yet because I left my Socket.cs behind... I'll undo the change first and try to switch again:

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

Now my status is as follows:

Which is also reflected in the Branch Explorer:

I'm going to run the merge command now:

Merge 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 I'm going to modify FileSystem-renamed.cs (remember it was moved and renamed on the branch):

And now I'm going to re-run the merge and add a comment:

As you can see in the last line, FileSystem-renamed.cs now needs a 3-way merge since it was modified by the two contributors.

Now I'll 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:

As you can see, it 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. Please 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:

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 my Branch Explorer looks like this:

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

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

Labelling the newly merged code just involves running the cm label command as follows:

And the Branch Explorer now appears as follows:

Listing the repos on a given server is easy, just use the repository [list] command:

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:

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

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 then Plastic will not have it on the list).

This guide gives just a teste 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 a more 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.

I've just run a script which has made a bunch of changes to my source files, including a local move and delete. My status now looks like this:

How can I bring these changes under source control, now that the files have moved or been deleted? It's not a problem. We can just run the move or remove commands and create controlled changes:

I am working on some experimental code changes, and I want save them in source control, and maybe share them with my colleagues, but I don't want to check them in to any branch because they are just an idea I'm trying out.

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

I have shelved my local changes on the repository. I switch my branch to another workspace and continue working as normal. Later, I want to get back those experimintal changes I was working on. To do this I use the apply subcommand to apply the shelveset to my workspace.

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

Why is this useful? Because it means we can pipe output from other commands into cm.

For example, I can pipe from the Windows dir command to easily remove all files matching a pattern from my workspace:

Commands that accept piped paths like this are

1. add
2. applylocalchanges
3. checkin
4. checkout
5. getstatus
6. partialcheckin
7. remove
8. shelveset create
9. undocheckout
10. undochange
11. uncounchanged
12. wktreenodestatus

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

January 21, 2020

May 16, 2019

March 26, 2019

May 14, 2019

March 22, 2019

March 21, 2019

March 13, 2019

February 8, 2019

September 4, 2018

February 26, 2018

August 24, 2015