# FolderSync (CLI prototype)

FolderSync is a working prototype of a versioned one-way folder sync
tool: it copies new files, updates changed files, and (optionally)
deletes files that no longer exist in the source, but before it ever
overwrites or removes an EXISTING destination file it first archives
that file's current content into a version history directory. The
`versions` command lists every historical snapshot stored for a given
file, and `restore` brings any of them back - so a sync that turns out
to have been a mistake ("oh no, that sync wasn't supposed to happen")
can be undone, not just diagnosed after the fact. This differs from
the sibling SyncGuard tool in exactly this respect: SyncGuard performs
a plain one-way mirror where an overwritten or deleted destination
file is simply gone, with no undo. FolderSync is the same core
diff/mirror idea aimed at teams and small-business IT admins who need
a safety net under it. Two-way sync with conflict resolution, and
cloud/NAS sync targets, are on the roadmap rather than implemented
here - see ../plan.md for the full product plan.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o foldersync .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o foldersync.exe .
    GOOS=darwin  GOARCH=arm64 go build -o foldersync .

## Usage

  foldersync sync <src> <dst> --versions <versionsdir> [--delete] [--apply]

    One-way sync from <src> to <dst>.
      - Files present in <src> but not <dst> are copied. New files have
        no prior destination content, so nothing is versioned for them.
      - Files present in both but with different content (detected by
        a size + SHA-256 checksum comparison) are updated in <dst>;
        the file's PRE-update content is versioned FIRST, before the
        overwrite happens.
      - With --delete, files present in <dst> but not <src> are
        removed; the file's last content is versioned first, so the
        delete is recoverable.
      - Without --apply, sync only prints a dry-run plan (which of the
        planned copies/updates/deletes exist, and which of those would
        trigger a version snapshot) and touches neither <dst> nor
        <versionsdir>. Pass --apply to actually perform the sync.

  foldersync versions <dst-relative-path> --versions <versionsdir> [--json]

    Lists every historical version FolderSync has archived for the
    given destination-relative file path, newest first, each with its
    timestamp and size. Pass --json for machine-readable output.

  foldersync restore <dst-relative-path> <dst-root> --versions <versionsdir> [--at <timestamp-or-latest>] [--apply]

    Restores a specific historical version of a file back into
    <dst-root>/<dst-relative-path>, overwriting whatever is currently
    there, or creating it if the file was deleted by a prior sync.
      - --at latest (the default if omitted) restores the most
        recently archived version.
      - --at <timestamp> restores that exact version, using any
        timestamp string as printed by `versions`.
      - Without --apply, restore only reports what it would do and
        touches nothing. Pass --apply to actually perform the restore.

    Recursive safety property: restoring is itself undo-able. Whatever
    currently sits at <dst-root>/<dst-relative-path> (if anything) is
    versioned BEFORE it is overwritten by the restored content, using
    the exact same versioning mechanism as a normal sync overwrite. So
    restoring an older version never silently destroys newer content -
    it just becomes another entry in the file's own version history,
    itself restorable in turn.

Version storage layout: each archived snapshot of destination-relative
path REL is stored at <versionsdir>/REL/<timestamp>, so REL becomes a
directory containing one file per historical snapshot, named by the
UTC timestamp at which it was archived (sortable lexicographically,
newest last -> the `versions` command reverses this to print newest
first).

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds -
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.