Reword README.md sentences that read badly on a second pass
check / check (push) Waiting to run

Split sentences that carried two or three ideas, turned the cases in
which a backup does not find a mount point into a list, and named the
figures that remote info reports as unknown.

Model: fable-5-1
This commit is contained in:
2026-11-06 18:32:24 +00:00
parent 64c31f890b
commit b6f8e860e1
+35 -23
View File
@@ -92,8 +92,8 @@ vaultik snapshot list
The default config is written for macOS. It backs up your home directory and
`/Applications`, with a list of excludes. A configured path that does not exist
stops the backup, so on another system run `vaultik config edit` first and
change the `snapshots` section.
stops the backup. On another system, run `vaultik config edit` first and change
the `snapshots` section.
On macOS, grant your terminal app Full Disk Access before the first backup. The
setting is under System Settings, Privacy & Security, Full Disk Access. Without
@@ -208,9 +208,10 @@ Every other command except `database delete` also needs these:
directory, when they do not exist.
- For an `rclone://` destination, an rclone config file that defines the remote.
Each command below lists what it needs beyond this. No command needs root, but a
backup can read only what its user can read, and a restore sets file owners only
as root.
Each command below lists what it needs beyond this.
No command needs root. A backup can read only what its user can read. A restore
sets file owners only when it runs as root.
### Global flags
@@ -342,7 +343,8 @@ change the exit status.
After a successful backup, `--prune` does two things:
- It removes the older snapshots of each name it just backed up. It keeps only
the newest one, or with `--keep-newer-than` every snapshot newer than that.
the newest one. With `--keep-newer-than`, it keeps every snapshot newer than
that duration instead.
- It then deletes at the destination what [`prune`](#prune) deletes.
`--prune` also needs permission to list, read and delete at the destination.
@@ -364,8 +366,14 @@ and exits non-zero. It does so on every backup until the cause is gone.
A mount point here is a directory at or below a configured path that is on a
different filesystem from its parent. It counts only when the backup finds an
entry in it that is not excluded. A backup does not find it when the volume is
not mounted, or when the directory is now excluded or no longer configured.
entry in it that is not excluded.
A backup does not find a mount point in these cases:
- The volume is not mounted.
- The directory holds no entry that the backup reads.
- The directory is now excluded.
- The directory is no longer under a configured path.
If the cause is intended, such as a retired volume, remove the older snapshots
yourself with `snapshot purge`. Take a path that is empty on purpose out of the
@@ -374,8 +382,8 @@ config.
### `snapshot list`
Lists the snapshots in the local index and the snapshots at the destination, as
one table. Before it, the command prints the snapshot names and paths in the
config.
one table. Before the table, the command prints the snapshot names and paths in
the config.
It needs permission to list and read at the destination. It needs no private
key.
@@ -484,9 +492,9 @@ Flags:
The command acts only on snapshots in the local index. `--keep-latest` keeps the
newest snapshot of each name, not the newest overall.
A removed snapshot leaves the local index, and its directory under `metadata/`
at the destination is deleted. Its blobs stay. Run `vaultik prune` afterwards to
delete the blobs that no snapshot uses any more.
The command removes each such snapshot from the local index. It also deletes the
snapshot's directory under `metadata/` at the destination. Its blobs stay. Run
`vaultik prune` afterwards to delete the blobs that no snapshot uses any more.
The command first drops local records of snapshots that are no longer at the
destination. It fails and removes nothing when the destination cannot be listed
@@ -590,8 +598,8 @@ It works in three steps:
- It drops each snapshot from the local index whose directory is gone from the
destination.
- It removes unfinished snapshots from the local index. It also removes the file,
chunk and blob records that no snapshot uses.
- It removes unfinished snapshots from the local index. It also removes the
file, chunk and blob records that no snapshot uses.
- It reads every manifest at the destination. It then deletes each blob that no
manifest lists and that is older than `prune_grace_period`.
@@ -653,8 +661,8 @@ Reports what the destination holds:
It needs permission to list and read at the destination. It needs no private
key.
When a manifest cannot be read, the last figures are reported as unknown. That
snapshot's own blob count and size are unknown too.
When a manifest cannot be read, the figures for blobs that no manifest lists are
reported as unknown. That snapshot's own blob count and size are unknown too.
The command skips a name under `metadata/` that is not a remote key, with a
warning. It does not count a file under `blobs/` whose name is not a blob hash.
@@ -1008,8 +1016,8 @@ different destination:
- `prune`
- `remote nuke`
The destination is `storage_url`, or else `s3.endpoint`, `s3.bucket` and
`s3.prefix`.
The destination that is compared is `storage_url`. When `storage_url` is not
set, it is `s3.endpoint`, `s3.bucket` and `s3.prefix`.
There are two ways out:
@@ -1181,10 +1189,14 @@ destination, what it protects and the risks it accepts.
## Development
[ARCHITECTURE.md](ARCHITECTURE.md) describes how the code is organised.
[docs/DATAMODEL.md](docs/DATAMODEL.md) describes the local index.
[`AGENTS.md`](AGENTS.md) holds the rules for AI agents.
[`REPO_POLICIES.md`](REPO_POLICIES.md) holds the repository policies.
These documents are for developers:
- [ARCHITECTURE.md](ARCHITECTURE.md) describes how the code is organised.
- [docs/DATAMODEL.md](docs/DATAMODEL.md) describes the local index.
- [docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md) describes the layout of the
destination.
- [`AGENTS.md`](AGENTS.md) holds the rules for AI agents.
- [`REPO_POLICIES.md`](REPO_POLICIES.md) holds the repository policies.
### Requirements