Documentation

Support

Unity Version Control

DevOps

On-prem

Gluon

Editor plug-in

Open Unity Dashboard

Unity Version Control

FIND

Find items with the Unity Version Control CLI.
Read time 2 minutesLast updated 21 days ago

Description

Runs SQL-like queries to find UVCS objects. For more information about syntax and examples, refer to the cm find documentation.

Usage

cm find <object_type> [where <str_conditions>] [on repository '<repspec>' | on repositories '<repspec1>','<repspec2>'[,...]] [order by <sort_field> ['asc' | 'desc']] [[limit <maxresults>] [offset <offset>]] [--format=<str_format>] [--dateformat=<date_format>] [--nototal] [--file=<dump_file>] [--xml] [--encoding=<name>]

Options

Option / Argument

Description

--format
Retrieves the output message in a specific format. Read the 'cm find' guide to see all the object attributes that can be used as output format strings.
--dateformat
Format used to output dates.
--nototal
Does not output record count at the end.
--file
File to dump results.
--xml
Prints the output in XML format to the standard output.
--encoding
Specifies the output encoding, i.e.: utf-8. See the MSDN documentation at http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx to get the table of supported encodings and its format, (at the end of the page, in the "Name" column).
str_conditionsSearches conditions on an object attributes.
repspecSearches repositories alias or specification. In the case of 
on repositories
, use a comma to separate the repspec fields. (Use 
cm help objectspec
to learn more about repository specifications.)
sort_fieldThe name of the field to use as sorting field. Mind there is only a subset of field possibilities. Use 'cm help showfindobjects' to find what objects are allowed to be ordered and by what fields.
maxresultsThe maximun number of results returned by the query.
offsetThe number of rows to skip before starting to return results from the query.
object_typeObject type to find. Some of these objects are implementing the 
order by
clause. Use 
cm help showfindobjects
to learn how to specify these objects, the ones allowing 
order by
and by what fields. You can also read the 
cm find
guide.

Help

Remarks

If no repository is specified, the search is made on the repository configured in the workspace. When you run queries using comparison operators (
>
, 
<
, 
>=
, 
<=
) from the command line, remember that the shell considers these operators as IO redirections. So you will need to enclose the queries in double quotation marks. The 
cm find
command accepts a format string to show the output. Each output parameter is identified by a string and the user can refer it by typing the parameter number between 
{
and 
}
brackets. Output parameters usually correspond to the attributes of the object.

These are some valid output format strings

  • --format={id}{date}{name}
  • --format="{item}#{branch} with date {date}"

XML and encoding considerations

When the 
--xml
option is specified, the command shows the command result as an XML text in the standard output. The operating system default encoding is used to show the text, so it is possible that not-ANSI characters are incorrectly visualized in the console. If you redirect the command output to a file, it will be correctly visualized. When both 
--xml
and 
--file
options are specified, the default encoding will be utf-8.

Examples

cm find revision
cm find revision "where changeset=23 and owner='maria'"
cm find branch "on repository 'rep1'"
cm find label "on repositories 'rep1', 'rep:default@localhost:8084'"
cm find branch "where parent='br:/main' on repository 'rep1'"
cm find revision "where item='item:.'" --format="{item}#{branch}"
cm find revision "where item='item:.'" --xml --file=c:\queryresults\revs.xml
cm find label "where owner='me' limit 10 offset 20"
cm find branches "where owner='me' order by branchname desc limit 10"