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 branch or cm find branches.
  • All cm find queries 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

General syntax

The following example shows the general syntax:

cm find object "[where conditions] [on repositories]"
               [sort options] [pagination options]
               [format options]
ParameterDescription
objectFind 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 conditionsThe filtering conditions depend on the object. To retrieve the conditions, and available objects, use the command cm showfindobjects.
sort optionsOrder the objects by a specified field.
pagination optionsManage the result size and specify the starting point to retrieve objects.
format optionsSpecify output preferences, such as --format, --xml, or --file. Refer to the Microsoft documentation on width formatting for strings.
on repositoriesRetrieve 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:

ConstantDescription
todayToday's date.
yesterdayYesterday's date.
this weekCurrent week's Monday date.
this monthThe first day of the current month.
this yearThe first day of the current year.
one day agoOne day before the current date.
one week agoSeven days before the current date.
one month agoOne 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:

ParameterDescription
limitThe 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.
offsetDefine 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 20

Display the first ten branches that you created:

cm find branches "where owner='me'" limit 10

Sort

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 objectAvailable fields
branchdate, branchname
changesetdate, changesetId
labeldate, labelname
reviewdate, 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 desc

Find 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 desc

XML 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