Set Up a Syncthing Folder with Safe Ignore Rules

Get a Syncthing folder wrong and it will happily replicate the mistake to every paired device before you notice. This guide gets you a named folder, a config path you can find again, and an ordered .stignore that keeps junk and secrets out of the sync. Allow about 20 minutes for the setup, plus however long the first scan and transfer take.

Before you start

You need Syncthing installed on this Debian machine and a second device you control. Decide on a directory for the files, such as /home/ALICE/Sync/notes. Replace ALICE and the example device ID below with your own values. The commands are ordinary user commands unless marked as needing elevated privileges.

This guide was checked against the installed package's syncthing v1.27.2-ds4. The local manpage is labelled v1.27.0, so lean on syncthing --help if a later package changes a command. The 1.27 configuration change matters here: on Unix-like systems the new default config location is $XDG_STATE_HOME/syncthing, or $HOME/.local/state/syncthing when that variable is unset. Older installs may still use $HOME/.config/syncthing.

1. Find the paths and device ID

Run the path query before you edit anything. It tells you where this install keeps config.xml, the device certificate, database, logs and default sync directory.

syncthing --paths
syncthing --device-id
syncthing --version

On a fresh install, --device-id can fail because cert.pem does not exist yet. That is expected until Syncthing has generated its identity. The version command should print something like:

syncthing v1.27.2-ds4 "Gold Grasshopper" (go1.22.2 linux-amd64)

2. Generate the initial configuration

If this is a new user account, generate the configuration explicitly. This creates the device key and certificate, writes config.xml, and then exits. You can also suppress the default folder so you only add the folders you actually intend to share.

syncthing generate --no-default-folder

Verify the identity now exists:

syncthing --device-id

The output is a hyphenated device ID. Add this machine to the other device through its Syncthing interface or configuration. A device ID identifies a key pair, not a user account. Never paste the private key into a ticket or chat.

If you generated the configuration in the wrong directory, stop before sharing anything. Check the path, remove only that newly created and unused directory, then run the command again with --home=/absolute/path. Do not remove an existing Syncthing directory: it holds the identity and database.

3. Start Syncthing and add a folder

Start Syncthing as the account that owns the files. Avoid sudo syncthing unless you have a specific, documented reason: running it as root creates a separate root-owned identity and can make later file access confusing.

syncthing --no-browser

The process stays in the foreground and prints the GUI address among its early log messages. On this installation the usual local address is http://127.0.0.1:8384. Open that address from the same machine, then set a GUI username and a strong password before you expose the GUI beyond localhost.

Add the other device by its device ID, accept the pairing on both sides, then add a folder. Use a stable folder ID such as notes, a label such as Shared notes, and set its local path to:

/home/ALICE/Sync/notes

Choose the folder mode deliberately. Send and Receive accepts changes in both directions. Send Only stops this machine accepting remote file changes. Receive Only stops it sending local changes onward. These modes guard against some classes of mistake, but they are not a backup: a deletion can still propagate according to the folder's mode and history.

printf 'syncthing test\n' > /home/ALICE/Sync/notes/syncthing-test.txt
sha256sum /home/ALICE/Sync/notes/syncthing-test.txt

Once the second device reports the file as up to date, remove the test file through the normal file manager or shell. If it turns out to have been a real file by accident, restore it from your backup before letting synchronisation settle. Syncthing is a synchroniser, not an undelete tool.

4. Add ordered ignore rules

Create .stignore in the root of the synced folder, not in Syncthing's configuration directory. The file itself is never synchronised. Patterns are relative to the folder root, and the first matching pattern wins, so put specific exceptions before broad rules where needed. A leading ! includes a match that an earlier rule would otherwise ignore.

// macOS metadata can be removed when it blocks an empty directory
(?d).DS_Store

// editor and build noise
*.swp
build/

// local secrets: keep these on this device
*.key
*.pem
!public.pem

The * wildcard does not cross a directory separator; use ** when it must. A pattern such as /private.txt matches only the folder root, while private.txt can match that name anywhere below the root too. A directory pattern ending in / matches its contents but not the directory entry itself, so drop the trailing slash when that entry must match as well.

An ignore rule does not delete files already present on a peer. It only changes what Syncthing considers for synchronisation. The (?d) prefix permits removal of an ignored file when it is the only thing stopping an otherwise empty directory from being removed. Reserve it for disposable operating-system files.

To share a common rule set, .stignore can include another file with a line such as:

#include shared-ignore.txt

The included file must exist, and it must not be included more than once. An included file can itself include another, with nested paths resolved relative to the file doing the including. The patterns still apply from the synced folder root regardless.

5. Check changes and recover cleanly

After editing .stignore, use the GUI's folder scan or wait for the watcher to notice the change. If a file unexpectedly vanishes from the synchronised view, stop the affected folder in the GUI before you delete or rewrite rules. Move the questionable file outside the synced folder, correct the rule, rescan, then restore it only once you have confirmed the fix.

For automation, the local CLI exposes the running instance through the GUI/API. Discover its exact commands with:

syncthing cli --help
syncthing cli show --help
syncthing cli operations --help

These commands depend on a running instance and its API authentication. Keep the API bound to a trusted address, protect its key, and never put credentials in shell history.

Done means

• Paths confirmed. syncthing --paths identifies the configuration and database locations you expect.
• Identity generated. syncthing --device-id prints this machine's identity after initial generation.
• Devices paired. The intended devices are paired by device ID, with GUI authentication configured.
• Sync proven. The test file arrived on the peer and was removed deliberately.
• Ignore rules in place. .stignore sits in the folder root, uses ordered rules, and keeps secrets out of synchronisation.
• Recovery understood. You know how to stop a folder and restore a file before changing a rule that misbehaves.