Correct doc and help sentences that are false about the code (closes #233)
check / check (push) Waiting to run

A blob is written in full to a temporary file in $TMPDIR and uploaded
once finished, not streamed to storage; the README and
config.example.yml now say a backup needs about blob_size_limit of free
space there. Also corrected: the snapshot ID format, what restore reads
and how incomplete snapshots are removed in docs/DATAMODEL.md, what
source_path is for, the index_path default, the config search order in
the snapshot create help, what snapshot remove cleans up in the prune
help, how the release installs Go, and the script/release and
script/fmt-check comments.

The source_path claim is also corrected in models.go, scanner.go and
001.sql, which the issue did not list.

Model: opus-5-5
This commit is contained in:
2026-10-07 12:35:07 +00:00
parent 8b22ae8d42
commit adfa7ac6ff
13 changed files with 59 additions and 41 deletions
+3 -3
View File
@@ -54,7 +54,7 @@ The database tracks five primary entities and their relationships:
#### File (`database.File`)
Represents a file, directory, or symlink in the backup system. Stores metadata needed for restoration:
- Path, source_path (for restore path stripping), mtime
- Path, source_path (the configured snapshot path the scan found it under), mtime
- Size, mode, ownership (uid, gid)
- Symlink target (if applicable)
@@ -82,9 +82,9 @@ The final storage unit uploaded to S3. Contains many compressed and encrypted ch
Blob creation process:
1. Chunks are accumulated (up to MaxBlobSize, typically 10GB)
2. As each chunk is added, its uncompressed bytes are fed to a running SHA-256
3. Concurrently, the same bytes are compressed with zstd, then encrypted with age (recipients configured in config), and streamed to storage
3. Concurrently, the same bytes are compressed with zstd, then encrypted with age (recipients configured in config), and written to a temporary file in `$TMPDIR` (`/tmp` when unset)
4. On finalize, the blob's name is the double SHA-256 of the uncompressed contents — `hex(SHA256(SHA256(...)))` — not a hash of the compressed, encrypted bytes
5. Uploaded to `blobs/{hash[0:2]}/{hash[2:4]}/{hash}`
5. The finished file is uploaded to `blobs/{hash[0:2]}/{hash[2:4]}/{hash}` and then deleted, so a backup needs about `blob_size_limit` of free space in `$TMPDIR`
#### BlobChunk (`database.BlobChunk`)
Maps chunks to their position within blobs: