Cm find by example

In every version control system, we frequently need to get usage information about what files are being changed or just searching for a specific change or a specific branch.

The best way of achieving this is by using queries. So when we created Plastic SCM, we added a very powerful query system called cm find, a command that allows you to get specific information involving changesets, branches, labels, merges, code reviews, and more.

The find command can also be used to customize views in the GUI.

This guide covers (with examples) some scenarios that can be handled with the cm find command. They are a small subset of what you can do in your Plastic SCM installation. Each example includes a question, a step-by-step solution, and the expected output to help you understand what kind of information is returned.

We can retrieve the branches created by a user in a specific period, and then we can filter by a specific attribute.

We start retrieving all the branches available:

We only want our branches, so we filter by user:

After filtering by user, we now want only the branches related to this sprint, so we are looking for the ones created after a specific date:

You can use a formatted output:

Finally, we look for a specific attribute. According to our internal feature lifecycle, each branch must pass tests before integrating it on the main branch.

When a branch passes the test, the "test" attribute will be set to "passed," and so, we filter by attribute name and by attribute value:

The following table displays the different filtering options that are currently available to be used with cm find branch command:

* Condition date corresponds to Creation date column in the Branches view.

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find branch command:

You can find a lot of info for the changesets, and the comments are just one of those. For quick info, you can use cm log and do your own filtering (using shell commands) or let cm find to do the job for you.

This example shows the date and comment for all the changesets that belong to a branch:

Here are all the changesets, for example, you're looking for the word "solution." Here we can easily see it, but it becomes harder to spot when you have a couple of hundred changesets. For filtering by a specific word, use the SQL-syntax LIKE and % for an approximate search because you're not looking for the complete comments:

You can also query the changesets by replication date, using the following command (see replication log on how to get the last replication date):

returnparent allows you to get the parent of a specific changeset or revision. That way, if you want to know what happened before the changeset you can use:

The following table displays the different filtering options that are currently available to be used with cm find changeset command:

* Conditions changesetid, date, and owner correspond to Name , Creation date and Created by columns respectively in the Changesets view.

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find changeset command:

Given a branch, you can get all the replication operations from any time chronologically.

If you only want the last date, you can filter by date and select the last row using PowerShell or bash.

PowerShell:

Bash:

Result:

The following table displays the different filtering options that are currently available to be used with cm find replicationlog command:

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find replicationlog command:

You can find all the labels in a specific repository:

And you can find all the labels that created in specific branch in a particular repository:

You may want to find which branch contains a specific release:

In the above example, the label BL237 comes from the main branch.

You can get the label's date, and later ask for the changesets created in that timespan in that branch. Getting the information for two (or more) labels is very simple:

The following table displays the different filtering options that are currently available to be used with cm find label command:

* Condition date corresponds to Creation date column in the Labels view.

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find label command:

The attributes can be applied to branches, changesets, and labels, without any distinction. The first thing you need is the object Id. You can get it by specifying the id when querying for a branch:

Once you have it, you can get the attribute list with the following commands:

In this case, the attribute name is "status", and the attribute value is "Passed".

You can combine these two commands using some PowerShell scripting:

Or bash scripting:

The output will be the same as before:

And you will get the same output by running the following query:

Let's suppose you set a specific attribute to some objects (in this case, the test "status"). You can query for these attributes, no matter the object that contains it.

The following table displays the different filtering options that are currently available to be used with cm find attributes command:

* Conditions date and type correspond to Creation date and Name columns respectively in the Attributes view.

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find attributes command:

With a specific changeset retrieved in the previous sample, you may want to know more about the files that have changes in it, and for that purpose you may use find revision.

You use a custom format, because you only want the file and folder paths:

You could also filter by folder with some command line help (grep on Linux, and where on Windows PowerShell):

PowerShell:

Bash:

Then the output would be something like this:

You can also get the revision info for a branch, searching in all its changesets. You can start by getting all the changed items from a branch and a time span:

Later you can use our favourite shell tool, in our case Powershell, to filter that info.

If you prefer bash, this is your line:

The expected output looks like this:

The following table displays the different filtering options that are currently available to be used with cm find revisions command:

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find revisions command:

It's possible to track the merges from and to a specific branch or changeset.

If you want to know where a branch has been integrated on, type the following command:

And if you want to know which branches are integrated in a specific branch, the command is:

The previous commands can also use our format flags to customize the output by returning only the branch names, that way, for example, the second command would become something like this:

Or:

Remember that find merge returns all types of merges: regular merges, cherrypicked merges, and subtractive merges.

So you can get interval merges to a given branch:

You can do this with two queries (find branches, find merge) and some PowerShell hacking. Place this code on a PS1 file and run it from your PowerShell console:

Here is a sample output:

This code performs the following actions:

1. Find all the branches from this sprint.
2. Find all the merges from this sprint, and return only the source branches.
3. Change the format of the $allbranches output so both lists have the same format.
4. Check if the "merges" list contains the branches from the allBranches list. If it doesn't, the branch is not integrated.

An equivalent code in bash shell would be the following:

This code does the following:

1. Finds every branch belonging to this sprint.
2. Finds every merge belonging to this sprint, returning only their source branches.
3. Print all branches from this sprint that weren't on the merged branches list.

We are looking for this scenario:

We want those branches that have been integrated into another branch (so we must discard merges into the same branch) but have changesets pending to integrate (the orange cset on the picture), and yes, we can do it with a single query, and then some post-processing with some Powershell code:

Here is a sample output:

This code performs the following actions:

1. Get all the merges and the source changeset done after a specific date.
2. Filter those merges that have the same origin and destination.
3. Get a list only with the merges for discarding those already merged.
4. Changes the format of the find branches output so it matches the find merge format.
5. Compare, and filter those branches merged on that interval but have pending changesets to merge.

If you are using bash, here's an alternative:

What you've just done:

1. Write all merges on a file, indicating source changeset, performed after a specific date; at the same time, write all source merge branches on a different file.
2. Iterating on all existing branches by branch name and changeset, print only those that don't appear on the first file (merge source branch and changeset) but do appear on the second one (meaning that there are pending changesets to merge).
3. Finally, delete the temporary files.

For example, you want to know which branches have been integrated into version 1.0, directly or indirectly. As before, you only need one single query to the server and some more PowerShell to filter the data. In this specific example, you want to get all the branches that have been integrated into /main.

Here is a sample output, You can see that the branch 12299 is indirectly integrated in the release 4.3.39.406

A brief explanation of the script:

1. You get the list and remove the duplicates as before.
2. You call the ListAll function with the target branch, an empty visited list, and a marker that will help display the depth. The output of this function is piped to null because you won't use this value in the code: Otherwise it would display.
3. Inside the ListAll function, you try to find a merge which target matches the target window.
4. If it matches, you add the item to the visited list, and you call ListAll recursively, the time with our merge source.
5. After the recursive function returns, you update the visited list based on the function's return value.

An equivalence under bash can be done with the following script:

A brief explanation for this script:

1. You get the list of merges, remove duplicate entries, and store it into a file.
2. You prepare two auxiliary files:
   1. old_targets, which will save every target branch you find
   2. targets, which will contain the target branches whose sources you are looking for
3. You now proceed to look if the target branches exist on the list file as destinations. If so, you will store the merge source branch for the next round if it has not been affected before. Also, you will print it on screen.
4. You increase the depth level and you switch the target list: The new list of targets became the current list of targets, and the current list is added to the "already used" list.
5. Finally, only a clean-up operation remains to leave the environment as it was.

The following table displays the different filtering options that are currently available to be used with cm find merge command:

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find merge command:

The integrated code review feature allows you to get information about the status of a review. In this example, start getting 'my' reviews (the ones assigned literally to 'me' where 'me' is the current user). You can also put a user's name like previous examples.

Afterwards, you can scope the result to those reviews that have a specific status (1 = approved):

Finally, you find reviews in a specific time frame:

So you want to compare it with the ones that have this specific span and this specific condition:

With these two queries, you could get a ratio of approved/all reviews on this sprint.

The following table displays the different filtering options that are currently available to be used with cm find review command:

* Conditions date and targetid correspond to Creation date and Reviewed object columns respectively in the Code reviews view.

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find review command:

You can get the shelves that are created by your team members during the last year:

The following table displays the different filtering options that are currently available to be used with cm find shelve command:

Learn how to filter by date using constants.

This table displays the different output options that are currently available to be used with cm find shelve command:

In this guide, you've seen how to customize the output, but you can also set the output as XML and save it to a file for later analysis:

Generates the following XML content:

<?xml version="1.0" encoding="utf-8" ?>
<PLASTICQUERY>
  <REVISION>
    <ID>426098</ID>
    <COMMENT></COMMENT>
    <DATE>07/06/2013 16:00:09</DATE>
    <OWNER>roberto</OWNER>
    <TYPE>dir</TYPE>
    <SIZE>0</SIZE>
    <CHANGESET>16716</CHANGESET>
    <PARENT>426069</PARENT>
    <ITEM>d:\linked_replicated\</ITEM>
    <ITEMID>2</ITEMID>
    <BRANCH>br:/main/Fix-4.1/scm12863</BRANCH>
    <PATH>d:\linked_replicated\</PATH>
    <REPOSITORY>codice</REPOSITORY>
    <REPNAME>codice</REPNAME>
    <REPSERVER>localhost:8087</REPSERVER>
    <HASH>kWJO1fm+7RCiZZcgSjM4/Q==</HASH>
  </REVISION>
  <REVISION>
    <ID>426092</ID>
    <COMMENT></COMMENT>
    <DATE>07/06/2013 16:00:09</DATE>
    <OWNER>roberto</OWNER>
    <TYPE>txt</TYPE>
    <SIZE>78238</SIZE>
    <CHANGESET>16716</CHANGESET>
    <PARENT>426056</PARENT>
    <ITEM>d:\linked_replicated\01nerva\src\client\plastic\ActionMenuManager.cs</ITEM>
    <ITEMID>37736</ITEMID>
    <BRANCH>br:/main/Fix-4.1/scm12863</BRANCH>
    <PATH>d:\linked_replicated\01nerva\src\client\plastic\ActionMenuManager.cs</PATH>
    <REPOSITORY>codice</REPOSITORY>
    <REPNAME>codice</REPNAME>
    <REPSERVER>localhost:8087</REPSERVER>
    <HASH>FXmLNV7B9Et1wTGqULWpgQ==</HASH>
  </REVISION>
</PLASTICQUERY>
  

This content can be later imported into tools like Excel.

Suppose you want to get the information of all the changesets in our repository. You can execute the following command:

You can then load the output in Excel; this is the result:

Excel includes a very useful utility called PivotTable that allows us to get more statistics.

Using the filtering and sorting features available in Excel, you can get the group the changesets user and convert those stats into graphs:

You can also group by branch, and you could get, grouping by branch, how many users have contributed, and how many changesets have been created by each user, on each branch.

The find command has a default output for each object, but you can define your custom output options as seen before, retrieve the result using XML format with the --xml attribute, and save the result in a file with the --file attribute for later analysis.

The general syntax is the following:

Where:

• object can be almost every object in the system, having branch, attribute, changeset, label, merge, review, revision, and user.
• The filtering conditions depend on the object. You can get the conditions (and all the objects you can use) by typing the command cm showfindobjects.
• The on repositories argument can be used to get information from one or more repositories that may, or may not, match the current workspace. You can go to any folder (inside our workspace, in another workspace or in a folder without workspace) and type: cm find revisions "where branch = 'main/scm12800' on repositories 'codice@localhost:8087'" --nototal 423620 27/05/2013 13:25:53 dirRoberto d:\linked_replicated\#br:/main/scm12800#16582 423621 27/05/2013 13:25:53 dirRoberto d:\linked_replicated\01nerva#br:/main/scm12800#16582 423622 27/05/2013 13:25:53 dirRoberto d:\linked_replicated\01nerva\src#br:/main/scm12800#16582

  This will work as long as you have the authorization to query that repository.

  You can query together from not only different repositories but also different servers. For example

  cm find "changesets where date >= '2017/11/17' on repositories 'documentation/plasticdocu@localhost:8087','codice@codice@cloud'" --nototal 68621 1451 /main/scm21135 11/20/2017 3:32:31 PM maria documentation/plasticdocu Added documentation about the EOL conversion mechanism. 4821759 132324 /main/SCM21120 11/20/2017 1:41:45 PM pablo codice Added missing config file 4821840 132326 /main/scm21149/scm21150 11/20/2017 1:54:35 PM vsanchezm@codicesoftware.com codice Fix HAL FAILED - Conflicts and user intervention required. Rebase from main. 4821941 132333 /main 11/20/2017 2:38:28 PM hal codice HAL: merged /main/scm21076/scm21084/scm21093 : GTK Gluon: add pending changes view
• The sort options lets you get the objects ordered by the specified field. Read more about sorting.
• The pagination options can be used to manage the result size and the starting point where retrieving the objects from. See more about pagination.
• format options allows you to specify the output options (for example, --format , --xml or --file as you saw previously, among some other options).

When filtering by date, you can use date formats that follow your machine localization settings. For example, if your computer displays dates in the 'MM-dd-yyyy' format, you can use dates such as '12-31-2021' in your queries.

You can also use the following constants to simplify your queries:

• 'today': today's date.
• yesterday': yesterday's date.
• this week': current week's Monday date.
• this month': current month's 1st day date.
• this year': current year's January 1st date.
• one day ago': one day before the current date.
• one week ago': seven days before the current date.
• one month ago': one month before the current date.
• n days ago': 'n' days before the current date.
• n months ago': 'n' months before the current date.
• n years ago': 'n' years before the current date.

The following where clauses are valid for fields of type date:

• (...) where date > 'today' (...)
• (...) where date < 'yesterday' (...)
• (...) where date > 'this week' (...)
• (...) where date > 'this month' (...)
• (...) where date < 'one day ago' and date > '3 days ago' (...)
• (...) where date < 'one week ago' and date > '3 weeks ago' (...)
• (...) where date < 'one month ago' and date > '3 months ago' (...)
• (...) where date > '1 year ago' (...)

Every find object complies with pagination, defining a limit and an offset to manage the result size and starting point.

For example:

• Display 10 labels starting from the 21st where I am the owner: cm find label "where owner='me'" limit 10 offset 20
• Display the first 10 branches created by me: cm find branches "where owner='me'" limit 10

You can sort some objects by different fields. This way, the order by clause can be used with the following objects and some of its fields:

For example:

• Find my changesets and order the results by date in descendant order: cm find changesets "where owner='me'" order by date desc 4336 203 /main 10/8/2021 3:48:10 PM mbarriosc@codicesoftware.com battlegame reverted 4332 202 /main 10/8/2021 3:16:29 PM mbarriosc@codicesoftware.com battlegame Lighter shadow 4328 201 /main 10/8/2021 3:08:22 PM mbarriosc@codicesoftware.com battlegame Reverted
• Find all branches between two dates, sorting by the branch name in descendant order: cm find branch "where date > '2022/01/01' and date < '2022/01/05'" order by branchname desc 28781097 1/3/2022 7:36:49 PM /main/SCM31425 borja.ruiz@unity3d.com codice T 28780726 1/3/2022 12:03:54 PM /main/scm31423 miguel.gonzalez@unity3d.com codice T 28781122 1/4/2022 4:01:09 PM /main/scm31415 jesusmg codice T 28780724 1/3/2022 10:29:24 AM /main/scm31371 alvaro.berruezo@unity3d.com codice T 28781091 1/3/2022 5:30:43 PM /main/scm30759 alvaro.berruezo@unity3d.com codice T

March 14, 2022

• Added a note to highlight this guide is about cm find examples with some and not all of the available objects.

March 14, 2022

• The cm find command now supports pagination and sorting.

December 10, 2019

• We fixed some cm find examples by adding missing double-quotes.

December 7, 2018

• We added some new examples.
• Learn how to find shelves.
• You can use date constanst when filtering by date.

November 20, 2017

• Learn how to use the on repositories argument to query from one or more repositories.

July 1, 2014

• Publication date.