charles/nautilus-syncthing-extension
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Live Syncthing status emblems in GNOME Files (Nautilus) — non-blocking, per-file, custom SVGs
1 commit 1 branch 0 tags 35 KiB
  • Python 80.8%
  • Shell 19.2%
Find a file
Exact
Charles Jacquin 14b68c43e8
 feat: Syncthing status emblems for Nautilus 
Live folder + per-file sync emblems in GNOME Files via the GTK4
nautilus-python API. Non-blocking (cache-read callback + background REST
poll); per-file state from db/need + folder/errors + peer db/completion,
so cost is flat regardless of file count. Bundles custom emblem SVGs that
resolve under any icon theme. Install/uninstall scripts, MIT license.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 14:55:24 +02:00
emblems feat: Syncthing status emblems for Nautilus 2026-06-16 14:55:24 +02:00
.gitignore feat: Syncthing status emblems for Nautilus 2026-06-16 14:55:24 +02:00
install.sh feat: Syncthing status emblems for Nautilus 2026-06-16 14:55:24 +02:00
LICENSE feat: Syncthing status emblems for Nautilus 2026-06-16 14:55:24 +02:00
README.md feat: Syncthing status emblems for Nautilus 2026-06-16 14:55:24 +02:00
syncthing_emblems.py feat: Syncthing status emblems for Nautilus 2026-06-16 14:55:24 +02:00
uninstall.sh feat: Syncthing status emblems for Nautilus 2026-06-16 14:55:24 +02:00

README.md

nautilus-syncthing-extension

Live Syncthing status emblems in GNOME Files (Nautilus). Folders and their contents get a small corner badge reflecting real sync state — without polling per file or blocking the file view.

Emblem Meaning
🟢 emblem-st-ok folder fully synced
🔵 emblem-st-sync syncing / pending (folder, file, or any parent of a pending file)
🔴 emblem-st-error sync error (file + its parent folders)

Synced files inside a folder are left unbadged — only the folder root keeps the green check — so the view stays clean.

Requirements

  • GNOME Files (Nautilus) 43+ — uses the GTK4 Nautilus 4.1 extension API
  • nautilus-python (a.k.a. python-nautilus)
  • python-gobject
  • A running Syncthing with its config at ~/.local/state/syncthing/config.xml (the API key and GUI address are read from there — nothing to configure)

On Arch:

sudo pacman -S python-nautilus python-gobject

Install

./install.sh

It copies the extension to ~/.local/share/nautilus-python/extensions/, the custom emblem SVGs to ~/.local/share/icons/hicolor/scalable/emblems/, and restarts Nautilus. No root, no system files touched.

Uninstall with ./uninstall.sh.

Note: the installer intentionally does not drop an index.theme into ~/.local/share/icons/hicolor. Doing so shadows the system hicolor theme and breaks every application icon. GTK resolves the emblem SVGs from the emblems/ directory without any extra theme metadata.

How it works

  • The Nautilus callback (update_file_info) only reads an in-memory cache, so it never blocks the file view — language/runtime speed is irrelevant here.
  • A background thread polls the Syncthing REST API every POLL_SECONDS (5s) and invalidates affected files so Nautilus re-stamps them.
  • Per-file state is cheap: /rest/db/need returns only out-of-sync files (one call per folder, not per file) and /rest/folder/errors the failed ones. Pending files plus their ancestor directories get the sync emblem.
  • Outgoing transfers: on the sending device Syncthing already considers the folder complete, so the root is also checked against each peer's /rest/db/completion and shown as syncing until every peer is 100%.

Total cost for N folders with one peer each is a handful of localhost calls every 5 seconds — flat regardless of how many files the folders hold.

Tuning

  • POLL_SECONDS (top of syncthing_emblems.py) — refresh interval.
  • EMBLEM — map states to different icon names if you prefer theme emblems (e.g. emblem-synchronizing / emblem-important / emblem-default).

After editing the script or SVGs, run nautilus -q; the next launch reloads.

Limitations

  • Nautilus has no extension API for the sidebar bookmarks ("places"), so emblems appear only in the main icon/list view, not on sidebar entries.
  • The active icon theme must provide the emblem icons; the bundled custom SVGs cover this for any theme.

License

MIT — see LICENSE.