Path Length limitations and Rainbow Settings

Path Length limitations and Rainbow Settings

The limitations

For historical reasons, Windows has a limitation on the length of file system paths. It is 248 characters. And while newer versions of Windows OS has settings that can disable this limit, the limit is still enforced in quite a lot of tooling in the ecosystem today. We're talking anything from Zip to Git-for-Windows to the .NET framework itself.

For the time being, Rainbow works with this restriction as is. Opening it up for support on systems that support it is definitely being considered. But for now, this is what it is. 248 characters.

Under normal circumstances, the root path of all Sitecore items is sitecore so that reserves 8, leaving us with 240.

Rainbow does not detect anything on the file system it operates on. It works exclusively on the basis of the two settings below. It does so to preserve consistency across environments.

The settings

Rainbow.SFS.SerializationFolderPathMaxLength

This setting controls, how many characters to reserve, for your configuration path

• e.g. D:\Projects\HabitatIsNotAStarterKit\Unicorn\system\templates\Foundation\Search (79 chars)
• e.g. C:\Users\mark\Documents\Visual Studio 2017\Projects\HabitatIsNotAStarterKit\Unicorn\system\templates\Foundation\Search (119 chars)

Be aware that this can very quickly get out of hand. To work around this, see below.

• D:\Projects\FancypantsClient\HabitatIsNotAStarterKit\Unicorn\src\HabitatIsNotAStarterKit\Feature\FancypantsClient.PageComponents\Search (136 chars)

Rainbow's default setting is 110. Only 1 of the above examples fit within this.

Rainbow.SFS.MaxItemNameLengthBeforeTruncation

To help a little with the path length limitations, this other setting basically determines "how long is long enough?" as far as an Item Name is concerned.

Default setting is 30 chars

So it's like this:

In the default settings, 110 characters are reserved by Rainbow.SFS.SerializationFolderPathMaxLength

30 characters are reserved for Item Name (which will ultimately be the file name)

3 characters are reserved for the default extension; yml

Leaving us with 97 characters for the Item Path; e.g. /sitecore/system/Settings/Rules/Content Editor Warnings/Rules (62 characters).

Wrap-around

So what happens when these defaults are not enough?

For every Item Rainbow processes, it does the same math. This is important. It does the same math; it has no considerations about file systems and path limitations - it calculates based on the above settings alone.

1. What is this Item's current Path Length? (essentially the .Paths.FullPath of the Parent Item => plen
2. How much is reserved for the Repository Root Path I am currently working? => reserved
3. How long is the file extension? => extlen
4. What is the defined Max Length for Item Names? => maxnamelen

    if(plen > (240 - reserved - extlen - maxnamelen)
        do_wraparound()
    else
        serialize_as_is()

So what is a wraparound?

Essentially, when Rainbow can't make things fit within the limitations it will - instead of creating a directory structure that mimics the item path; e.g. D:\Projects\Unicorn\MyConfig\sitecore\system\settings - it will take the ID of the parent item and create a folder in the Repository Root. Like so: D:\Projects\Unicorn\MyConfig\B18CA85D-2893-451D-AFCD-70619C095B75. For children of the path that has been wrapped like this, it continues nesting from there. Like D:\TestDatastore\Unicorn\Master\0bfb89b6-c751-4a99-9ba8-67f5c2e3df53\By entry page URL_6b945ae7-673f-412a-96f8-f53ef9d63bbc.

This can be confusing for a human to follow. Unfortunately there is no way around this, under current limitations.

Because of this, it is extremely important that these 2 settings remain the same on ALL environments

As mentioned, Rainbow runs the above calculation ONLY. So it needs to know HOW the repository was serialised to being with, in order to be able to locate items and paths correctly.

As mentioned, it is recommended to never change the defaults. But IF they need to be changed, the following rules must be observed:

• The setting must be replicated everywhere. All developer machines, all delivery environments, everywhere Unicorn/Rainbow is being used.
• The full respository - all configs MUST be completely reserialised. No exception.

Assorted tips

• Developers are not locked to a specific path for their local repositories. As long as they remain under the defined limit (default 110).
• Subsequently it does not matter if one developer runs on a short repository path e.g. D:\Projects\Winning\Unicorn and another on D:\My Projects\For This Client\For That Project\Winning\Unicorn - as long as the root paths stay under the defined Max Length (110 default) it will in no way influence how Rainbow behaves
• In most setups, the repository root path is defined like D:\Something\Something Else\$(configurationName). Try and keep your configuration names short. Do Fe.H.IsNotAStarterKit instead of Feature.Habitat.IsNotAStarterKit.
• Try avoiding nesting your repositories too deep; e.g. inside some deep Helix structure
• Monitor Rainbow.config and make sure no developer makes changes to it to accommodate a personal path length.