How to link repositories using Xlinks

Thursday, December 01, 2011 11 Comments

Xlinks are one of the coolest new features in Plastic SCM 4.0.

They're basically a way to link different "trees" together so that a "project" repository can have "versioned links" to other component repositories and then just switching to a branch on the "project" repo will set up all the code for you.

For 3.0 users: instead of delving with complex multi-repository selectors, Xlinks enable a way to just link to repos and download them easily (developers on your team won't have to copy/paste complex selectors, just switch to the right branches).

For Git users: Xlinks are "submodules" done right!

I’m going to show you how easy is working with multiple repositories at the same time using Xlinks.


We have several repositories, one for the source code, one for marketing stuff and the last one for third party tools.




It’s a good idea to have your information divided into isolated repositories since they are independent sub-projects, but actually they are part of the same project, so many times they will need to evolve together and share their content. For example, the Core repository needs the ThirdParty repository to achieve a successful build.

How can we mix these repositories and work with all of them at the same time? Xlinks.


We have to create a new repository that will be the one who is going to manage the Xlinks to external repositories. This will be our “Project” repository.

Create a new workspace working against the new repository, make three new directories, this will be the skeleton for the final structure.

Now we create the Xlinks to our external repositories. You can find more info about how to create them issuing “cm xlink --help” but basically you just need to type ‘--w’ if you want to create a writable Xlink, where is going to be placed the external repository content, the external repository path that is going to be mounted and finally the starting changeset of the external repository.
Sub-root paths will be supported in the future but from now you can only use the root path “/”.
Now checkin ‘em all!!! You can use the pending changes view to do it.
When everything is inside the repository your Items view will be like image below, notice the small arrows over the icon means that they are Xlinks to external repositories.

The last step to finally get the external content is perform an update operation, you can do it by right clicking on the workspace root item and Update.

One repository to rule them all, One repository to find them.
One repository to bring them all and in the darkness bind them.

Extra bonus

Do you remember that we created the Xlink with the “--w”? That means that they are writable! You can modify items under an Xlink, remove, move, merge, create branches, basically EVERYTHING.
With writable Xlinks you can evolve the 4 repositories at the same time, try to create a new branch on your Project repository, switch to it. Checkout a file inside an external repository, modify it a little bit and finally checkin it. PlasticSCM will automatically create a new branch on the remote repository to keep the change done! And you don’t have to care about nothing it simply works!


  1. Do you have an idea about the date of disponibility of xlink in subdirectory? Is this feature in the pipe line? It doesn’t look to be supported in 4.1.


  2. We still do not have it. Xlinks to subdirectories are trivial for readonly xlinks, but not so much for writable ones.

    Would readonly ones do for you?

  3. Have you been able to work out xlinks to subdirectories? We could really use that.

  4. {quote}And you don’t have to care about nothing it simply works!{quote}

    But what if I WANT TO CARE .. I do want writable xlinks but without any harmful "magic" ... viewing a branch explorer of a submodule / Xlink that is linked and worked with in multiple projects will really get awful fast

  5. But you can see the branch explorer of every xlinked repo, can't you?? So you can CARE about the details, of course

  6. yes, I can see it, it's not the problem. Sorry to be unclear: The Problem is / are automatically expanded branch expansion rules that automatically come up again even I've deleted all of them.

    I don't want to let plastic do any magic branching and merging. I want to care about branching myself!
    This seems not to be possible, else: it seems to be undocumented or a bug?!

  7. If you don't want plastic to create the branches, maybe it is better to use readonly xlinks, isn't it?

  8. no, not if development and testing (requirement before the checkin) in submodules only works integrated in project!

    Also: What about branches named identially in different projects using the same xlink

    Another problem: there are auto-commits in submodules that behaves / look like cherry picks of all changes between the version I branched up the (automatic) branch expansion merge base. It's not clear if I really intended to do these changes here or it was made automatically to allow auto-merging later on... it's also NOT that what I wanted to get in my project, that's why I sticked the subrepo to an older version!

    In short: is there an option to deactivate these auto-xlink-branching-magic or not? while still being able to create changes an commit them (on top of the sticky version I refered to?)

    If I want the newest development of the subrepo, I have to explicit update the ref OR have to merge the submodule myself. Automatic magic == bad in most cases (for me)

    I don't think this discussion why or why not (even it becomes a buglist for me) will not become constructive anymore ;)

  9. "magic" is writable xlinks. Use readonly and that's all.

    Please, contact support and they'll try to help you in more detail, or reach our forum as a best place to talk about this in detail.

  10. Using writable Xlinks is not possible to deactivate branch-expansion. But if the default mechanism doesn´t work for you, you can configure your custom branch expansion rules. You can define the source and destination branches.

    As Pablo said, using readonly Xlinks is another possibility.

    You can post in Plastic SCM forum your scenario, and we will try to find the best configuration for you.