syncthng

Docs

syncthng keeps a directory in sync using a private GitHub repo as storage and git to decide when to push or pull. You work on one machine at a time; it handles the rest on a schedule.

Requirements

git
Change detection and transport.
gh
GitHub CLI, authenticated via gh auth login.
bun
The runtime the CLI is built for.

Install

Nothing to install. Run it with npx and npm fetches the latest version on demand.

$npx syncthng init

Quick start

Run init and follow the prompts. Browse to a folder, name the repo, choose visibility and an interval, and pick what to ignore.

Commands

  • npx syncthng init

    Set up a new folder to sync (interactive).

  • npx syncthng sync [name]

    Sync now. Omit the name to sync all folders.

  • npx syncthng list

    List configured folders and their intervals.

  • npx syncthng status

    Show the live git state for each folder.

  • npx syncthng remove [name]

    Stop syncing a folder. Files are kept.

  • npx syncthng service repair

    Re-register every scheduled task.

  • npx syncthng service uninstall

    Remove every scheduled task.

How it works

  1. Commit. Any local edits are staged and committed before comparing with the remote.
  2. Compare. It fetches origin and reads how far ahead or behind the branch is.
  3. Move. If the branch is behind, it fast-forwards a pull. If it is ahead, it pushes. If it has diverged, it rebases and pushes, aborting safely on conflict.

Scheduling

Each folder gets one short-lived native scheduled task at its own interval, with no background daemon holding memory.

  • macOSlaunchd, one LaunchAgent per folder
  • Linuxcron, one crontab entry per folder
  • Windowsschtasks, one scheduled task per folder

Config

Your folders live in ~/.config/syncthng/config.json (%APPDATA%\syncthng on Windows). Removing a folder unregisters its task but never touches your files.