Staggered Versioning Deep Dive

Syncthing can keep a history of changed or deleted files in a .stversions directory. The staggered versioner is the most useful mode: it keeps more versions for recent changes and fewer for older ones — similar to macOS Time Machine.

Learning Focus

Set up staggered versioning as a fast recovery layer for accidental overwrites, while leaving long-term backup to Restic. Know the storage cost before enabling it on large sync folders.

Tool Snapshot

Versioning Mode	Retention	Storage Impact	Best For
None	No history	None	Trusted single-editor environments
Trash Can	Until manually cleared	High	Simple undo on small folders
Simple	N last versions per file	Moderate	Single device, predictable space
Staggered	Time-based graduated retention	Tunable	Production multi-device environments
External	Custom script	Depends	Integration with external VCS or backup

How Staggered Versioning Works

flowchart TD
  A[File changed or deleted] --> B[Current version moved to .stversions/]
  B --> C{Age of version?}
  C -->|Less than 1 hour| D[Keep each change — high frequency]
  C -->|1 hour to 1 day| E[Keep 1 version per hour]
  C -->|1 day to 30 days| F[Keep 1 version per day]
  C -->|30 days to 365 days| G[Keep 1 version per week]
  C -->|Older than max age| H[Purge automatically]

Configuring Staggered Versioning

config.xml — staggered versioning for a folder

<folder id="docs-sync" path="/var/www/html/docs" type="sendreceive">
  <versioning type="staggered">
    <param key="maxAge" value="31536000"/>   <!-- 1 year in seconds -->
    <param key="cleanoutDays" value="365"/>  <!-- Remove versions older than 365 days -->
    <param key="versionsPath" value=""/>     <!-- Empty = .stversions inside folder -->
  </versioning>
</folder>

In the GUI: Folder → Edit → File Versioning → Staggered File Versioning.

Versioning Parameters

Parameter	Default	Description
maxAge	31536000 (1 year)	Maximum age of versions in seconds. Set to 0 for unlimited.
cleanoutDays	0 (disabled)	Automatically delete all versions older than N days
versionsPath	(empty)	Custom path for .stversions — useful for storing versions on a different disk

Separating Versions to a Different Disk

config.xml — versions on a separate volume

<folder id="media-share" path="/var/www/html/media" type="sendreceive">
  <versioning type="staggered">
    <param key="maxAge" value="2592000"/>           <!-- 30 days -->
    <param key="versionsPath" value="/mnt/versions/media-share"/>
  </versioning>
</folder>

# Ensure the versions directory exists and is writable by the syncthing user
sudo mkdir -p /mnt/versions/media-share
sudo chown syncthing:syncthing /mnt/versions/media-share

Browsing and Recovering Versions

Versions are stored in a mirrored directory structure:

.stversions/
└── path/
    └── to/
        └── file.txt~20260415-090000
        └── file.txt~20260414-120000

recover-deleted-file.sh

# Find all versions of a specific file
find /var/www/html/docs/.stversions -name "myfile.txt~*" | sort

# Restore the most recent version
LATEST=$(find /var/www/html/docs/.stversions -name "myfile.txt~*" | sort | tail -n1)
cp "$LATEST" /var/www/html/docs/myfile.txt

# Or restore a version from a specific date
cp "/var/www/html/docs/.stversions/reports/q1.csv~20260101-000000" \
   /var/www/html/docs/reports/q1.csv

Storage Cost Estimation

check-versions-size.sh

# How much space is .stversions using?
du -sh /var/www/html/docs/.stversions/

# File count
find /var/www/html/docs/.stversions -type f | wc -l

# Oldest version
find /var/www/html/docs/.stversions -type f -printf "%T@ %p\n" | sort -n | head -1

warning

On high-churn folders (logs, database dumps), .stversions can grow very fast. Always monitor its size and set aggressive cleanoutDays or use a separate versionsPath on a large dedicated volume.

Versioning Strategies by Folder Type

Folder	Churn Rate	Recommended Versioning	Retention
/var/www/html/docs — static docs	Low	Staggered	365 days
/home/user/projects — code	Medium	Staggered + git	30 days
/var/log/app — application logs	Very high	None (Restic handles it)	N/A
/home/user/Desktop — user files	Low	Trash can	Manual

Common Mistakes

Mistake	Effect	Fix
Enabling versioning on a log folder	.stversions fills disk in hours	Exclude log files with .stignore
Default versionsPath on a small system disk	Versions compete with system space	Set versionsPath to a dedicated volume
maxAge=0 (unlimited) with no cleanout	Versions accumulate forever	Set cleanoutDays to a reasonable value

What's Next

• Syncthing API and Scripting
• Common Errors and Root Cause