Document snapshot files and fix the six findings of the last review
check / check (push) Successful in 17m0s

Rebased onto next, which added `snapshot files` and refuses an exclude
pattern that does not compile. The README, docs/REPOSTRUCTURE.md, the
example config and the help text now name `snapshot files` wherever
they list the commands that need the private key, read or list the
destination, run without the lock or write a decrypted database. The
config load conditions name exclude patterns, and docs/ARCHITECTURE.md
lists internal/exclude.

The six findings of
#399 (comment) use the
wording that review gives.

Model: opus-5-5
This commit is contained in:
clawbot committed 2026-11-16 23:22:40 +00:00
1 parent 3e53dd4014
commit 7b0f0e1362
7 files changed
+145 -48

No files matched your search

+3 -1
View File
@@ -16,7 +16,7 @@ Two other documents cover the stored data:
## Terms
- **Snapshot**: one backup of the paths listed under one name in the config.
- **Snapshot ID**: the name of a snapshot, in the form
- **Snapshot ID**: the identifier of one snapshot, in the form
`<hostname>_<snapshot-name>_<timestamp>`.
- **Chunk**: a piece of a file's content. A chunk is named by the SHA-256 hash
of its content.
@@ -69,6 +69,8 @@ source files
S3, a local directory and [rclone](https://rclone.org/).
- `internal/s3`: the S3 client that the S3 `Storer` uses.
- `internal/config`: loads and checks the config file.
- `internal/exclude`: compiles exclude patterns, for the config check and for
the `Scanner`.
- `internal/ui`: formats the status lines, warnings and errors a user sees.
- `internal/log`: the logger. It writes to stderr.
- `internal/pidlock`: the lock that `RunWithApp` takes for a command that
+1 -1
View File
@@ -17,7 +17,7 @@ copy that was uploaded with the snapshot.
## Terms
- **Snapshot**: one backup of the paths listed under one name in the config.
- **Snapshot ID**: the name of a snapshot, in the form
- **Snapshot ID**: the identifier of one snapshot, in the form
`<hostname>_<snapshot-name>_<timestamp>`.
- **Chunk**: a piece of a file's content, named by the SHA-256 hash of that
content.
+21 -10
View File
@@ -10,7 +10,7 @@ is a storage service set up in rclone. The layout is the same on all three.
## Terms
- **Snapshot**: one backup of the paths listed under one name in the config.
- **Snapshot ID**: the name of a snapshot, in the form
- **Snapshot ID**: the identifier of one snapshot, in the form
`<hostname>_<snapshot-name>_<timestamp>`.
- **Remote key**: a hash of the snapshot ID. It names the snapshot's directory
under `metadata/`. See [Remote keys](#remote-keys).
@@ -61,8 +61,11 @@ not exist, commands treat the destination as not present:
- `prune`
- `snapshot purge`
- `remote nuke`
- `snapshot verify` and `snapshot restore`, when given a remote key, or a
snapshot ID that is not in the local index
- These commands fail when given a remote key, or a snapshot ID that is not in
the local index:
- `snapshot files`
- `snapshot verify`
- `snapshot restore`
- `snapshot list` shows the local index alone.
- `snapshot remove` deletes nothing at the destination.
@@ -309,6 +312,7 @@ These commands write unencrypted data to the temporary directory:
is no limit on their total size.
- `snapshot restore` writes the decrypted database to
`vaultik-restore-*/snapshot.db`.
- `snapshot files` writes the decrypted database to the same place.
- `snapshot verify --deep` writes the decrypted database to
`vaultik-verify-*/snapshot.db`.
- `snapshot create` writes a copy of the local index to
@@ -322,11 +326,12 @@ Trust the temporary directory as much as the directory you restore into.
### Commands need different permissions
`snapshot create` without `--prune` writes objects. On S3 it needs no other
permission. Other commands need more:
`snapshot create` without `--prune` writes objects. With an `s3://` destination
it needs no other permission. Other commands need more:
- These commands list and read:
- `snapshot list`
- `snapshot files`
- `snapshot verify`
- `snapshot restore`
- `remote info`
@@ -336,12 +341,18 @@ permission. Other commands need more:
- `remote nuke`
- `prune` lists, reads and deletes.
An rclone remote that can move objects also needs permission to read and delete.
An upload there looks up the object it replaces and deletes it. It stops when
the look-up is refused.
On an rclone remote, a backup can also need permission to read and delete. Which
ones depends on the storage service. An upload to a remote that can move objects
looks up the object it replaces and deletes it. It stops when the look-up is
refused.
These commands list only when they are given a remote key, or a snapshot ID that
is not in the local index:
- `snapshot files`
- `snapshot verify`
- `snapshot restore`
`snapshot verify` and `snapshot restore` list only when they are given a remote
key, or a snapshot ID that is not in the local index.
`snapshot remove --local-only` does not reach the destination.
`snapshot remove --dry-run` deletes nothing.