Documentation

Support

Unity Version Control

DevOps

On-prem

Gluon

Editor plug-in

Open Unity Dashboard

Unity Version Control

Syntax

Syntax reference for the cm find command in Unity Version Control CLI.
Read time 3 minutesLast updated 21 days ago
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]

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' (...)

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