> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/shadefs/pinning-files-offline.md). # Pinning Files Offline ## How Pinning Works Pinned files are stored in your cache directory alongside other cached files, but they aren't subject to cache size limitations or eviction rules. When you pin content, ShadeFS creates a complete local copy that persists until you explicitly unpin it. **This means you can pin as much content as your local storage can accommodate, regardless of your configured cache size.** {% embed url="" %}
## Working Offline Pinned files remain fully accessible even offline. Any changes you make to pinned files while offline are marked as "dirty" in the system, indicating they need to be synchronized with the cloud. These files are protected from cache eviction until they can be successfully synchronized to ensure no work is lost when you come back online. When reconnecting or restarting ShadeFS, the system automatically identifies any changed files and synchronizes them with the Shade cloud. ## Conflicting Changes If someone else changed the same file while you were offline, ShadeFS keeps both versions. Their version keeps the original name, and your version is saved next to it with `-conflict-` and a number added to the end of the name, for example `edit.prproj-conflict-2847193021`. Nothing is overwritten, so you can compare the two and keep the one you want. The same applies if you and someone else both create a file with the same name. ## Pinning Hierarchy ShadeFS handles pinning with a hierarchy system. When working with nested folders: * Pinning a parent folder automatically includes all its contents * If both an outer folder and an inner folder are pinned, unpinning the inner folder won't have any effect as the outer folder's pin status takes precedence * You can selectively pin specific files or folders within an unpinned parent folder ## Flexible Usage A key advantage of ShadeFS pinning is its flexibility: * You can pin files without mounting the drive first * There's no limit to how much content you can pin (beyond your available storage) * Pinned status persists across system restarts and reconnections * You can continue to work with pinned files even when offline * You can keep working while files pin. Files you open through the mounted drive always download ahead of pinned files, so pinning slows down while you're actively playing media rather than slowing your playback. ## Managing Pinned Content {% hint style="info" %} Pinned files will save all files that you pin fully offline, avoiding your cache limits that you set, which are used for ephemeral and standard storage. This means that it is possible for you to pin **more than what you have available left on your cache drive depending on what you're trying to pin.** {% endhint %} To pin files or folders: 1. Open the Shade application 2. Navigate to the desired content 3. Right-click and select "Pin to Cache" To unpin content: 1. Right-click the pinned item 2. Select "Unpin from cache" Unpinning a file also removes its local copy. You can also unpin files from **Settings > ShadeFS > Cache Management**. To view all pinned files or folders, you can navigate to the **Pinned Items** page, which you can access at the drive or the workspace level. ### Pinning from Finder (macOS) On macOS, you can also pin and unpin directly from Finder. Right-click a file or folder on a mounted Shade drive and select **Pin to Cache** or **Unpin from Cache**. If you've selected several items, the option shows how many items will be pinned or unpinned. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://academy.shade.inc/shadefs/pinning-files-offline.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.