Overview

Pinning allows you to pin files and folders to the local data cache so that they remain cached until you Unpin them. It is implemented for all operating systems: macOS, Windows, and Linux (CLI only). 

This is especially useful when you need to ensure the data is on the local disk so you don't have to rely on your internet connection if you know it will be particularly poor.

For example, you have a specific project (e.g. a folder) that you know you'll be working on for several days, once you pin that "project", as long as there is enough configured cache, LucidLink will make sure all data is retrieved from the cloud, pro-actively, for you to work directly on the local disk. 

Note that all pinned files and folders will be updated accordingly even if another user is making changes to the folders you've pinned (e.g. new files and folders are copied into a pinned folder etc.). You are not creating a local-only copy when Pinning, simply ensuring that the data is available in your cache at all times.

Once all data is successfully pinned, you'll see a green pin next to the file or folder to show you that all data is available locally.

If new files or folders are created within a pinned directory a blue pin will appear showing you that data is being actively retrieved from the cloud to bring the pinned folder up-to-date. 

Since any other user can put as much data as they need, once the available size for pinning is 0 bytes on your machine, an orange pin will show you there is a problem with retrieving additional data and you will be able to tell exactly which files or folders were not able to fully download on the local disk.

Up to 80% of your configured total cache size is allowed to be used for pinning. This is to guarantee there is a free cache at all times for activities outside pinned entries. See Adjusting Local Cache Settings 

Finder / File Explorer (macOS & Windows)

Right-click on a file or folder and select Pin. You can also select multiple folders at once.

The file and folder overlay icons have different states when using the Pin feature.

Blue	Green	Orange
Pinning	Pinned	Cannot finish Pinning

The overlay icons are currently supported only on macOS and Windows.

Managing Pinned Files

The Pinned files dashboard can be accessed by doing the following:

• Select your filespace from the workspace dashboard and click the "Manage pinned files" option.

• Click on the dropdown menu next to your filespace, then select "Pinned files".

  

Pinning Files Dashboard Overview

Pinning Status & Progress: You can see a full list of all pinned files and folders, as well as sort by size, name, and status.

• Each item displays its current status, such as "Pinning" or "Pinned".
• For items currently in the process of being pinned, a loading icon shows the pinning progress in real-time.
• Hover over an item in the list to see its full path in the directory structure

Pinned cache metrics: 

• Pinned files: The total size of your files and folders pinned to the local data cache.
• Pinning limit: At all times, 20% of your total cache size is reserved for activities outside pinned entries
• Cache size: The cache size that has been set on this device.

 Management Controls:

The following actions can be performed on pinned files:

• Unpin items directly from the list by selecting the unpin icon.
  
• Use the Unpin all action to clear all pinned items at once.
  
• Use the Drop cache button to clear the entire local cache (except pinned files and any data remaining to be uploaded).
  
• Jump to your filespace settings to adjust your cache size if needed by selecting the Manage cache size link.
  

Command Line

#lucid help pin

Usage:
lucid pin [--list]
lucid pin [--set] path
lucid pin --unset path
lucid pin --unset --all

Pin/unpin a folder/file locally (keep/remove a local copy)

Options:

    [--list]                 List pinned entries
    [--set] path             The file/folder to be pinned. The path starts at the Filespace root, not the local file system root.
    --unset [path]           The file/folder to be unpinned. The path starts at the Filespace root, not the local file system root.
    --all                    Add this option in combination with '--unset' to unpin all entries

Using the lucid cache command you can see how much Pinned data you have on disk.

#lucid cache

State: enabled
Backend writes: enabled
Page size: 1MiB
Pinnable limit: 20GiB
Cache limit: 25GiB
Current size on disk: 1.56GiB
Pinned size on disk: 0B
Remaining upload: 0B

In order to monitor the pinning activity, you can run the lucid perf command:

lucid perf --cache pagesPinned,pagesUnpinned,failedPagePins

List pinned files and folders

lucid pin --list

Pin a file/folder (The path is relative to the root of the filespace)

lucid pin --set /A/B/C

Unpin a file/folder (The path is relative to the root of the filespace)

lucid pin --unset /A/B/C

Unpin all files/folders

lucid pin --unset --all