From 92d64d554073ec40bc8e5ba49ec50d075c9f071f Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Tue, 24 Mar 2026 00:26:35 -0700 Subject: [PATCH] Fix doc inconsistencies between README and ARCHITECTURE. - ARCHITECTURE.md: move mirror/prune to local command table, fix remove description (prune cleans blobs, not checkpoint), fix Phase 2 section to only list remote commands - README.md: add --force to mirror down, fix prune --remote description, build instructions include both binaries Co-Authored-By: Claude Opus 4.6 (1M context) --- ARCHITECTURE.md | 19 ++++++++++--------- README.md | 11 +++++++---- 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 50ab1f7..188da4c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -93,19 +93,22 @@ Properties: All commands operate on a repository directory (default: `~/.sgard`, override with `--repo`). -### Phase 1 — Local +### Local | Command | Description | |---|---| | `sgard init [--repo ]` | Create a new repository | -| `sgard add ...` | Track files; copies them into the blob store and adds manifest entries | -| `sgard remove ...` | Untrack files; removes manifest entries (blobs cleaned up on next checkpoint) | -| `sgard checkpoint [-m ]` | Re-hash all tracked files, store any changed blobs, update manifest | +| `sgard add ...` | Track files, directories (recursed), or symlinks | +| `sgard remove ...` | Untrack files; run `prune` to clean orphaned blobs | +| `sgard checkpoint [-m ]` | Re-hash all tracked files, store changed blobs, update manifest | | `sgard restore [...] [--force]` | Restore files from manifest to their original locations | | `sgard status` | Compare current files against manifest: modified, missing, ok | | `sgard verify` | Check all blobs against manifest hashes (integrity check) | | `sgard list` | List all tracked files | -| `sgard diff []` | Show content diff between current file and stored blob | +| `sgard diff ` | Show content diff between current file and stored blob | +| `sgard prune` | Remove orphaned blobs not referenced by the manifest | +| `sgard mirror up ...` | Sync filesystem → manifest (add new, remove deleted, rehash) | +| `sgard mirror down ... [--force]` | Sync manifest → filesystem (restore + delete untracked) | **Workflow example:** @@ -123,15 +126,13 @@ sgard checkpoint -m "initial" --repo /mnt/usb/dotfiles sgard restore --repo /mnt/usb/dotfiles ``` -### Phase 2 — Remote +### Remote | Command | Description | |---|---| | `sgard push` | Push checkpoint to remote gRPC server | | `sgard pull` | Pull checkpoint from remote gRPC server | -| `sgard prune` | Remove orphaned blobs (local or `--remote`) | -| `sgard mirror up ` | Sync filesystem → manifest (add new, remove deleted) | -| `sgard mirror down ` | Sync manifest → filesystem (restore + delete untracked) | +| `sgard prune` | With `--remote`, prunes orphaned blobs on the server | | `sgardd` | Run the gRPC sync daemon | ## gRPC Protocol diff --git a/README.md b/README.md index 16cf81e..d008ab7 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,14 @@ From source: ``` git clone https://github.com/kisom/sgard && cd sgard -go build -o sgard ./cmd/sgard +go build ./cmd/sgard ./cmd/sgardd ``` Or install into `$GOBIN`: ``` go install github.com/kisom/sgard/cmd/sgard@latest +go install github.com/kisom/sgard/cmd/sgardd@latest ``` NixOS (flake): @@ -84,7 +85,7 @@ sgard restore --repo /mnt/usb/dotfiles | `verify` | Check blob store integrity against manifest hashes | | `prune` | Remove orphaned blobs not referenced by the manifest | | `mirror up ` | Sync filesystem → manifest (add new, remove deleted) | -| `mirror down ` | Sync manifest → filesystem (restore + delete untracked) | +| `mirror down [-f]` | Sync manifest → filesystem (restore + delete untracked) | | `version` | Print the version | ### Remote sync @@ -93,12 +94,14 @@ sgard restore --repo /mnt/usb/dotfiles |---|---| | `push` | Push checkpoint to remote gRPC server | | `pull` | Pull checkpoint from remote gRPC server | -| `prune --remote` | Remove orphaned blobs on the remote server | -| `sgardd` | Run the gRPC sync daemon (separate binary) | +| `prune` | With `--remote`, prunes orphaned blobs on the server | Remote commands require `--remote host:port` (or `SGARD_REMOTE` env, or a `/remote` config file) and authenticate via SSH keys. +The server daemon `sgardd` is a separate binary (included in releases and +Nix builds). + ## Remote sync Start the daemon on your server: