How a folder treats files

Every rule a synced folder follows for a file, from what it takes in and what it keeps to what it removes, names and holds for you.

A folder syncs both ways, so a file you delete can move its item to the bin, and an item that leaves the folder can remove its file. These rules decide when, and what stops it by mistake. Change or stop syncing a folder changes a folder's settings.

What a folder takes in

The include and ignore lists, gitignore patterns, say which paths a folder reads, and ignore wins. A path with a part that starts with a period is read only where an include pattern names it. Whatever the lists say, a folder never takes in these:

Never taken inNames
Secrets.env, .env.*, *.pem, *.key, *.p12, *.pfx, SSH keys such as id_ed25519, .netrc, .npmrc, .pgpass, .git-credentials and credential files
Files a computer keeps for itself.DS_Store, Thumbs.db, ._*, desktop.ini and the like
Temporary files*.swp, *~, *.tmp, *.part, *.crdownload and the like
Symbolic linksNeither taken in nor followed

A push names each secret it leaves out, as server.pem: not taken, because its name is one a secret goes by. The contract lists every name.

A file the lists stop reading keeps its item, sends no edits and counts as unreached until they read it again.

What a folder does with each file

The folder's query says which items it holds. Whether an item was ever in the folder decides what happens to its file.

WhenWhat the folder does
A new file matches the queryCreates its item, and writes marfa_id and any missing type, tier and title into a note
A new note names a type, tier, state or tag the query doesn't holdCreates the item and keeps the file as unmatched. With outside_query: hold, holds the file unsent
A photo, PDF or other file whose type the query doesn't holdSends nothing, unless a note embeds it or it's attached to one
An item leaves the query's types, tiers, tags, filter or beneathKeeps the file as unmatched, and still sends its edits
An item leaves the query's states, or moves to the bin, or is purgedRemoves the file at the next pull, unless it changed since Marfa wrote it

A new file never goes for falling outside the query's states: a note you write with state: archived among active items becomes an archived item, kept as unmatched. Once a pull finds it in a state the query holds, leaving those states removes its file.

Unmatched files

marfa folders unmatched lists them. --remove takes them off the disk once you answer y or yes, or a script passes --yes, and the items stay. A file you changed, or whose edit waits to be sent, stays and is named. Don't delete an unmatched file by hand: that moves its item to the bin.

Hold new files outside the query

With outside_query set to hold, a new file the query wouldn't hold waits on disk, with no item and nothing written into it:

Terminal
marfa folders push Notes
1 new file(s) held outside the query, not sent: the folder's outside_query is hold, so each is sent once it matches the query or the setting is send; `folders unmatched` lists them

marfa folders status lists it as held with the flag outside_query. Once the query holds it, or outside_query is send, the next scan sends it. It never counts toward a large addition.

Deleting, moving and renaming

  • You delete a file: its item moves to the bin after a five-second grace, so an editor that saves by replacing the file isn't taken for a delete. If another device changed what the file showed, the file comes back with that change instead.
  • You move or rename a file: the item stays. Between two folders on one computer, the folders keep one item, following a note by its marfa_id and any other file by its identity or exact bytes.
  • The folder can't tell where a file went, because another folder can't be read or several hold its bytes: the deletion waits, and a watch looks again each minute.

A save made as Marfa writes

Marfa moves a file aside as .marfa-kept-<id>.tmp before replacing or removing it. A save it didn't read goes back at the path, or under the next numbered name if another file took it, flagged kept; a save of .marfa/folder.yaml stays in the root under its hidden name. After a stop, the next scan settles each hidden file, never deleting one or bringing back a file you deleted.

A folder added again over its files

Added again, such as after a restore, a folder takes each file back as the item it was.

File names

A new item's file is named from its title: /, \ and : become -, a control character becomes a blank, whitespace at either end and leading periods go, and an empty name is untitled. A name is cut to 255 bytes, keeping its extension.

Names that differ only in case or Unicode form are the same name, as a Mac's disk compares them: Plan.md and plan.md are one file.

When two items claim one nameWhich keeps it
Neither has a file yetThe one created first. The other gets Plan (2).md, on every device
One already has its file thereThat one
Two files on disk differ only in caseThe one already bound, or else the first. The other is held with the flag name until you rename it

Large changes

A folder holds a large addition or removal until you confirm it, as Fix a folder shows. Set the thresholds with --removal-threshold and --addition-threshold:

SettingDefaultPauses when
removal_threshold.files and .fraction10 and 0.25One pass would remove more than both: over 10 files and over a quarter of those the folder holds
removal_threshold.ceiling100One pass would remove over 100 files, whatever share they are
addition_threshold.files and .fraction50 and 0.25New files exceed both, counting those sent in the last ten minutes. A folder with no files judges by count alone

Nothing moves to the bin while a removal waits. The first sync isn't an addition, and while one waits, edits keep going and new files join it.

Terminal
marfa folders push Notes
0 created, 0 updated, 0 renamed, 3 unchanged, 60 missing, 0 deleted, 0 skipped
a large removal waits: 60 delete(s) not sent; `folders confirm` sends them, `folders restore` writes the files back

A file too large to send

A write larger than the server takes in one request is held and flagged refused, with its size and the limit in bytes. The limit is 1 MiB unless MARFA_MAX_REQUEST_BYTES sets another, and counts the JSON sent. A file at nine tenths of it gets a size warning.

Make it smaller, or raise the limit, and the next sync sends it.

A directory Marfa can't read or write

  • The folder's directory is missing, as on a disk that isn't connected: nothing moves to the bin, and commands say so.
  • A directory or file can't be read: nothing in it moves to the bin, and marfa folders status flags it unreadable.
  • A volume can't rename safely, such as exFAT on a Mac: Marfa replaces and removes no file there, and counts its item unwritten.
  • A different directory stands at the folder's path: the folder doesn't read it, and carries on when the original returns.

Know whether a push finished

Exit codeMeaning
0The push finished. A refused edit stays in its file, flagged refused, until you change the file
3A write is left unsent, or catching up with the server failed. Push again
5The server refused the credential

A push under a rate limit doesn't wait. It keeps its changes waiting and exits 3, as Fix a folder shows. A watch waits by itself.

The rules are in the contract's folder-guards, folder-files, folder-documents and folder-sync chapters.

On this page