quico-os-setup/zfs-pacman-hook
1
0
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity

refactor(docs): Explain counter suffix (#1)

Browse Source
This commit is contained in:
hygienic-books 2023-12-26 06:09:43 +01:00
parent 525600dde4
commit 3516f56580
1 changed files with 20 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@ -66,14 +66,14 @@ The _trivial_ snapshot chain by default keeps 25 snapshots, the _important_ chai
Snapshots may look like so: Snapshots may look like so:
``` ```
$ zfs list -o name -t all $ zfs list -o name -t all
NAME ┌─── Important because systemd NAME snap_date_format='%F-%H%M' ┌─── Important because systemd
zpool snap_date_format='%F-%H%M' | is on our list of zpool | | is on our list of
zpool/root ▼ | important packages zpool/root ▼ ┌ Counter | important packages
zpool/root/archlinux ┌─────────────┐ ▼▼▼ zpool/root/archlinux ┌─────────────┐ ▼ ▼▼▼
zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:imp_pkgs:systemd:bind:enchant:grep zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:imp_pkgs:systemd:bind:enchant:grep
zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:trv_pkgs:jdk17-temurin zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:trv_pkgs:jdk17-temurin
zpool/root/archlinux@pacman_2023-03-07-0114_op:inst_sev:trv_pkgs:docker-credential-secretser... zpool/root/archlinux@pacman_2023-03-07-0114_1_op:inst_sev:trv_pkgs:docker-credential-secretser...
zpool/root/archlinux@pacman_2023-03-07-0115_op:upgr_sev:trv_pkgs:proton-ge-custom-bin zpool/root/archlinux@pacman_2023-03-07-0115_1_op:upgr_sev:trv_pkgs:proton-ge-custom-bin
▲▲▲▲ ▲▲▲ └────────────────────────────┘ ▲▲▲▲ ▲▲▲ └────────────────────────────┘
| | Max. 30 characters per our | | Max. 30 characters per our
Pacman operation that triggered this snapshot ───┘ | pacman-zfs-snapshot.conf Pacman operation that triggered this snapshot ───┘ | pacman-zfs-snapshot.conf
@ -81,7 +81,9 @@ Pacman operation that triggered this snapshot ───┘ | pacm
Severity based on affected packages, here trivial ───────┘ Severity based on affected packages, here trivial ───────┘
``` ```
Notice how snapshot line 3 ends in `docker-credential-secretser...`. This snapshot was triggered on installation of the Arch User Repository package [docker-credential-secretservice-bin](https://aur.archlinux.org/packages/docker-credential-secretservice-bin) whose package name is 35 characters long. In this example our `pkgs_list_max_length` setting limits maximum name of the packages string to `30` characters. If we can't naturally fit package names into this limit by removing packages from the list we instead cut off part of the package name and add an ellipsis (three dots `...`). The default setting is `pkgs_list_max_length='30'`. In case the user wants three characters or fewer thus making an ellipsis impractical we simply trim the package name to that many characters: Notice how in this case the _counter_ is `1` for all four snapshots. The counter is used as the distinguishing factor for snapshots that are otherwise identical. This avoids naming collisions by incrementing it as needed. In day-to-day operations you will typically see it at `1` as there rarely is a need to avoid collisions unless you purposely limit the timestamp length and/or package list length to the point that successive snapshots may appear identical. See [Avoiding naming collisions](#avoiding-naming-collisions) for more details.
Notice also how snapshot line 3 ends in `docker-credential-secretser...`. This snapshot was triggered on installation of the Arch User Repository package [docker-credential-secretservice-bin](https://aur.archlinux.org/packages/docker-credential-secretservice-bin) whose package name is 35 characters long. In this example our `pkgs_list_max_length` setting limits maximum name of the packages string to `30` characters. If we can't naturally fit package names into this limit by removing packages from the list we instead cut off part of the package name and add an ellipsis (three dots `...`). The default setting is `pkgs_list_max_length='30'`. In case the user wants three characters or fewer thus making an ellipsis impractical we simply trim the package name to that many characters:
``` ```
pkgs_list_max_length='7': dock... pkgs_list_max_length='7': dock...
pkgs_list_max_length='6': doc... pkgs_list_max_length='6': doc...
@ -98,10 +100,10 @@ NAME
zpool zpool
zpool/root zpool/root
zpool/root/archlinux zpool/root/archlinux
zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:imp zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:imp
zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:trv zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:trv
zpool/root/archlinux@pacman_2023-03-07-0114_op:inst_sev:trv zpool/root/archlinux@pacman_2023-03-07-0114_1_op:inst_sev:trv
zpool/root/archlinux@pacman_2023-03-07-0115_op:upgr_sev:trv zpool/root/archlinux@pacman_2023-03-07-0115_1_op:upgr_sev:trv
``` ```
Whatever you set as your `pkgs_list_max_length` is still just a best effort as it is subject to ZFS' internal maximum for dataset name length. This limit is currently 255 characters. For a snapshot the dataset name in front of the `@` character plus everything else starting with the `@` character til the end count against the limit. If you'd like e.g. 200 characters allocated to the package list chances are that you'll see fewer characters than that depending on how long your dataset names are on their own. Whatever you set as your `pkgs_list_max_length` is still just a best effort as it is subject to ZFS' internal maximum for dataset name length. This limit is currently 255 characters. For a snapshot the dataset name in front of the `@` character plus everything else starting with the `@` character til the end count against the limit. If you'd like e.g. 200 characters allocated to the package list chances are that you'll see fewer characters than that depending on how long your dataset names are on their own.