Documentation

Support

Unity Version Control

DevOps

On-prem

Gluon

Editor plug-in

Open Unity Dashboard

Unity Version Control

XLINK

Manage xlinks with the Unity Version Control CLI.
Read time 3 minutesLast updated 21 days ago

Description

Creates, edits, or displays details of an Xlink.

Usage

cm xlink [-w] [-rs] <xlink_path> / (<csetspec> | <lbspec> | <brspec)> [<expansion_rules>[ ...]]
(Creates an Xlink.) 
cm xlink [-rs] <xlink_path> /<relative_path> (<csetspec> | <lbspec> | <brspec>) [<expansion_rules>[ ...]]
(Creates a readonly partial Xlink pointing to 
<relative_path>
instead of the default root 
/
.) 
cm xlink -e <xlink_path> (<csetspec> | <lbspec> | <brspec>)
(Edits an Xlink to change the target specification.) 
cm xlink -s|--show <xlink_path>
(Shows the Xlink information including the expansion rules.) 
cm xlink -ar|--addrules <xlink_path> <expansion_rules>[ ...]
(Adds the given expansion rules to the Xlink.) 
cm xlink -dr|--deleterules <xlink_path> <expansion_rules>[ ...]
(Removes the given expansion rules from the Xlink.)

Options

Option / Argument

Description

-
e
Edits an existing Xlink to change the target changeset specification.
-
s | --show
Shows information about the selected Xlink.
-
ar | --addrules
Adds one or more expansion rules to the selected Xlink.
-
dr | --deleterules
Deletes one or more expansion rules from the selected Xlink.
-
w
Indicates that the Xlink is writable. This means that the contents of the target repository can be modified through branch autoexpansion.
-
rs
Relative server. This option allows creating a relative Xlink that is independent of the repository server. This way, Xlinks created in replicated repositories in different servers will be automatically identified.
expansion_rules
To specify one or more expansion rule. Each expansion rule is a pair branch-target branch: 
br:/main/fix-br:/main/develop/fix
xlink_path
This is the directory in the current workspace where the linked repository will be mounted (when creating an Xlink) or is mounted (when editing an Xlink).
csetspec
The full target changeset specification in the remote repository. This determines what version and branch is loaded in the workspace for the linked repository. (Use 
cm help objectspec
to learn more about changeset specs.)
lbspec
The full label specification in the remote repository. (Use 
cm help objectspec
to learn more about label specs.)
brspec
The full branch specification in the remote repository. This uses the current changeset where the specified branch is pointing to. (Use 
cm help objectspec
to learn more about branch specs.)

Help

Remarks

This command creates an Xlink to a given changeset. By default, a read-only Xlink is created. This means that the contents loaded in the workspace inside the Xlink cannot be modified. To be able to make changes in the Xlinked content, create a writable Xlink instead (using the 
-w
option). It is possible to use a simplified syntax of the command when editing the target changeset of an Xlink. This way, the only required parameter is the new target changeset. The rest of parameters of the Xlink will not be modified.

Branch auto-expansion

When a change is made in any writable-xlinked repositories (
-w
option), a new branch needs to be created in the target repository. The name of the new branch is based on the checkout branch defined in the top-level repository. To determine the name of the branch to use, these rules apply:
  1. A check is made to see if a branch with the same full name exists in the target repository:
  • If it exists, this is used as the checkout branch.
  • If it does not exist, the branch name is built this way:
    • Name of the branch of the target Xlinked changeset + short name of the checkout branch (last part).
    • If this branch exists, it is used as the checkout branch.
    • Otherwise, the branch is created and the branch base is set to the Xlinked changeset.
  1. A new version of the Xlink is created in the branch on the parent repository pointing to the new changeset in the Xlinked repository.
Finally, the complete Xlink structure is kept up to date with the latest changes in the right versions.

Examples

cm xlink code\firstrepo / 1@first@localhost:8084
(Creates an Xlink in folder 'firstrepo' in the current workspace where the changeset '1' in the repository 'first' will be mounted.) 
cm xlink opengl\include /includes/opengl 1627@includes@localhost:8087
(Creates a readonly partial Xlink in directory 'opengl\include' in the current workspace where the path '/includes/opengl' in changeset '1627' in the repository 'includes' will be mounted as root. It means that whatever is inside '/includes/opengl' will be mounted in 'opengl\include' while the rest of the repository will be ignored.) 
cm xlink -w -rs code\secondrepo / lb:LB001@second@localhost:8084
(Creates a writable and relative Xlink in folder 'secondrepo' in the current workspace where the label 'LB001' in the repository 'second' will be mounted.) 
cm xlink code\thirdrepo / 3@third@localhost:8087 br:/main-br:/main/scm003
(Creates an Xlink in folder 'thirdrepo' in the current workspace where the changeset '3' in the repository 'third' will be mounted.) 
cm xlink -e code\secondrepo br:/main/task1234@second@localhost:8084
(Edits the Xlink 'code\secondrepo' to change the target repository by linking the branch 'main/task1234' in the repository 'second'.) 
cm xlink --show code\thirdrepo
(Shows information of the Xlink 'code\thirdrepo' including its expansion rules if exist). 
cm xlink -ar code\secondrepo br:/main-br:/main/develop br:/main/fix-br:/main/develop/fix
(Adds two expansion rules to the xlink 'code\secondrepo'.) 
cm xlink -dr code\secondrepo br:/main/fix-br:/main/develop/fix
(Deletes the expansion rule from the xlink 'code\secondrepo').
XLINK • Unity Version Control • Unity Docs