Documentation

Support

Unity Version Control

DevOps

On-prem

Gluon

Editor plug-in

Open Unity Dashboard

Unity Version Control

LIST

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

Description

Lists the contents of a tree.

Usage

cm ls | dir [<paths>[ ...]] [--format=<str_format>] [--symlink] [--selector[=<selector_format>]] [--tree=<obj_spec>] [-R | -r | --recursive] [--xml[=<output_file>]] [--encoding=<name>]

Options

Option / Argument

Description

--format
Retrieves the output message in a specific format. See Remarks for more info. This option cannot be combined with 
--xml
.
--symlink
Applies the operation to the symlink and not to the target.
--selector
Gets the content from the active workspace selector. If selector_format is specified, then lists the specified selector. This is mostly deprecated since selectors are no longer a central part of UVCS since 4.x.
--tree
Lists the tree in the specified changeset or branch. (Use 
cm help objectspec
to learn more about specs.)
-R | -r | --recursive
Lists recursively.
--xml
Prints the output in XML format to the standard output. It is possible to specify an output file. This option cannot be combined with 
--format
.
--encoding
Used with the 
--xml
option, specifies the encoding to use in the XML output, 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).
paths
List of paths to show. Use a whitespace to separate paths. Use double quotes (
" "
) to specify paths containing spaces.

Help

Remarks

  • Path can be typed with meta-characters.
  • The list depends on the workspace selector.
  • The output of the command can be formatted specifying a format string.
  • If 
    --tree
    or 
    --selector
    options are specified, the given path must be a server path (a.k.a.: 
    cm
    path): /dir/file.txt, not a workspace path: C:\Users\myuser\mywk\dir\file.txt
  • If no path is provided, the workspace path assumed is the current directory. If 
    --tree
    or 
    --selector
    options are used, then the root path (
    /
    ) is assumed.

The default format string is

{**size,10**} {**date**:dd/MM/yyyy} {**date**:HH:mm}\ {**type,-6**} {**location,-12**} {**checkout,-5**} {**name**}\ {**symlinktarget**}

Output format parameters (--format option)

This command accepts a format string to show the output.

The output parameters of this command are the following

  • {size}
  • {formattedsize}
  • {date}
  • {type}
    • dir
      : directory,
    • txt
      : text file,
    • File
      : file.
  • {location}
    (Example: 
    br:branch#cset
    )
  • {checkout}
  • {name}
  • {changeset}
  • {path}
  • {repspec}
  • {owner}
  • {revid}
  • {parentrevid}
  • {itemid}
  • {brid}
  • {repid}
  • {server}
  • {symlinktarget}
  • {hash}
  • {chmod}
  • {wkpath}
    (Path relative to workspace root)
  • {branch}
  • {newlocation}
    (
    cset@branch
    )
  • {guid}
    (Will take longer to resolve)
  • {itemguid}
  • {transformed}
    (Show applied rule for transformed items.)
You can customize the 
ls
format setting the PLASTIC_LS_FORMAT environment variable.

Examples

cm ls
cm ls c:\workspace\src
cm ls --format={name}
(Only file names.) 
cm ls --symlink
(Displays information about the symlink instead of the target file or directory.) 
cm ls code --selector
(Shows the content of the 'code' subdirectory from the current workspace selector.) 
cm ls /code --selector="rep 'myrep' path '/' branch '/main'"
(Shows the content of the '/code' subdirectory on the specified selector. Note that the path is specified in server format.) 
cm ls /code --tree=44@myrep@denver:7070
(Lists the '/code' subdirectory at changeset 44 at repo 'myrep' at server 'denver:7070'.) 
cm ls /code --tree=br:/main/scm13596@myrep@denver:7070
(Lists the '/code' subdirectory at the latest changeset in branch '/main/scm13596' at repo 'myrep' at server 'denver:7070'.) 
cm ls /code --tree=ae1390ed-7ce9-4ec3-a155-e5a61de0dc77@myrep@denver:7070
(Lists the '/code' subdirectory at changeset ae1390ed-7ce9-4ec3-a155-e5a61de0dc77 at repo 'myrep' at server 'denver:7070'.)