Using Plastic SCM command line for automation
Plastic SCM offers a rich command line client able to automate all the operations, making it perfect for automating daily tasks. In this article I'll try to show some of the most common uses.
Piping
One nice thing of the Plastic command line is that all item-related commands accept standard input, so it is very easy to pipe series of commands. For instance, let's say I modified some files without checking them out. I can use the command
cm fc -R | cm co -
to find the changed items (cm findchanged), recursing from the current directory (-R) and pipe the output to the checkout command. The '-' tells 'checkout' to pick the items to check out from the standard input. Also it is nice that the checkout command didn't touch the content of the files, so their changes are safely preserved.
Now, to find the elements that were checked out and check them in with a single command line:
cm fco --format={4} | cm ci -
Here I used the powerful --format modifier, telling that I want fco (find checkouts) to print only the 4th column of the output, which is the item name, and pipe that into checkin. If I needed to supply comments to that changeset, the command would be:
cm fco --format={4} | cm ci - -c="New interface methods have been implemented"
Format is very useful to adapt the output of any Plastic command to whatever is needed, specially for parsing in scripts or piping to other command like in the sample. I will talk a bit more about format in the next section.
The --format argument
Almost all Plastic commands support the --format modifier that allows formatting the output to suit most situations. Format picks a string as argument in which column indexes specified between brackets are replaced by the column contents. Each command returns a different set of columns, so the column indexes vary for each of them. Usually a cm help command will show the available columns.
Here are some samples of commands with customized output. To show all checked out items (by all users, --all), printing user and item:
C:\scm3\01nerva>cm fco --all --format="user: '{1}' item: '{4}'"
...
user: 'dave' item: 'c:\test\01nerva\src\plastic\controller\commands\GuiCommand.cs'
user: 'johnp' item: 'c:\codicetesting\01nerva\src\server\securitymanager\SecurityManager.cs'
...
To recursively add all the items in a given directory to the current repository, first issue a 'find private' command (cm fp) and pipe the output to the add command, making sure to checkout the parent directory so that items can be added.
cm fp -R | cm add --coparent -
The find command
An incredible amount of information can be retrieved with the find command, which is the portal for the query system in Plastic. Every object in the system can be queried, so for instance to get a list of changesets in the last month, I will use:
C:\scm3\01nerva>cm find "changesets where date > '2008/04/24'"
...
4013265 16617 03/06/2008 10:33:22 danipen codice Problem in the client configuration
4013435 16618 03/06/2008 13:34:23 ruben codice Print "ALREADY CHECKED OUT" in co command.
4013523 16619 03/06/2008 13:48:24 danipen codice Cache cleaning in SCC Plugin
4013524 16620 03/06/2008 13:48:45 danipen codice Skeleton for NetBeans plugin
4013575 16621 03/06/2008 13:49:37 ruben codice /main/SCM3571 rebased lb:BL104
Total: 707
I used "" to escape '>' in the shell. So I got the output splitted in columns. This is useful, but wouldn't it be nice to get this in XML so I can import it into excel and make some charts? No problem, 'find' supports the --xml modifier:
C:\scm3\01nerva>cm find "changesets where date > '2008/04/24'" --xml
<PLASTICQUERY>
...
<CHANGESET>
<ID>4013524</ID>
<CHANGESETID>16620</CHANGESETID>
<COMMENT>Skeleton for NetBeans plugin</COMMENT>
<DATE>03/06/2008 13:48:45</DATE>
<OWNER>danipen</OWNER>
<REPNAME>codice</REPNAME>
</CHANGESET>
<CHANGESET>
<ID>4013575</ID>
<CHANGESETID>16621</CHANGESETID>
<COMMENT>/main/SCM3571 rebased lb:BL104</COMMENT>
<DATE>03/06/2008 13:49:37</DATE>
<OWNER>ruben</OWNER>
<REPNAME>codice</REPNAME>
</CHANGESET>
</PLASTICQUERY>
The find command can also be used to filter objects with applied attributes. Here, find all the branches that have a 'Status' attribute with value 'Pending':
cm find branches where attribute='Status' and attrvalue='Pending'
Even, you could go the quick way, and find the branch with an attribute value of 'Pending', however you should be carefull as values can be used in different attributes!
cm find branches where attrvalue='Pending'
Now let's go for some custom format. get the files in a changeset:
C:\scm3\01nerva>cm find revisions where changeset = 13451
3596263 04/10/2007 16:24:00 txt 13451 dave c:\scm3\01nerva\src\plastic\controller\commands\MarkerCommands.cs#br:/main/scm2252#1 Implemented apply label
3596268 04/10/2007 16:24:02 txt 13451 dave c:\scm3\01nerva\src\plastic\model\GUIMarker.cs#br:/main/scm2252#0 Implemented apply label
3596270 04/10/2007 16:24:00 txt 13451 dave c:\scm3\01nerva\src\plastic\BranchCache.cs#br:/main/scm2252#1 Implemented apply label
3596768 04/10/2007 16:24:01 txt 13451 dave c:\scm3\01nerva\src\plastic\model\GUIItemHelper.cs#br:/main/scm2252#0 Implemented apply label
3597033 04/10/2007 16:24:02 txt 13451 dave c:\scm3\01nerva\src\plastic\model\GUIItem.cs#br:/main/scm2252#4 Implemented apply label
Total: 5
By default 'find' will print all the columns of the given object (here, revision). I want to get just the names of the items in the changeset, so let's see what columns I can retrieve on the revision object:
C:\scm3\01nerva>bcm showfindobjects
Available objects and attributes:
...
REVISION
attribute
attrvalue
branch
changeset
comment
date
id
item
itemid
label
marker
...
I see there is an 'item' attribute, so I will use the format modifier in the find command to print just that column. The find command also accepts the --format option but it uses a simplified syntax in this case, where the column name is used instead of the index (more useful in my opinion, the format of all commands should work this way). I will also use the --nototal modifier so the total count is not printed at the end of the command:
C:\scm3\01nerva>cm find revisions where changeset=13451 --format={item} --nototal
c:\scm3\01nerva\src\plastic\controller\commands\MarkerCommands.cs
c:\scm3\01nerva\src\plastic\model\GUIMarker.cs
c:\scm3\01nerva\src\plastic\BranchCache.cs
c:\scm3\01nerva\src\plastic\model\GUIItemHelper.cs
c:\scm3\01nerva\src\plastic\model\GUIItem.cs
Conclusion
Plastic SCM provides with a command line interface that offers a lot of interesting capabilities. Combined with scripting most repetitive tasks can be easily automated and together with triggers many different development workflows can be enforced, but that will the subject for another article.
