Versioning and File History
File versioning in Syncthing preserves old copies of files when they are modified or deleted by a remote peer. It acts as a local undo buffer.
Syncthing versioning only triggers on changes received from remote peers. If you locally delete a file, it is not versioned — it's just deleted. This is a critical distinction.
Use versioning as an emergency safety net, not a primary backup strategy. For true backup, use Restic.
Where Versions Are Stored
All version history is stored in a hidden .stversions directory inside the synced folder:
/var/www/html/uploads/
├── images/
│ └── photo.jpg ← current file
└── .stversions/
└── images/
└── photo.jpg~20260413-091523 ← old version
The Four Versioning Modes
1. No File Versioning (Default)
No old versions are kept. A deletion from a peer results in immediate local deletion with no recovery option.
Best for: Folders where disk space is critical and recovery is handled by a separate backup system (restic).
2. Trash Can Versioning
Deleted or replaced files are moved to .stversions and kept for a configurable number of days.
| Setting | Description |
|---|---|
| Clean out after | Number of days to keep old versions (default: 30) |
Day 0: peer deletes photo.jpg
→ Moved to .stversions/images/photo.jpg~20260413-091523
Day 30: cleanup runs
→ photo.jpg~20260413-091523 is permanently deleted
Best for: Casual use, desktop machines. Simple time-based cleanup.
3. Simple Versioning
Keep the last N versions of a file. On overflow, the oldest version is deleted.
| Setting | Description |
|---|---|
| Keep versions | Number of versions to retain per file (default: 5) |
photo.jpg~1 (oldest)
photo.jpg~2
photo.jpg~3
photo.jpg~4
photo.jpg~5 (newest)
→ On 6th change: photo.jpg~1 is deleted, others shift
Best for: Folders where you need a fixed-depth undo history per file.
4. Staggered Versioning
The most sophisticated option. Keeps more recent versions at fine granularity and fewer older versions at coarse granularity, similar to Grandfather-Father-Son (GFS) retention.
| Period | Granularity |
|---|---|
| Last hour | One version per 30 seconds |
| Last day | One version per hour |
| Last month | One version per day |
| Beyond that | One version per week |
Best for: Production servers, NAS devices, media libraries. Gives you fine-grained recent history plus long-term retention without unlimited disk growth.
Configuring Versioning in the GUI
- Expand the folder card → Edit.
- Go to the Versioning tab.
- Choose the versioning type from the dropdown.
- Configure the parameters (days, count, etc.).
- Click Save.
Recovering a File from Versions
Version files are just regular files in .stversions. Recovering is a manual process:
# List all versions of a specific file
ls -la /var/www/html/uploads/.stversions/images/photo.jpg*
# Recover a specific version by copying it back
cp "/var/www/html/uploads/.stversions/images/photo.jpg~20260413-091523" \
/var/www/html/uploads/images/photo.jpg
# Syncthing will detect the restored file and sync it to peers
When you copy a file back from .stversions, Syncthing treats it as a new local change and syncs it to all peers — effectively performing a distributed rollback.
Disk Space Planning
Staggered versioning can accumulate significant disk usage on busy folders. Monitor it:
# Check size of version history
du -sh /var/www/html/uploads/.stversions
# Find the largest version files
find /var/www/html/uploads/.stversions -type f -printf '%s %p\n' \
| sort -rn | head -20 | numfmt --to=iec
Summary: When to Use Each Mode
| Mode | Disk Usage | Recovery Ease | Best For |
|---|---|---|---|
| None | Minimal | None | Disk-constrained + external backup |
| Trash Can | Low (time-based) | Easy | Desktops and laptops |
| Simple | Fixed | Easy | Dev/test folders |
| Staggered | Medium (grows over time) | Easy | Production, media libraries |