Choosing What Travels: Ignores

A shared folder does not have to mean every file in it. Every working directory grows things that belong to the machine, not the project — drafts in progress, temp files, a private scratch folder. Syncthing's answer is a per- folder pattern list in a file called .stignore.

The pattern file that does not travel

Willow gets an ignore file. Deliberately, its contents are one line — hold that thought:

$ cat share-a/.stignore
#include .stglobalignore

The first thing to know about .stignore is what it does not do. It is not synced. Juniper's folder, after everything settles:

$ ls -a share-b
.
..
.stfolder
events-list.txt
issue-12-draft.md
photos

No .stignore. Ignore rules are each device's own declaration of what it will not send or accept, and Syncthing treats them as local configuration, like the folder's path. This is a feature — your laptop can refuse the huge video renders your desktop produces — and a paper cut: a team that wants shared rules must find another way to share them. Which is what the one line above is for.

The shared list

.stignore's #include directive pulls in another file — and that file is an ordinary file, so it syncs like any other:

$ cat share-a/.stglobalignore
*.tmp
scratch

Two patterns, in the dialect all ignore files use: *.tmp matches any file whose name ends in .tmp, and scratch matches a file or folder of that name. Willow writes it, juniper receives it as a normal arrival, and then juniper gets the same one-line .stignore (created locally, by hand — only the included file travels). Now both devices apply the same rules, and any device can edit the shared list for everyone.

The lab then plants test files on both sides: scratch-notes.tmp and a scratch/ folder on willow, layout-ideas.tmp on juniper. After the folder settles:

$ ls -a share-a
…
.stglobalignore
.stignore
events-list.txt
issue-12-draft.md
photos
scratch
scratch-notes.tmp

$ ls -a share-b
…
.stglobalignore
.stignore
events-list.txt
issue-12-draft.md
layout-ideas.tmp
photos

Read it as two absences. Willow's scratch-notes.tmp and scratch/ are at home on willow and nowhere else; juniper's layout-ideas.tmp likewise never left. The assertions, for the record:

$ test ! -e share-b/scratch-notes.tmp
[exit 0]
$ test ! -e share-b/scratch
[exit 0]
$ test ! -e share-a/layout-ideas.tmp
[exit 0]

And the control, so the silence isn't mistaken for a broken folder: an ordinary file created on willow in the same minutes — real- update.txt — arrived on juniper immediately. The folder was never ignoring everything. It was ignoring exactly the two patterns.

Ignores are per-folder, and they bite

Two cautions the model makes obvious once stated. Ignores live in the folder root and apply to that folder only — the same *.tmp rule must be repeated (or included) in every folder that wants it. And an ignored file is invisible to sync entirely: it is not sent, not requested, and not reported as missing. If a teammate swears a file "never arrived", a pattern quietly matching its name is a prime suspect — chapter 10 lists it, and the API will show you a device's ignore lines (rest/db/ignores, chapter 9) so you can check without guessing.

Check: on your own folder, write a .stignore containing *.tmp, create notes.tmp and notes.txt side by side, and watch the other device. One file arrives; the other simply never exists there. Then delete the pattern and rescan — the missing file is not lost, only uninvited, and it will travel as soon as the rule lets it.