XLINK
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:
- 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.
- 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').