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 mkwk command. mkwk stands for make workspace and it is inspired in the good-ol ClearCase commands.

Then I go to the new 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 update to latest 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 mkbr 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 current 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 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 find for changes to locate it:

status --all 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 LM stands for locally moved, which means I moved the file outside the 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:

With ci --all I'm basically telling Plastic: detect everything that changed and perform a checkin. And all means: changed files, new files, deleted and moved.

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

Here you see how it shows how 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 my pending changes off and restart 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 unco command:

And now status is:

Which means I'm clean.

Two remarks:

1. The output of the unco command shows not only the files but also the directories that where undone. We just keep this for the sake of completeness at this point.
2. I used the --all modifier which means: undo all changes whether they're real "checkouts" or simply changed files. In Plastic a "changed file" and a "checkedout file" are slightly different and some commands reflect it.

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:

Note that I added the --all modifier again in order to make the unco command work with modified and not checkedout files.

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

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

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 work 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 check it out.
   

2. If you need to work with exclusive-checkouts (locks) then you need to checkout the file first. Check 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. A cm status --all walks through your workspace looking for changes. If you use checkouts then the status just list 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 edit any file.

Now you can see how Bmp.cpp is marked as checked-out instead of just changed.

Files moved using the cm mv command are another form of checkouts as you can see in the following example:

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

I can checkin the two files as follows:

Since I didn't specify the --all modifier in the checkin, the Socket.cs file is still a pending change, but the checkedout files were checkedin:

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

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

Then 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:

All the files that I changed on the branch are now replaced by the ones in main during the update run by the switch command.

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 perform the merge) and the --commentsfile (to add to the new changeset created during the merge operation the comment included in the file) 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 (typically the default Plastic's Xmerge) to solve the conflicts in FileSystem.cs. Please note how FileSystem.cs has been properly moved and renamed and the file contents were correctly merged.

Now if you run a status command, all merged files are in checkout status:

You see new statuses in use now: replaced (RP) which means that the file won't be copied in the version control but just kept as a pointer to the original location in the branch, and then the FileSystem.cs file marked as a real checkout (CO) 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 checkedin.

Now I can simply checkin using the cm ci command:

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

And the Branch Explorer now looks as follows:

Listing the repos on a given server is easy, just use the lrep command:

By default lrep 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 lrep 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).

September 4, 2018

February 26, 2018

August 24, 2015