Symlink support#

Symlinks (aka "symbolic links" or "soft links") are special items meant as proxies of other files or directories. They point to another item - known as the "target" - by path, and when an application tries to interact with them, the kernel redirects some of the file system operations (e.g., read and write), so they apply to the target instead.

In simpler terms: by using symlinks, applications might read from (or write to) a file that is located somewhere else, maybe even in a different drive.

Applications rarely need to be "aware" of symlinks most of the time, as they work transparently, and the kernel takes care of making them work. However, sometimes it is necessary to create, delete, or move them around in the file system tree. Moreover, some programs need to detect them, understand them, and retrieve the target path to perform some special handling.

Unity DevOps Version Control can do all that. Support spans Linux, macOS, Windows[*], and even PlasticFS!

Symlinks creation#

Creating symlinks is easy in Unix systems. You need to open your favorite shell and use the following command:

# ln -s TARGET LINK_NAME
# -s, --symbolic: make symbolic links instead of hard links

$ ln -s ../game_engine/built_in_assets /wk/game/Assets
$ ls /wk/game

# Assets -> ../game_engine/built_in_assets

On Windows, you need to enable Developer Mode[*]. Then open CMD and then use the following command:

# mklink [/D] LINK_NAME TARGET
# /D Creates a directory symbolic link. Default is a file symbolic link.

> mklink /D C:\wk\game\Assets ..\game_engine\built_in_assets
> dir C:\wk\game

# Assets -> ..\game_engine\built_in_assets

It is worth noting that arguments in Windows and Linux are expected in different order. Also, the Windows command requires you to specify when you want to point to a directory instead of a file.

Symlinks and version control#

Once you have created a symlink, you can add it to (or remove it from) version control in the Unity DevOps Version Control GUI or the command line as usual. You don't need to do anything out of the ordinary. The client will know that you mean the link and not its target!:

# The 'Assets' directory is a freshly created symlink.

> cm add Assets
The selected items are about to be added. Please wait ...
Item c:\wk\game\Assets was correctly added

> cm rm Assets
Item c:\wk\game\Assets has been removed

When you checkout a file, you tell UVCS you want to track its changes. As said before, reading and writing operations on symlinks are redirected by the kernel to affect the target. In the same way, the Unity DevOps Version Control command line "redirects" checkout commands to the target item, like so:

> cm co c:\wk\game\Assets
The selected items are about to be checked out. Please wait ...
Item c:\wk\game_engine\built_in_assets was correctly checked out

> cm unco c:\wk\game\Assets
c:\wk\game_engine\built_in_assets unchecked out correctly

Whereas this is usually the desired behavior, you may want to change the symlink itself, not its target. For that specific case, commands that relate to tracking changes - like checkout (co), undo and undo checkout (unco) - also provide a --symlink option:

> cm co --symlink c:\wk\game\Assets
The selected items are about to be checked out. Please wait ...
Item c:\wk\game\Assets was correctly checked out

> cm unco --symlink c:\wk\game\Assets
c:\wk\game\Assets unchecked out correctly

Remember that commands affecting the file tree hierarchy - like add, move (mv) and remove (rm) - do not need nor provide such an option, as they only can refer to the link itself.

PlasticFS#

At the time of writing this, PlasticFS provides symlink support too. You should be able to use the Unity DevOps Version Control command line, the GUI, and tools like mklink. Indeed, you don't need to enable Developer Mode when using dynamic workspaces anymore! Note that symlinks might behave slightly differently in dynamic workspaces, having some minor advantages and disadvantages.

On top of that, PlasticFS supports junctions too. Junctions can be created with mklink using the /J option. Whereas the server does not support them, they will be auto-converted to symlinks if you need to add them under version control.

[*] Windows support requires you to enable Developer Mode (unless you use PlasticFS dynamic workspaces). To do so, type 'Developer Settings' into the Cortana search box in the taskbar. Then go to the 'For developers' section and switch the 'Developer Mode' toggle on: https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development

If you cannot enable Developer Mode, you can disable support by adding the following setting to your client.conf:

<EnableSymlinkSupportOnWindows>no</EnableSymlinkSupportOnWindows>

Windows support is enabled by default for Windows 10 build 14972 or newer since Unity DevOps Version Control 11.0.16.8044. However, it has been available since Plastic 11.0.16.6979, released on May 19th, 2022. If you have a version released in between and you cannot upgrade, it is possible to explicitly enable support by adding the following setting to your client.conf:

<EnableSymlinkSupportOnWindows>yes</EnableSymlinkSupportOnWindows>