Sync Configuration

Sync Options

Strayfiles supports multiple sync methods. Choose what works for your workflow.

Git Sync

Enable automatic Git commits in strayfiles.toml:

[sync]
git_auto_commit = true
commit_message = "strayfiles: auto-save"
git_remote = "origin"

Git Settings

Setting	Type	Default	Description
`git_auto_commit`	boolean	`false`	Auto-commit on save
`commit_message`	string	`"strayfiles: auto-save"`	Commit message template
`git_remote`	string	`"origin"`	Remote to push to

How It Works

You save a note in Strayfiles
Changes are committed with your configured message
Commits are pushed to your remote

Works with any Git remote: GitHub, GitLab, Bitbucket, self-hosted.

Folder Sync Providers

Strayfiles works seamlessly with folder sync providers. Just place your notes in a synced folder.

iCloud

[settings]
roots = ["~/Library/Mobile Documents/com~apple~CloudDocs/notes"]

Or use iCloud Drive’s visible path:

[settings]
roots = ["~/iCloud Drive/notes"]

Dropbox

[settings]
roots = ["~/Dropbox/notes"]

Syncthing

Point to any Syncthing-managed folder:

[settings]
roots = ["~/Sync/notes"]

OneDrive

[settings]
roots = ["~/OneDrive/notes"]

How Folder Sync Works

Your notes live in a synced folder
The sync provider handles file transfer
Strayfiles watches for changes
When files change, Strayfiles re-indexes

No special configuration needed - if your folder syncs, Strayfiles sees the changes.

Stray Cloud (Pro)

Pro users get Stray Cloud with end-to-end encryption via Supabase:

Real-time sync across devices
Zero-knowledge encryption
No file path dependencies
Works alongside folder sync

See Stray Cloud for setup details.

GitHub Sync (Pro Add-on)

Pro users can also enable GitHub Sync to back up notes to a private GitHub repository:

Secure Device Flow OAuth authentication
Dual-sync with Stray Cloud (realtime + version control)
Content-hash conflict detection
iOS sees sync status (read-only)

GitHub Sync gives you version-controlled backup alongside real-time cloud sync.

See GitHub Sync for setup details.

Mixing Sync Methods

You can combine methods:

[settings]
# Some notes in iCloud
roots = [
  "~/iCloud Drive/personal-notes",
  "~/projects"  # Git-managed projects
]

[sync]
# Auto-commit for Git repos
git_auto_commit = true

Sync Conflicts

When using folder sync providers, conflicts are handled by the provider:

iCloud: Creates conflict copies
Dropbox: Creates “conflicted copy” files
Syncthing: Uses its conflict resolution

For Stray Cloud, Strayfiles has built-in conflict resolution.

Tips

Git for code projects: Use Git sync for notes in code repositories - they’ll be committed alongside your code.

Folder sync for personal notes: Use iCloud/Dropbox for personal notes that don’t belong in a Git repo.

Stray Cloud for teams: Use Stray Cloud when you need real-time collaboration or encrypted sync across many devices.