Syntax
Understand the syntax for your cm find queries.
Refer to the following information on how to format your cm find queries:
- You can use either singular or plural to find an object. For example, you can use either
cm find branchorcm find branches. - All
cm findqueries are case sensitive. - In the command line, the shell considers comparison operators (
>,<,>=,<=) as IO redirections so you need to enclose the queries with quotation marks:cm find branches "where owner='pablo' and changesets >= '2013/03/01'"- The PowerShell console escapes the double (") quotes by default so you need to put an extra pair of quotes to specify you want them inside the command:
cm find replicationlog where branch = "'/semanticmain'" --format="{date}" --nototal | select -Last 1
- The PowerShell console escapes the double (") quotes by default so you need to put an extra pair of quotes to specify you want them inside the command:
General syntax
The following example shows the general syntax:
cm find object "[where conditions] [on repositories]"
[sort options] [pagination options]
[format options]| Parameter | Description |
|---|---|
object | Find almost any object in the system, such as a branch, attribute, changeset, label, merge, review, revision, and user. To view available objects, use the command cm showfindobjects. |
filtering conditions | The filtering conditions depend on the object. To retrieve the conditions, and available objects, use the command cm showfindobjects. |
sort options | Order the objects by a specified field. |
pagination options | Manage the result size and specify the starting point to retrieve objects. |
format options | Specify output preferences, such as --format, --xml, or --file. Refer to the Microsoft documentation on width formatting for strings. |
on repositories | Retrieve information from one or more repositories or servers, regardless of their match with the current workspace. You can use this argument from any folder or workspace context if you have the authorization to query that repository. |
Date constants
To filter by date, use date formats that follow your machine localization settings. For example, if your computer displays dates in the MM-dd-yy format, you can use a date such as 12-31-2021 in your queries.
The following constants are available for you to use to simplify your queries:
| Constant | Description |
|---|---|
today | Today's date. |
yesterday | Yesterday's date. |
this week | Current week's Monday date. |
this month | The first day of the current month. |
this year | The first day of the current year. |
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' (...)
Note: You can also use the between operator. For example, where date between '3 days ago' and 'one day ago'.
Pagination
Use pagination to define a limit and an offset to manage the result size and starting point:
| Parameter | Description |
|---|---|
limit | The amount of results that you want to receive. Note: If you don’t have read permissions for some objects, you might get less results than the specified limit value. |
offset | Define a number at which the query starts. For example, if you use 10, the query returns results starting from the eleventh. |
Pagination examples
Display ten labels, starting from the twenty first, where you're the owner:
cm find label "where owner='me'" limit 10 offset 20Display the first ten branches that you created:
cm find branches "where owner='me'" limit 10Sort
Use the order by clause to sort certain objects by different fields. You can use the keywords asc or desc to sort your results in ascending or descending order, respectively. Dates and changeset IDs sort numerically, and text fields sort alphabetically.
You can sort the following objects by the specified fields:
| Sort object | Available fields |
|---|---|
branch | date, branchname |
changeset | date, changesetId |
label | date, labelname |
review | date, modifieddate, status |
Example sort
Find your changesets and order the results by date in descending order:
cm find changesets "where owner='me'" order by date descFind all branches between two dates and sort by the branch name in descending order:
cm find branch "where date > '2022/01/01' and date < '2022/01/05'" order by branchname descXML output
Set the output to XML so that you can save it to a file for later analysis:
cm find revisions "where changeset=16716" --xml --file=output.xml