Easily parse "cm" commands output

  • Updated

Motivation

The "cm" command line tool provides an excellent way to retrieve information from the Plastic SCM server repositories. You can use it ranging from generating reports to develop custom integrations.

For example, our Eclipse plugin [https://www.plasticscm.com/documentation/ides/plastic-scm-version-control-ides-integrations-guide#Chapter2:Eclipseintegration] uses only the "cm" tool to provide excellent support of the Plastic SCM most common used operations inside the IDE.

Because parsing the default output of the "cm" command can be difficult, we created three different parameters to make the task easier:

  • Machine readable.
  • Format
  • XML

Each parameter will help you in different scenarios. If you are looking to develop a plugin, the "machinereadable" parameter will help you a lot. If you need to automate a few "cm" commands, the "--format" parameter will help; and, if you need some information for reporting, you can use the "XML" formatter.

Let me give you more information about each one.

Machine readable parameter

The "machinereadable" parameter formats the "cm" output in a friendly way for developers. We use it for several Plastic SCM plugins; the Eclipse plugin is one of them.

Check out the following list of operations with "--machinereadable" parameter support:

  • Checkin (cm ci)
  • Undo checkout (cm unco)
  • Update (cm update)
  • Get workspace info (cm gwp)
  • List (cm ls)
  • List workspaces (cm lwk)
  • Merge (cm merge)
  • Status (cm status)
  • Lock, Unlock, List locks (cm lock, unlock, listlocks)

Using only the "--machinereadable" parameter, the command output will be much easier to parse than the default command output.  You can go further and make it even easier by using fields and line separators:

  • "--startlineseparator=": Used to locate the start of each line.
  • "--endlineseparator=": Used to locate the end of each line.
  • "--fieldseparator=": Used to separate the line fields.

Check out an example of a "cm" command using all the parameters defined above:

$>cm lwk --machinereadable --startlineseparator="[%NEW_LINE%]" --endlineseparator="[%EOL%]" --fieldseparator="[%FIELD_SEPARATOR%]"
[%NEW_LINE%]codice[%FIELD_SEPARATOR%]c:\wkspaces\codice[%FIELD_SEPARATOR%]BABIECA[%FIELD_SEPARATOR%]57c830d9-f6b3-4f78-9007-109516ff3f72[%EOL%]
[%NEW_LINE%]Tanks2[%FIELD_SEPARATOR%]c:\Users\mluci\wkspaces\Tanks2[%FIELD_SEPARATOR%]BABIECA[%FIELD_SEPARATOR%]858a4ced-e83a-4455-a1bc-1478ae3c61a4[%EOL%]
[%NEW_LINE%]lomweb[%FIELD_SEPARATOR%]c:\Users\mluci\wkspaces\lomweb[%FIELD_SEPARATOR%]BABIECA[%FIELD_SEPARATOR%]4be8701f-1c01-4cdd-ab16-1cf41964ce4a[%EOL%]

Format parameter

The "--format" parameter is present in almost all the "cm" commands, and it's similar to the .NET String format method [https://docs.microsoft.com/es-es/dotnet/api/system.string.format?view=netframework-4.7.2].

You can use it to select and format the fields you need from the "cm" command. Fields separators can be used as well.

Please check out an example if the usage.

$>cm lwk --format="[%NEW_LINE%]WkName:{0}||Machine:{1}||Path:{2}[%END_OF_LINE%]"
[%NEW_LINE%]WkName:codice||Machine:BABIECA||Path:c:\wkspaces\codice[%END_OF_LINE%]
[%NEW_LINE%]WkName:Tanks2||Machine:BABIECA||Path:c:\Users\mluci\wkspaces\Tanks2[%END_OF_LINE%]
[%NEW_LINE%]WkName:lomweb||Machine:BABIECA||Path:c:\Users\mluci\wkspaces\lomweb[%END_OF_LINE%]

Some commands only admit fields with numbers, like the one above using {0}, {1} and {2}. They used to be the first commands we developed; the new ones allow names to easily recognize the fields requested, for example, the "cm ls" command.

$>cm ls --format="[%NEW_LINE%]Name:{name}||Size:{size}[%END_OF_LINE%]"
[%NEW_LINE%]Name:acl||Size:0[%END_OF_LINE%]
[%NEW_LINE%]Name:AclCmd.cs||Size:4973[%END_OF_LINE%]
[%NEW_LINE%]Name:ActivateUserCmd.cs||Size:2425[%END_OF_LINE%]

Now, the brackets contain the field name and not the field index.

Please check out the commands help ("--help" parameter) to know whether you need to use integers or fields names. It will also help you to know which fields are available for each command.

XML

Finally, the XML formatter is useful when you need to get the Plastic SCM data in that specific format. Check out the list of the "cm commands" that support the XML output:
  • Status (cm status)
  • Update (cm update)
  • List (cm ls)
  • Find (cm find)
  • File info (cm fileinfo)
Please check out the examples at [https://www.plasticscm.com/documentation/cmfind/plastic-scm-version-control-query-system-guide#Outputandpost-processingoptions] to learn how to use it.