Xlinks guide

Chapter 1: What is an Xlink

Projects often need to reuse existing components that have been developed and are actively used as part of other projects. Plastic SCM encourages using separate repositories for different projects and components, and access shared components by "mounting" them in the project repository through Xlinks. This chapter will introduce what are Xlinks and how to use this powerful feature to share components among projects that evolve in parallel.

An Xlink is pretty similar to a symbolic link, like those found in Unix operating systems. It is a directory entry in your repository tree that points to another directory in a different repository. An Xlink, however, will also contain information about the specific version of the target directory to which it is pointing.

Sample Xlink

Xlinks can point to repositories with other Xlinks inside them, so Xlink component mounting can address really complex development scenarios.

Several Xlinked repositories

Xlinks pointing to a given version of the target directory let the user specify, for instance, that project X on version 1.1 is using version 2.1 of library Y. When a new version of the library is labeled, say 2.2, the code of the project can be updated to use it and maybe version 1.2 of project X uses library Y 2.2.

Since Xlinks are versioned, the Xlink in old project X version 1.1 still points to library Y 2.1 and the original configuration can be completely rebuilt without any issue. The following figure depicts how it looks like:

Xlink evolution

Chapter 2: Creating and Modifying Xlinks

An Xlink is defined using the Plastic SCM command line client, through the xlink command. An Xlink is defined with at least two arguments:

  1. The directory entry to create in the current repository. This is a directory that will be used to.
  2. The directory to mount in the target repository. You can Xlink not only to the root of another repository, but also to any path inside by mounting a "subtree" on the parent repo as "partial Xlinks".

    Partial Xlinks are available on Read-only Xlinks (see below). "Writable partial Xlinks" are not supported yet because they would overly complicate the merge (what if you have conflicts on parts you are not mounting?).

    Remarks: At this point you need to use the command line to create partial Xlinks. GUI support will come soon.


  3. Version and repository to mount at point 1 above. The version of the directory to mount is specified using either a changeset specification or a label specification.
  4. Xlink definition syntax sample

  • Read-only Xlinks - Are recommended for situations where you are the user of an existing component, but you don't influence its development. In the sample above, you were Xlinking an existing library and only calling it from your project, but not making any changes to it.
  • Writable Xlinks - On the other hand, let you make changes inside the Xlinked repository.

You'll notice in the Items view of the GUI client that the Type column contains wXlink where it used to be Xlink for read-only Xlinks.

Read-only vs. writable-Xlinks in the Items view

The command used to create the Xlink in the sample referred in section What is an Xlink looks like this:

cm xlink component1 / 1@mylibrary

In the sample:

  • component1 is the directory in the project repository that will point to the mounted mylibrary component. This directory must not exist already in the repository. The xlink command will create an item for it and it will throw an error if a file of directory already existed with the same name.
  • / is the directory in the target repository, as described above.
  • 1 is the changeset number in the target repository.
  • mylibrary is the target repository. Together with the changeset it forms a changeset specification. In this case, there is no server specified. If the server is to be specified, the spec would look like this: 1@mylibrary@servername:8087

It is also possible to specify a label instead of a changeset. Since a label is actually a pointer to a changeset, the two specifications are interchangeable. To do so keep in mind that specifying an xlink with a label only uses the label to retrieve the changeset to which it points and sets the xlink to it. This means that if the label is moved afterwards, the Xlink will still point to the original changeset.

To create a partial Xlink (read-only):

cm xlink component1Src /src/dll cs:478@mylibrary

where /src/dll is the subdirectory where the partial Xlink will be mounted.

You can create a Writable Xlink in the command line specifying the -w modifier:

cm xlink -w component1 / 1@mylibrary
To get further information about how to create an Xlink in the Command Line, refer to the command line interface and use the cm help xlink command.

Xlinks can not only be created from the command line, they can be created from the GUI client that Plastic SCM provides. You'll note the new option in the Items View context menu:

Remember that, at this moment, partial Xlinks must be created only from the command line.

Creating an Xlink in the GUI Client

You can create an Xlink by right-clicking on any directory or existing Xlink and selecting the Create Xlink option. It will create a new Xlink inside the selected directory. You'll see this dialog box pop up to help delineate the parameters:

Create Xlink Dialog Box in the GUI Client

You'll be able to configure the name of the Xlink and the target changeset of the Xlink. To select the target changeset, you'll select the target Plastic SCM server, then a repository inside that server, and finally a changeset in the repository. In this dialog box, it is also possible to set the Writable and Relative server options for the Xlink.

The Xlink is created in the workspace and appears as a pending change in the Pending Changes View or to the cm status --added command, as depicted in the following figure:

Just created Xlink in the Pending Changes view

Once it is checked in, the Xlink needs to be updated so the contents of the mounted directory are downloaded into the workspace. This can be done in the GUI by clicking the Update workspace button:

Xlink in the Items view

The target of an existing Xlink can be modified using the -e modifier of the xlink command. In this case, the syntax is similar to the creation syntax, but the Xlink must exist already. The following example modifies an existing Xlink component1 to point to changeset 5 on repository mylibrary:

cm xlink -e component1 / 5@mylibrary
To get further information about how to modify an Xlink in the Command Line, refer to the command line interface and use the cm help xlink command.

Xlinks can also be modified using the Plastic SCM GUI client. When you right-click an existing Xlink, the following context menu will pop up:

Editing an Xlink in the GUI Client

When you click the Edit Xlink option, a dialog box will pop up:

Editing an Xlink Dialog Box

You'll be able to configure the target changeset of the Xlink.

Exploring the Xlinked repository

The Plastic SCM GUI views that you can open in the left options tree display the information of the top-level repository loaded in the workspace. But it may be desirable to see the Branch Explorer or the Changesets views of an Xlinked repository.

The items view makes this easy through the Repository submenu. When you right-click an item inside an Xlinked repository, the Repository submenu lets you open the most important views for the repository where the item is located: i.e. the Xlinked repository. For your convenience, the first entry in the menu contains the repository name of the item:

Repository menu for an item in an Xlinked repository

Chapter 3: Xlink Expansion Rules

Xlink Expansion Rules define how branches are created on the Xlinked repositories, and how the branches in the parent repository relate to the branches in the Xlinked repository.

Xlink created in top level branch

The regular scenario is very simple: the developer defines a new Xlink from the quake repo to the zlib repo. He sets the wXlink between changesets on the main branches of each repo.

Standard Xlink creation

The expansion rule for the wXlink at this point will be very simple:

    main@quake -> main@zlib

Since the two Xlinked changesets are on branches with the same name and the same level (top level branches in this case) expanding the wXlink is very simple as explained below:

  • Now the developer creates a branch task001 to implement a new feature.
  • Then he modifies file /src/foo.c that is inside the wXlink, so stored inside the zlib repo.
  • Since he's using a writable Xlink the branch auto-expansion mechanism of Xlinks will create a new branch main/task001@zlib as follows:

Standard Xlink creation - subbranch

At this point, the expansion rules will be as follows:

Standard Xlink creation - Automatic created rule

Please note how a new rule has been automatically created by Plastic ( Is defined by user = No ) to track the new branch expansion that happened.

New automatically created rules will be created if more branches are automatically expanded through the branch hierarchy.

Adding an Xlink on a second level branch

Consider now the following very common example: suppose you have to create a new wXlink but you create a task branch to do the job, so you're isolated while you test the new layout and it will be merged later to main.

Your scenario will be as follows:

Xlink creation with proposed rule

In this situation you don't really want to create an Xlink expansion rule from main/xlink-creation@quake -> main@zlib nor this rule to set how branches are created on the Xlinked repo. Most likely what you want to do is eventually Xlink the main branches.

Plastic SCM will detect this situation and will inform you as follows:

Warning when creating an xlink

And will create a rule main@quake -> main@zlib:

Main rule creation

Now suppose that just after creating the wXlink on the branch task001 you need to modify a file inside the wXlink. Since the main to main wXlink is already defined, the branch expansion will work correctly and will automatically create a /main/xlink-creation branch inside the zlib repo:

Xlink creation expansion

And the expansion rules at this point will be as follows:

Xlink creation expansion rule

Creating asymmetric Xlink hierarchies

So far the created wXlinks have been symmetric: main linked to main, main/task001 to main/task001 and so on.

Expansion rules are especially helpful when asymmetric links are required. Suppose you need to link the branch main@quake to branch main/fix@zlib. The initial expansion rule will be set this way, and it will enable a parallel asymmetric evolution like the following picture shows:

Asymmetric links

The initial versions of Plastic SCM with Xlink support didn't include Xlink expansion rules. The expansion was controlled by matching branch names, so while simple asymmetric hierarchies were supported, complex cases were not. Consider the following example:

Complex case without expansion rules

That will be handled in the following way now:

Complex case with expansion rules

Advanced expansion cases

Some projects need to set more than one Xlink to the same repository, maybe because they depend on two different versions of the same component.

Consider the following example:

Complex case with multiple xlinks in the same repository

The erp repo Xlinks twice to the zlib: one for the server code that uses the most up-to-date 1.9 version of zlib, and one for the iphone code that uses the older version 1.7.

(Note: the erp project could be structured on a different way, maybe dividing the server and client on different repositories, but this is not the goal of this explanation).

Once the Xlinks are setup, let's inspect /server/zlib:

Complex xlink in main server

Please note how the Is defined by user is set to true. In Plastic internals jargon this rule is a traveling rule which means: it doesn't apply to the current branch and has to travel to the final one (like when you create a rule in /main/task001 for main@quake -> main@xlinked, it has to travel to main during the merge) or it hasn't been applied yet. Consider now the situation where you make a change inside /server/zlib. The situation will be:

Complex case with multiple xlinks in the same repository - Change

Where the /server/zlib wXlink has been updated to point to the newly expanded branch main/server@zlib while the other wXlink hasn't been modified yet.

At this point, if you edit the wXlink /server/zlib you'll see the rule has been modified and it is now as follows:

Complex xlink in main server after expansion

The rule now directly applies to the branch association so it is not considered anymore as a traveling rule (or defined by user).

This is a complex scenario and understanding how it works helps to get a deeper understanding of Xlink branch expansion rules.

Initially an Xlink is created from main@erp to main@zlib with a rule main -> main/server (main/server branch is still empty):

Xlink Branch Expansion in action in a complex scenario - step one

Then the developer creates main/task001@erp and makes a change inside wXlink.

Please note how the branch expansion doesn't happen as initially expected only because main/server is empty and it doesn't contain changesets to start /main/server/task001 from, so main/task001@zlib is created instead:

Xlink Branch Expansion in action in a complex scenario - step two

Now the developer merges main/task001@erp back to main and the following happens (now the rule is used as expected). The rule defined by the user is finally used when the correct conditions are met:

Xlink Branch Expansion in action in a complex scenario - step three

Chapter 4: Merging links

Merging a branch also affects the auto-expanded branches in the wXlinked repositories. The merge operation is done on the top-level repository (the repository to which the workspace is pointing to). It will then evaluate any new versions of wXlinks that have been created and consider the changes in the linked repositories in the merge process as well.

In this sample scenario, we have the same 2 repositories we used in previous sections: ProjectX and MyLibrary. ProjectX is the top-level repository and contains a wXlink component1 pointing to MyLibrary. In ProjectX we have created two child branches: task0127 and task0243.

We then made changes in the file events.h, located in the Xlinked MyLibrary repository in both branches. This, indeed, expanded branches task0127 and task0243 to the MyLibrary repository:

Sample conflict: same file modified on two branches on Xlinked repositories

Now, what happens when you try to merge from branch task0127 to branch task0243, as depicted in the figure below?

Branch task0127 is merged to task0243

The merge operation will consider the changes made to the wXlink in both branches and then evaluate the changes in the wXlinked repositories themselves to include them in the merge. So, as a user, you'll have to resolve any possible conflicts as you would with a normal "single repository" merge.

Merging changes in Xlinked repositories

Now the merging of Form1.cs is resolved but, what about the wXlink? The answer is that the merge operation will also update the WXlink to point to the result of the merge in the MyLibrary repository. That is, as a result of the merge operation, there is a new version of Form1.cs with the merged changes, and the WXlink in the ProjectX repository will point to this new changeset. For this reason, the Pending Changes view shows a pending merge link for the ProjectX repository, as depicted in the next figure:

Merged branches in top-level and wXlinked repositories

The overall result is that you only need to tell Plastic SCM "I want to merge this branch" in your workspace, and the merge operation will handle the changes made in wXlinked repositories.

Chapter 5: Relative Xlinks

When Xlinks are replicated, the target they point to is still the original one. So, say that you are replicating a repository with an xlink component1 pointing to changeset number 6 on repository MyLibrary on server mainserver.location1.com:8087. The destination of your replica is on another Plastic SCM server at otherserver.location2.com:8087. When you replicate the top-level repository, the Xlink in your replicated repository will still point to mainserver. If it is reachable from the location2.com network, the data for MyLibrary repository will be downloaded from location1.com.

Most of the time, you'll want to replicate the MyLibrary repository to location2.com as well, and perform any changes in the local replica.

To tell the Xlink that you want to use the MyLibrary repository found in your default server (that of the top-level repository), you need to create the Xlink with a relative server.

This is achieved with the -rs modifier when the Xlink is created, as in the following example:

cm xlink -rs component1 / 6@mylibrary

When this link is replicated, it'll try to locate MyLibrary repository in the local server, rather than mainserver.location1.com.

Note that changeset number 6 may no longer have number 6 in the replicated repository (changesets are internally identified by their GUID, not their number, since replicas may have different numbering. Refer to the DISTRIBUTED VERSION CONTROL guide for more details). The Xlink will be pointing to the right changeset even if the number changes, because it uses the changeset GUID rather than the changeset number to locate it.


December 17, 2016
  • Partial readonly Xlinks are now available.