file-sync#

sync.py is a bidirectional file synchronization tool. It keeps two directories in sync (e.g. PC ↔ USB), detects conflicts using version history, and handles deletions safely via .trash/.

Usage#

bash

python sync.py <local_folder> <remote_folder> <device_name>

Arguments:

• local_folder — First directory to sync
• remote_folder — Second directory to sync
• device_name — Label for this device (used in conflict file names, e.g. "PC1", "USB")

Sync direction: The tool is symmetric — either folder can be local or remote.

Sync Rules#

SituationBehaviorNew file on one sideCopy to the other sideSingle-side modificationCopy updated file to the other sideConcurrent modification (conflict)Both copies → .conflict/, no overwriteFile deleted on one side, kept on otherConflict (both kept in .conflict/)File deleted on both sidesRemove from both, nothing to trashOne side deletes, other side unchangedDelete propagates to the other side via .trash/

Special Directories (auto-ignored)#

Files and folders matching these names are excluded from sync: .conflict, .trash, .sync_logs

State & History#

State is stored in .sync_state.json in each folder. Each file maintains a history list of MD5 hashes (up to 10 entries). Conflict detection uses history to find a common ancestor:

• No common ancestor → conflict
• One side unchanged (matches ancestor) → auto-merge
• Both sides changed from ancestor → conflict

Conflict Resolution#

When a conflict is detected, both versions are copied into local_folder/.conflict/ with names like:

text

filename_LOCAL_<device>_<timestamp>
filename_REMOTE_<device>_<timestamp>

The original files are left untouched. Manually review and merge, then delete from .conflict/.

Deletion Safety#

Deleted files go to .trash/<relpath>.<timestamp> rather than being permanently removed.

Logging#

Logs are written to local_folder/.sync_logs/sync_<timestamp>.log, including timestamps, action types (INFO/CONFLICT/TRASH/ERROR), and a summary count.

Workflow Example#

bash

# Sync PC1 with USB drive (USB mounted as E:)
python sync.py C:\Users\PC1 E:\ PC1

# Sync back after working on USB
python sync.py E:\ C:\Users\PC1 USB

Bundled Resources#

• scripts/sync.py — The sync script (copy to your project or call directly)
• references/behaviors.md — Detailed behavior notes, edge cases, and design rationale