diff --git a/content/docs/run/sync-a-folder.mdx b/content/docs/run/sync-a-folder.mdx index cc8d4aa8..b0117fd0 100644 --- a/content/docs/run/sync-a-folder.mdx +++ b/content/docs/run/sync-a-folder.mdx @@ -90,7 +90,7 @@ Keep the directory out of iCloud Drive, other cloud-synced folders and network s Check the plan first. **The query decides every item the folder takes in.** A query that names only a type holds every active and archived item of that type in the library tier, and the first sync writes all of them to disk. With no `types`, it holds every type the key reads except `system.*`. -Set `tier: all` to write matching items from both the library and feed tiers as files. To narrow the query, use `filter`, `tier`, `state` or `beneath`, as [list, filter and search](/build/list-filter-search) describes. +Set `tier: all` to write matching items from both the library and feed tiers as files. To narrow the query, use `filter`, `tier`, `state` or `beneath`, as [list, filter and search](/build/list-filter-search) describes. **A folder's `filter` can't use a `backref` condition**, because a folder on disk can't follow one: the instance refuses the settings with `validation_error`, naming `query.filter`, and a computer refuses them before it sends them. Then confirm, and sync once: @@ -136,6 +136,8 @@ query: Edit the file and the next sync sends your change to the instance through [Update a folder](/api-reference/folders/updateFolder), so **it reaches every computer that follows the folder**. `folder` and `version` in this file are Marfa's to write. [Folder](/catalog/folder) lists every other setting. +**A `first_placement` directory can't hold a `..` name.** Write the directory the new files go in, such as `Notes/Tickets`, not `Notes/../Tickets`. Marfa refuses the settings with `validation_error`, naming `first_placement` and the type, because a computer treats a path with `..` as outside the folder and writes no file there. + **Each setting you send replaces its value whole.** Omitted settings the folder type declares stay, and every accepted change removes stored settings the type does not declare. A change names the version it starts from: changes to different settings can merge, but a collision is refused without changing the folder ([folder change rules](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsfolder-change-declared)). This edit leaves a `drafts` directory alone and tags every new note: