Skip to content

Folder Types: Who May Do What

Every folder has a type on each device, chosen independently per device, and the type is a one-line statement of trust:

  • sendreceive — the default. I send my changes, I accept yours. The folder converges.
  • sendonly — I send my changes. Yours are not applied here.
  • receiveonly — I accept your changes. Mine are not sent.

The same folder can be all three on three different machines, and the classic setups fall straight out of it: one authoritative machine (send-only) publishing to several readers, or a backup target (receive-only) that can never push its own accidents back upstream. The lab runs a second folder — bulletin, the notice board — through both shapes.

Act 1: the master and the reader

Willow is send-only for the board; juniper is send-receive. Willow's meeting notes sync to juniper as usual — hashes equal, reader served. Then juniper, quite reasonably, pins up a notice of its own: announcement.txt, lost property, one green umbrella. Willow's folder afterwards:

$ ls board-a board-b
board-a:
meeting-notes.txt

board-b:
announcement.txt
meeting-notes.txt

$ test ! -e board-a/announcement.txt
[exit 0]

The announcement was never refused, queued, or errored — it simply does not exist in willow's world. Willow's status for the folder says why, in its own terms:

{
  "state": "idle",
  "needFiles": 0,
  "needBytes": 0,
  "localFiles": 1,
  "globalFiles": 1
}

As far as the send-only side is concerned, the shared truth about this folder has one file in it. Incoming announcements are not changes to be rejected; they are not changes at all.

Act 2: the reader who edits anyway

Swap the roles: willow send-receive, juniper receive-only. Now juniper edits the meeting notes locally — adds a line about the roof fund. Nothing stops it; receive-only governs sync, not your editor. What happens is quieter:

$ sha256sum board-a/meeting-notes.txt board-b/meeting-notes.txt
a2875362a5ab1a183251e8313eedba924688e247a5b11e1a5659249a80b060dd  board-a/meeting-notes.txt
ccfd62e260242912f6e7c94b201f136569136bea6bc5e131de8f32dd7e5b164d  board-b/meeting-notes.txt

Two different files, and they stay different: juniper's edit is never sent, willow's copy never changes. But the divergence is not secret. Juniper's own status for the folder shows its disk disagreeing with the shared truth:

{
  "state": "idle",
  "needFiles": 0,
  "localFiles": 2,
  "globalFiles": 1,
  "localBytes": 221,
  "globalBytes": 119
}

localFiles 2, globalFiles 1 — juniper holds two files' worth of folder (the shared notes, its unsent edit counted in bytes, and the announcement from Act 1), while the folder's agreed content is one file. This is the gauge to watch on any receive-only device: local and global drifting apart is the sound of local changes piling up against a door that only opens inward.

Throwing local changes away

A receive-only folder gets one extra verb, and the API exposes it: revert — discard my local changes and make my copy match the shared one exactly.

$ curl -s -X POST -H "X-API-Key: $KEY" "http://127.0.0.1:8395/rest/db/revert?folder=bulletin"
[HTTP 200]

$ sha256sum board-a/meeting-notes.txt board-b/meeting-notes.txt
a2875362a5ab1a183251e8313eedba924688e247a5b11e1a5659249a80b060dd  board-a/meeting-notes.txt
a2875362a5ab1a183251e8313eedba924688e247a5b11e1a5659249a80b060dd  board-b/meeting-notes.txt

The edit is gone, the hashes agree. Read the lab's final inventory for the fuller price: juniper's announcement.txt — a local addition, remember, in a folder where it could never be sent — is gone too. Revert means the whole of your side of the folder, edits and additions alike. It is exactly the right button for "this backup target has been fiddled with; make it true again," and exactly the wrong one to press hoping it only undoes the last edit.

Check: the type is per device and per folder, and it is the first thing to verify when changes flow one way but not the other — in the config ("type" on the folder), or in the GUI's folder panel. Half of all "Syncthing isn't syncing" is a folder patiently doing precisely the send-only or receive-only job it was given.