Skip to content

docs(run): say a folder refuses a backref filter and a placement with .. #701

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aicayzer merged 2 commits into from
Oct 31, 2026
Merged

docs(run): say a folder refuses a backref filter and a placement with .. #701

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0271702
docs(run): say a folder refuses a backref filter and a placement with ..
aicayzer Oct 31, 2026
5fba1a3
docs(folders): say where a backref folder query is refused
aicayzer Oct 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion content/docs/run/sync-a-folder.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:
Expand Down
Loading