Plastic SCM CLI guide
Introduction
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.
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 all you need to do is to use the cm workspace create command.
>cm workspace create quakewk quake_path --repository=quake@localhost:6060
Workspace quakewk has been correctly created
Then I go to the newly created directory:
>cd quake_path
>cm status
/main@quake@localhost:6060 (cs:0)
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:
>cm status --head
cs:573@quake@localhost:6060
I can update to latest by simply typing:
>cm update .
The command then will start dumping all the info about the files being copied until I am up-to-date with latest.
>cm status
/main@quake@localhost:6060 (cs:573)
Now I am on the latest changeset: 573 in my case.
Create a new branch and switch to it
Creating a new branch is just a matter of running the cm branch (or cm branch create) command:
> cm branch main/fix-1342
Note that I just created the new branch, but I didn't switch to it yet, as cm status shows:
>cm status
/main@quake@localhost:6060 (cs:573)
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:
> 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 actually didn't update anything on the workspace to do the switch because at this point fix-1342 points to the same cset 573.
Do some changes - edit - checkin workflow
I'm going to edit a file in my workspace and then I'll search for changes to locate it:
>vim code\FileSystem-renamed.cs
>cm status
/main/fix-1342@quake@localhost:8084 (cs:573)
Changed
Status Size Last Modified Path
Changed 80 bytes 6 seconds ago code\FileSystem-renamed.cs
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:
>move code\FileSystem-renamed.cs code\lib\FileSystem.cs
1 file(s) moved.
And I run status to find the moved file:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:573)
Moved
Status Size Similarity Path
Moved locally 86 bytes 99% code\FileSystem-renamed.cs -> code\lib\FileSystem.cs
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:
>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 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.
Note: Please note that I followed a very simple workflow: I just edited the file and then ran 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
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:
>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
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:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
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
All I want is to undo all changes. In order to do that I simply 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
And now my status is:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
Which means I'm clean.
One remark:
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.
As I mentioned, I can restrict the undo to specific change types. I do this by using the filter options:
Suppose I have the same changes as above, but this time I have added and deleted a couple of files:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
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
This time I want to undo the Add and the Remove, but leave the changes untouched. I do this by using 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 my status is:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
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
Just as I wanted.
Undo a single change
What if you just want to undo a single changed file?
I modified a couple of files:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
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
But I only want to undo the changes to cg_main.c
. I'll 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)
Changed
Status Size Last Modified Path
Changed 15.83 KB 50 seconds ago code\cgame\cg_ents.c
Undo changes filtering by path
Now suppose I just need to undo a few changes under certain paths:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
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
I just want 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)
Changed
Status Size Last Modified Path
Changed 12.26 KB 5 minutes ago merge\Socket.cs
I can target the undo even more precisely using wildcards:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
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 I just want 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)
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
Now suppose I want to checkin only certain files on a given path. I have a number of modified files as follows:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:575)
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
But I only want to checkin the ones inside q3radiant\alpha
, so I run the checkin command as follows:
>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 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:
-
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.
- If you need to work with exclusive-checkouts (locks) then you need to checkout files before editing them. Read more about locks here.
- 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.
Checkout-edit-checkin workflow
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.
>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)
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
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:
>cm mv common\aselib.c q3asm
common\aselib.c has been moved to q3asm
>cm status
/main/fix-1342@quake@localhost:8084 (cs:576)
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.
I 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 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:
>cm status
/main/fix-1342@quake@localhost:8084 (cs:577)
Changed
Status Size Last Modified Path
Changed 12.26 KB 5 minutes ago merge\Socket.cs
Merging
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:
>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.
Ok, I can't switch yet because I left my Socket.cs
behind... I'll 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 my workspace, replacing all the files I changed on the branch with the versions in main.
Now my status is as follows:
>cm status
/main@quake@localhost:6060 (cs:573)
Which is also reflected in the Branch Explorer:
I'm going to run the merge command now:
>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
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):
>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:'/')
And now I'm going to 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.
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:
>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
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:
>cm status
/main@quake@localhost:6060 (cs:578)
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 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:
>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
Labelling the newly merged code just involves running the cm label command as follows:
>cm label BL612 cs:579
And the Branch Explorer now appears as follows:
List the available repos
Listing the repos on a given server is easy, just 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 then 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 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.
>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
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:
>cm status
/main@quake@localhost:6060 (cs:578)
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
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:
>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)
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
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.
>cm shelveset src\experimental_changes
Uploading file data
Confirming checkin operation
Modified src\experimental_changes
Created shelve sh:25@myrepo@localhost:8080 (mount:'/')
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.
>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.
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:
>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.
Commands that accept piped paths like this are
- add
- applylocalchanges
- checkin
- checkout
- getstatus
- partialcheckin
- remove
- shelveset create
- undocheckout
- undochange
- uncounchanged
- wktreenodestatus
Now there's nothing stopping you building cool scripts using pipe and cm together!
Last updated
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.