From 0271702579475846657c0096758bebc241fd4cc8 Mon Sep 17 00:00:00 2001 From: August Cayzer Date: Sat, 31 Oct 2026 00:02:00 +0000 Subject: [PATCH 1/2] docs(run): say a folder refuses a backref filter and a placement with .. --- content/docs/run/sync-a-folder.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/run/sync-a-folder.mdx b/content/docs/run/sync-a-folder.mdx index cc8d4aa8..32d0b1df 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: Marfa refuses the settings with `validation_error`, naming `query.filter`. 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: From 5fba1a3999deef78d2de53a8db2222b65d7d4a13 Mon Sep 17 00:00:00 2001 From: August Cayzer Date: Sat, 31 Oct 2026 00:41:49 +0000 Subject: [PATCH 2/2] docs(folders): say where a backref folder query is refused --- content/docs/run/sync-a-folder.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/run/sync-a-folder.mdx b/content/docs/run/sync-a-folder.mdx index 32d0b1df..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. **A folder's `filter` can't use a `backref` condition**, because a folder on disk can't follow one: Marfa refuses the settings with `validation_error`, naming `query.filter`. +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: