FIND
Description
Runs SQL-like queries to find Unity VCS objects.
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: https://www.plasticscm.com/download/help/cmfind |
| --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_conditions | Searches conditions on an object attributes. |
| repspec | Searches 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_field | The 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. |
| maxresults | The maximun number of results returned by the query. |
| offset | The number of rows to skip before starting to return results from the query. |
| object_type | Object 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: https://www.plasticscm.com/download/help/cmfind |
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"