| name | msync-user |
| description | Operate the `msync` snapshot-based bidirectional sync
tool — sync two paths between machines using a
three-way merge. Trigger when the user wants to keep a
notes / docs / config directory in sync across two
accounts, recover from a sync conflict, or learn the
three-way-merge model.
|
msync-user skill
1. Design principles
- Educational. A small ~184-line dispatcher that
composes
data table operations and rsync. Reading
end-to-end teaches the snapshot-based three-way
merge.
- Functional. Pure transformations over snapshot
files; no in-place state changes during a
msync sync.
- Decentralized. Two-way sync between peers; no
central server.
- Simple.
msync calls only account and
data. The data dep is the documented exception
to the strict-foundation rule; FEAT-046 will inline
it.
2. The model
A snapshot is a TSV table:
File Mtime Size Hash
notes/intro.md 1714723200 845 abc123
notes/index.md 1714723300 120 def456
...
msync sync a b runs three snapshots — base, A's
current, B's current — and computes a three-way merge
on the union of file paths:
- File only in A ⇒ copy to B
- File only in B ⇒ copy to A
- File in both, identical ⇒ skip
- File in both, different ⇒ conflict
Conflict policy: today, mtime + size win (newer +
larger preferred). Per FEAT-064, richer policies
(interactive, batch, --theirs / --ours flags) will land
later.
3. Workflow recipes
-
Take a snapshot of a tree.
msync snapshot ~/notes
-
Sync two paths.
msync sync ~/notes peer:~/notes
-
Sync via an intermediate account.
msync sync ~/notes peer:~/notes alice@example.com
-
Schedule via event.
event create notes-sync
event edit notes-sync
# script body: msync sync ~/notes peer:~/notes
echo '*/15 * * * *' | event insert notes-sync schedule
4. Guardrails
- Conflict policy is mtime + size today. If both
sides have a newer-but-smaller file, the larger
wins. This may be wrong for your workload — wait
for FEAT-064 if you need stricter policy.
msync sync is two-way. Don't run it
concurrently from both ends; you'll race the
snapshot computation.- Multi-endpoint (N≥2) isn't implemented
(FEAT-065 pending). Stick to two-way until that
lands.
- Snapshots include mtime, not content hash. A
touch-only edit (no content change) still triggers
a sync. Filter via
--exclude patterns if that
matters.
- Bsync (the Python predecessor) is being phased
out per FEAT-063. Migrate to msync; bsync stays
for backward compat in v0 but won't get new
features.
5. Where to read more
man msyncman snapshot for the per-service-backup siblingman data — table operations msync uses internally- This package's
CLAUDE.md
