The definitive guide to "find"

Thursday, February 23, 2012 7 Comments

Motivation

We designed the “cm find” as a SCM query language able to solve almost any query in SQL-like format but avoiding direct queries to the underlying database system and hence avoiding difficult and long joins.
It has been there for years, and years, and years... but only the advanced plastikers knew about it... now is the time to open up the Pandora's box! :)
This post will help learning the possibilities of the “find” functionality which is available through the “cm find” command and also in the GUI through the “advanced” panel on most of the views.

What can you use “find” for?

“find” is great for scripting your own tools, but it is also great for customizing your UI with simple but very powerful queries.

The very basics

There are a few things to keep in mind when dealing with “find”:
  • Where are the fields? You can find all the “searchable” fields running “cm showfindcommands
  • How can I format the output? If you’re on the CLI, you can format your output with –format=”{field} {field2}”

    Useful “finds” to start with

    Let’s go through some useful queries:
  • All the branches I created: cm find branch where owner=’pablo’
  • The first “trick”: cm find branch where owner=’me’. “me” will be replaced by the user invoking the query, quite useful as default configuration for some “views” in the GUI. Yo can try it from the “advanced” panel at the branches view as: find branch where owner=’me’
  • Another trick: doing it more “English like”: find branches where owner=’me’
  • Branches you created since the beginning of 2010: find branches where date >= ‘2010/01/01’
  • Finding all the branches you created with changes (important WITH changes) since the beginning of Feb 2012: find branches where owner='me' and changesets >='2012/02/01'. The field “changesets” does the trick. It actually hides a “join” (for the SQL guys out there) with the “changeset” table.
  • Let’s try again with “all the changes I created THIS month”: find branches where owner='me' and changesets >='this month'

    Ok, now that you’re curious about what you can type on the “date” fields, here’s the entire list of available keywords: today, yesterday, "thisweek, "this week", "thismonth", "this month", "this year”, “this year","onedayago", "one day ago", "oneweekago", "one week ago", "onemonthago", "one month ago"

    And now the ones to be used with a number like find branches where changesets >= “10 days ago”: "daysago", "days ago", "monthsago", "months ago", "yearsago", "years ago"
    Enough for today! :)

  • 7 comments:

    1. WoW!!

      A few days ago I asked a question just like that in the forum!

      I wanted to know how can I find branches that have more than 2 days!

      Plastic is perfect!! :D

      ReplyDelete
    2. This post is titled "The definitive guide to find" but it only shows a few examples. Where are the syntax rules and keyword listing?

      Thanks.

      Greg

      ReplyDelete
    3. Hi

      I assume the command:

      cm showfindcommands

      should read:

      cm showfindObjects

      ReplyDelete
    4. Hi

      I assume the command:

      cm showfindcommands

      should read:

      cm showfindObjects

      ReplyDelete
    5. You're right: should be ShowFindObjects.

      ReplyDelete
    6. What is the query for the "branches with pending integrations" conditional format rule? I'd like to get a list of branches that are not merged to main branch.

      ReplyDelete
    7. What is the query for the "branches with pending integrations" conditional format rule? I'd like to get a list of branches that are not merged to main branch.

      ReplyDelete