sc/sgard
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix doc inconsistencies between README and ARCHITECTURE.

Browse Source 
- 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) <noreply@anthropic.com>
This commit is contained in:
Kyle Isom
2026-03-24 00:26:35 -07:00
parent 5f1bc4e14c
commit 92d64d5540
2 changed files with 17 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
ARCHITECTURE.md
View File

@@ -93,19 +93,22 @@ Properties:
All commands operate on a repository directory (default: `~/.sgard`, override with `--repo`). All commands operate on a repository directory (default: `~/.sgard`, override with `--repo`).
### Phase 1 — Local ### Local
| Command | Description | | Command | Description |
|---|---| |---|---|
| `sgard init [--repo <path>]` | Create a new repository | | `sgard init [--repo <path>]` | Create a new repository |
| `sgard add <path>...` | Track files; copies them into the blob store and adds manifest entries | | `sgard add <path>...` | Track files, directories (recursed), or symlinks |
| `sgard remove <path>...` | Untrack files; removes manifest entries (blobs cleaned up on next checkpoint) | | `sgard remove <path>...` | Untrack files; run `prune` to clean orphaned blobs |
| `sgard checkpoint [-m <message>]` | Re-hash all tracked files, store any changed blobs, update manifest | | `sgard checkpoint [-m <message>]` | Re-hash all tracked files, store changed blobs, update manifest |
| `sgard restore [<path>...] [--force]` | Restore files from manifest to their original locations | | `sgard restore [<path>...] [--force]` | Restore files from manifest to their original locations |
| `sgard status` | Compare current files against manifest: modified, missing, ok | | `sgard status` | Compare current files against manifest: modified, missing, ok |
| `sgard verify` | Check all blobs against manifest hashes (integrity check) | | `sgard verify` | Check all blobs against manifest hashes (integrity check) |
| `sgard list` | List all tracked files | | `sgard list` | List all tracked files |
| `sgard diff [<path>]` | Show content diff between current file and stored blob | | `sgard diff <path>` | Show content diff between current file and stored blob |
| `sgard prune` | Remove orphaned blobs not referenced by the manifest |
| `sgard mirror up <path>...` | Sync filesystem → manifest (add new, remove deleted, rehash) |
| `sgard mirror down <path>... [--force]` | Sync manifest → filesystem (restore + delete untracked) |
**Workflow example:** **Workflow example:**
@@ -123,15 +126,13 @@ sgard checkpoint -m "initial" --repo /mnt/usb/dotfiles
sgard restore --repo /mnt/usb/dotfiles sgard restore --repo /mnt/usb/dotfiles
``` ```
### Phase 2 — Remote ### Remote
| Command | Description | | Command | Description |
|---|---| |---|---|
| `sgard push` | Push checkpoint to remote gRPC server | | `sgard push` | Push checkpoint to remote gRPC server |
| `sgard pull` | Pull checkpoint from remote gRPC server | | `sgard pull` | Pull checkpoint from remote gRPC server |
| `sgard prune` | Remove orphaned blobs (local or `--remote`) | | `sgard prune` | With `--remote`, prunes orphaned blobs on the server |
| `sgard mirror up <path>` | Sync filesystem → manifest (add new, remove deleted) |
| `sgard mirror down <path>` | Sync manifest → filesystem (restore + delete untracked) |
| `sgardd` | Run the gRPC sync daemon | | `sgardd` | Run the gRPC sync daemon |
## gRPC Protocol ## gRPC Protocol

11
README.md
View File

@@ -19,13 +19,14 @@ From source:
``` ```
git clone https://github.com/kisom/sgard && cd sgard 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`: Or install into `$GOBIN`:
``` ```
go install github.com/kisom/sgard/cmd/sgard@latest go install github.com/kisom/sgard/cmd/sgard@latest
go install github.com/kisom/sgard/cmd/sgardd@latest
``` ```
NixOS (flake): NixOS (flake):
@@ -84,7 +85,7 @@ sgard restore --repo /mnt/usb/dotfiles
| `verify` | Check blob store integrity against manifest hashes | | `verify` | Check blob store integrity against manifest hashes |
| `prune` | Remove orphaned blobs not referenced by the manifest | | `prune` | Remove orphaned blobs not referenced by the manifest |
| `mirror up <path>` | Sync filesystem → manifest (add new, remove deleted) | | `mirror up <path>` | Sync filesystem → manifest (add new, remove deleted) |
| `mirror down <path>` | Sync manifest → filesystem (restore + delete untracked) | | `mirror down <path> [-f]` | Sync manifest → filesystem (restore + delete untracked) |
| `version` | Print the version | | `version` | Print the version |
### Remote sync ### Remote sync
@@ -93,12 +94,14 @@ sgard restore --repo /mnt/usb/dotfiles
|---|---| |---|---|
| `push` | Push checkpoint to remote gRPC server | | `push` | Push checkpoint to remote gRPC server |
| `pull` | Pull checkpoint from remote gRPC server | | `pull` | Pull checkpoint from remote gRPC server |
| `prune --remote` | Remove orphaned blobs on the remote server | | `prune` | With `--remote`, prunes orphaned blobs on the server |
| `sgardd` | Run the gRPC sync daemon (separate binary) |
Remote commands require `--remote host:port` (or `SGARD_REMOTE` env, or a Remote commands require `--remote host:port` (or `SGARD_REMOTE` env, or a
`<repo>/remote` config file) and authenticate via SSH keys. `<repo>/remote` config file) and authenticate via SSH keys.
The server daemon `sgardd` is a separate binary (included in releases and
Nix builds).
## Remote sync ## Remote sync
Start the daemon on your server: Start the daemon on your server: