The definitive guide to "find"

The definitive guide to "find"

Thursday, February 23, 2012 Pablo Santos 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! :)

Pablo Santos

I'm the CTO and Founder at Códice.
I've been leading Plastic SCM since 2005. My passion is helping teams work better through version control.
I had the opportunity to see teams from many different industries at work while I helped them improving their version control practices.
I really enjoy teaching (I've been a University professor for 6+ years) and sharing my experience in talks and articles.
And I love simple code. You can reach me at @psluaces.