Conflict Resolution

Handling Edit Conflicts

When you edit the same note on multiple devices before syncing, Strayfiles detects the conflict and helps you resolve it.

How Conflicts Happen

Timeline:
1. Note at version 3 on all devices
2. MacBook edits → local version 4
3. iMac edits → local version 4
4. MacBook syncs first → server has version 4
5. iMac tries to sync → version mismatch detected

The iMac expected to update version 3, but found version 4 instead.

Conflict Detection

Strayfiles uses optimistic concurrency:

1. Each note has a version_number
2. When you save, you send: “Update version N to N+1”
3. If server has version > N, conflict detected
4. Both versions preserved for resolution

What’s Stored

When a conflict occurs, Strayfiles saves:

Field	Description
Base content	Common ancestor (version both started from)
Local content	What you tried to save
Remote content	Current version on the server
Base version	Version number of common ancestor
Local version	Your expected version
Remote version	Actual current version
Device IDs	Which devices made each change

Storage location:

• Local backends: Content stored in files at ~/.strayfiles/conflicts/{id}/
• Supabase: Content stored in database for Stray Cloud

Conflict tracking requires the Redb backend (default). Memory and Git backends don’t support conflict tracking.

Resolution Strategies

Keep Local: Use your version, discard the remote changes.

Keep Remote: Use the other device’s version, discard your changes.

Auto-Merge: Attempt automatic 3-way merge using the base as common ancestor.

3-Way Merge

Auto-merge works when changes don’t overlap:

Base:    "Hello world"
Local:   "Hello world!" (added punctuation)
Remote:  "Hello beautiful world" (added adjective)
Merged:  "Hello beautiful world!" (both changes)

Merge fails when changes conflict:

Base:    "Hello world"
Local:   "Hi world"
Remote:  "Hello earth"
Result:  Cannot auto-merge (same section changed differently)

Resolving Conflicts

1. Open the note (conflict indicator shown)
2. Click “Resolve Conflict”
3. See side-by-side comparison:
   • Left: Your version
   • Right: Their version
   • Bottom: Base version
4. Choose resolution:
   • “Keep Mine”
   • “Keep Theirs”
   • “Auto-Merge” (if available)
   • Manual edit (copy parts from each)

Conflict Indicators

Notes with unresolved conflicts show:

• Warning icon in note list
• Banner at top of note
• Sync status shows “Conflict”

Preventing Conflicts

Sync frequently: Smaller, more frequent syncs reduce conflict chances.

Avoid simultaneous edits: If you know you’ll edit on multiple devices, sync first.

Use different notes: For parallel work, consider separate notes that merge later.

Device Authorization

Only devices that are party to the conflict can resolve it. Specifically, the device resolving the conflict must be either the local_device_id or the remote_device_id recorded on the conflict. Attempting to resolve a conflict from a third device will fail with an authorization error.

Device Attribution

Conflict view shows which device made each change:

Your changes (MacBook Pro):
+ Added new section on API

Their changes (iPhone):
+ Fixed typo in introduction

This context helps decide which version to keep.

Conflict History

Resolved conflicts are logged for audit purposes:

• Resolution method recorded (keep local, keep remote, or auto-merge)
• Timestamp of resolution
• Version numbers preserved
• Can see that past conflicts occurred and how they were resolved

Note: When a conflict is resolved, the conflict content files (base, local, and remote .md files) are permanently deleted. Only metadata — versions, resolution method, timestamps, and device IDs — is preserved. You cannot view the actual conflict content from history; you can only see that a conflict occurred and how it was resolved.

Advanced: Manual Resolution

For complex conflicts:

1. Choose “Keep Mine” or “Keep Theirs”
2. Copy the other version’s content you want
3. Manually merge in the editor
4. Save creates new clean version

Folder Sync Conflicts

When using iCloud/Dropbox (not Pro sync):

• Conflicts handled by the sync provider
• Creates “conflicted copy” files
• Strayfiles shows both files
• Manually merge and delete duplicate

Tips

Check for conflicts after offline work: Syncing after being offline may surface conflicts.

Auto-merge is safe: It only succeeds when changes don’t overlap. Overlapping changes require manual resolution.

When in doubt, keep both: Copy content from both versions before resolving.