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 in | Names |
|---|---|
| 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 links | Neither 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.
| When | What the folder does |
|---|---|
| A new file matches the query | Creates 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 hold | Creates 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 hold | Sends nothing, unless a note embeds it or it's attached to one |
An item leaves the query's types, tiers, tags, filter or beneath | Keeps the file as unmatched, and still sends its edits |
| An item leaves the query's states, or moves to the bin, or is purged | Removes 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:
marfa folders push Notes1 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 themmarfa 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_idand 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 name | Which keeps it |
|---|---|
| Neither has a file yet | The one created first. The other gets Plan (2).md, on every device |
| One already has its file there | That one |
| Two files on disk differ only in case | The 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:
| Setting | Default | Pauses when |
|---|---|---|
removal_threshold.files and .fraction | 10 and 0.25 | One pass would remove more than both: over 10 files and over a quarter of those the folder holds |
removal_threshold.ceiling | 100 | One pass would remove over 100 files, whatever share they are |
addition_threshold.files and .fraction | 50 and 0.25 | New 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.
marfa folders push Notes0 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 backA 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 statusflags itunreadable. - 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 code | Meaning |
|---|---|
0 | The push finished. A refused edit stays in its file, flagged refused, until you change the file |
3 | A write is left unsent, or catching up with the server failed. Push again |
5 | The 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.