From 3c8a68153748da9db05b2d4b679bb370d0a18ffd Mon Sep 17 00:00:00 2001 From: John Eckersberg Date: Fri, 27 Jun 2025 16:35:10 -0400 Subject: [PATCH 1/2] xtask: post-process manpages to fix broken apostrophes Signed-off-by: John Eckersberg --- xtask/src/xtask.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/xtask/src/xtask.rs b/xtask/src/xtask.rs index d7c0d457c..622b98411 100644 --- a/xtask/src/xtask.rs +++ b/xtask/src/xtask.rs @@ -104,6 +104,19 @@ fn manpages(sh: &Shell) -> Result<()> { "cargo run --features=docgen -- man --directory target/man" ) .run()?; + + // Post-process hack to unconditionally define the roff string for + // apostrophe, See: + // https://github.com/bootc-dev/bootc/pull/1385#discussion_r2172661872 + for page in std::fs::read_dir(sh.current_dir().join("target/man"))? { + let page = page?; + let path = page.path(); + let groffsub = r"1i .ds Aq \\(aq"; + let dropif = r"/\.g \.ds Aq/d"; + let dropelse = r"/.el .ds Aq '/d"; + cmd!(sh, "sed -i -e {groffsub} -e {dropif} -e {dropelse} {path}").run()?; + } + // We also have some man pages for the systemd units which are canonically // maintained as markdown; convert them to man pages. let extradir = sh.current_dir().join("docs/src/man-md"); From 1b3f1411c31181c08ba96f88e2ee9d704a5d9c7d Mon Sep 17 00:00:00 2001 From: John Eckersberg Date: Thu, 26 Jun 2025 13:42:14 -0400 Subject: [PATCH 2/2] docs: Update generated Signed-off-by: John Eckersberg --- docs/src/host-v1.schema.json | 19 +++++++- docs/src/man/bootc-container-lint.md | 15 +++++-- docs/src/man/bootc-container.md | 2 +- docs/src/man/bootc-edit.md | 6 +-- .../man/bootc-install-ensure-completion.md | 4 +- docs/src/man/bootc-install-finalize.md | 2 +- .../man/bootc-install-print-configuration.md | 4 +- docs/src/man/bootc-install-to-disk.md | 32 ++++++------- .../src/man/bootc-install-to-existing-root.md | 45 +++++++++++-------- docs/src/man/bootc-install-to-filesystem.md | 33 +++++++------- docs/src/man/bootc-install.md | 4 +- docs/src/man/bootc-rollback.md | 23 +++++++--- docs/src/man/bootc-status.md | 4 +- docs/src/man/bootc-switch.md | 6 +-- docs/src/man/bootc-upgrade.md | 6 +-- docs/src/man/bootc-usr-overlay.md | 4 +- docs/src/man/bootc.md | 4 +- 17 files changed, 129 insertions(+), 84 deletions(-) diff --git a/docs/src/host-v1.schema.json b/docs/src/host-v1.schema.json index 85ec800ca..1dd4dd069 100644 --- a/docs/src/host-v1.schema.json +++ b/docs/src/host-v1.schema.json @@ -119,7 +119,8 @@ "type": "object", "required": [ "checksum", - "deploySerial" + "deploySerial", + "stateroot" ], "properties": { "checksum": { @@ -131,6 +132,10 @@ "type": "integer", "format": "uint32", "minimum": 0.0 + }, + "stateroot": { + "description": "The name of the storage for /etc and /var content", + "type": "string" } } }, @@ -194,6 +199,13 @@ } ] }, + "otherDeployments": { + "description": "Other deployments (i.e. pinned)", + "type": "array", + "items": { + "$ref": "#/definitions/BootEntry" + } + }, "rollback": { "description": "The previously booted image", "anyOf": [ @@ -311,10 +323,15 @@ "description": "The status of the booted image", "type": "object", "required": [ + "architecture", "image", "imageDigest" ], "properties": { + "architecture": { + "description": "The hardware architecture of this image", + "type": "string" + }, "image": { "description": "The currently booted image", "allOf": [ diff --git a/docs/src/man/bootc-container-lint.md b/docs/src/man/bootc-container-lint.md index 178ab2aca..ca28bd783 100644 --- a/docs/src/man/bootc-container-lint.md +++ b/docs/src/man/bootc-container-lint.md @@ -6,7 +6,8 @@ checks as part of a container build # SYNOPSIS **bootc container lint** \[**\--rootfs**\] \[**\--fatal-warnings**\] -\[**\--list**\] \[**\--skip**\] \[**-h**\|**\--help**\] +\[**\--list**\] \[**\--skip**\] \[**\--no-truncate**\] +\[**-h**\|**\--help**\] # DESCRIPTION @@ -29,7 +30,7 @@ part of a build process; it will error if any problems are detected. **\--list** : Instead of executing the lints, just print all available lints. At - the current time, this will output in YAML format because its + the current time, this will output in YAML format because it\'s reasonably human friendly. However, there is no commitment to maintaining this exact format; do not parse it via code or scripts @@ -40,10 +41,16 @@ part of a build process; it will error if any problems are detected. Example: \--skip nonempty-boot \--skip baseimage-root +**\--no-truncate** + +: Don\'t truncate the output. By default, only a limited number of + entries are shown for each lint, followed by a count of remaining + entries + **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-container.md b/docs/src/man/bootc-container.md index ab9283f61..e77448bf8 100644 --- a/docs/src/man/bootc-container.md +++ b/docs/src/man/bootc-container.md @@ -30,4 +30,4 @@ bootc-container-help(8) # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-edit.md b/docs/src/man/bootc-edit.md index 7416d2e88..f50f6ad6e 100644 --- a/docs/src/man/bootc-edit.md +++ b/docs/src/man/bootc-edit.md @@ -28,12 +28,12 @@ Only changes to the \`spec\` section are honored. **\--quiet** -: Dont display progress +: Don\'t display progress **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-install-ensure-completion.md b/docs/src/man/bootc-install-ensure-completion.md index f36b1c0e1..2ec1cbf40 100644 --- a/docs/src/man/bootc-install-ensure-completion.md +++ b/docs/src/man/bootc-install-ensure-completion.md @@ -23,8 +23,8 @@ your code is using \`bootc install to-filesystem\` from the start. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-install-finalize.md b/docs/src/man/bootc-install-finalize.md index cdbdb8330..2124733cc 100644 --- a/docs/src/man/bootc-install-finalize.md +++ b/docs/src/man/bootc-install-finalize.md @@ -24,4 +24,4 @@ to-filesystem\` # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-install-print-configuration.md b/docs/src/man/bootc-install-print-configuration.md index fbea4d0be..f39ed969e 100644 --- a/docs/src/man/bootc-install-print-configuration.md +++ b/docs/src/man/bootc-install-print-configuration.md @@ -23,8 +23,8 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-install-to-disk.md b/docs/src/man/bootc-install-to-disk.md index d46a8d668..2e7280b29 100644 --- a/docs/src/man/bootc-install-to-disk.md +++ b/docs/src/man/bootc-install-to-disk.md @@ -7,9 +7,8 @@ bootc-install-to-disk - Install to the target block device **bootc install to-disk** \[**\--wipe**\] \[**\--block-setup**\] \[**\--filesystem**\] \[**\--root-size**\] \[**\--source-imgref**\] \[**\--target-transport**\] \[**\--target-imgref**\] -\[**\--enforce-container-sigpolicy**\] -\[**\--skip-fetch-check**\] \[**\--run-fetch-check**\] -\[**\--disable-selinux**\] \[**\--karg**\] +\[**\--enforce-container-sigpolicy**\] \[**\--run-fetch-check**\] +\[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] \[**\--bound-images**\] \[**\--stateroot**\] \[**\--via-loopback**\] \[**-h**\|**\--help**\] \<*DEVICE*\> @@ -63,8 +62,8 @@ more complex such as RAID, LVM, LUKS etc. By default, bootc install and install-to-filesystem assumes that it runs in a podman container, and it takes the container image to - install from the podmans container registry. If \--source-imgref is - given, bootc uses it as the installation source, instead of the + install from the podman\'s container registry. If \--source-imgref + is given, bootc uses it as the installation source, instead of the behaviour explained in the previous paragraph. See skopeo(1) for accepted formats. @@ -84,16 +83,17 @@ more complex such as RAID, LVM, LUKS etc. Enabling this option enforces that \`/etc/containers/policy.json\` includes a default policy which requires signatures -**\--skip-fetch-check (deprecated, see --run-fetch-check)** +**\--run-fetch-check** -: This is now the default and has no effect. +: Verify the image can be fetched from the bootc image. Updates may + fail when the installation host is authenticated with the registry + but the pull secret is not in the bootc image -**\--run-fetch-check ** +**\--skip-fetch-check** -: Verify the target image can be pulled using the bootc image. - - This will ensure the bootc system can be upgraded, - i.e. the registry credentials are available on the bootc image. +: Verify the image can be fetched from the bootc image. Updates may + fail when the installation host is authenticated with the registry + but the pull secret is not in the bootc image **\--disable-selinux** @@ -135,11 +135,11 @@ more complex such as RAID, LVM, LUKS etc. \ *Possible values:* - - stored: Bound images must exist in the sources root container + - stored: Bound images must exist in the source\'s root container storage (default) - pull: Bound images will be pulled and stored directly in the - targets bootc container storage + target\'s bootc container storage **\--stateroot**=*STATEROOT* @@ -151,7 +151,7 @@ more complex such as RAID, LVM, LUKS etc. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') \<*DEVICE*\> @@ -160,4 +160,4 @@ more complex such as RAID, LVM, LUKS etc. # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-install-to-existing-root.md b/docs/src/man/bootc-install-to-existing-root.md index 1c21a5358..13f0ca2b4 100644 --- a/docs/src/man/bootc-install-to-existing-root.md +++ b/docs/src/man/bootc-install-to-existing-root.md @@ -7,11 +7,12 @@ bootc-install-to-existing-root - Install to the host root filesystem **bootc install to-existing-root** \[**\--replace**\] \[**\--source-imgref**\] \[**\--target-transport**\] \[**\--target-imgref**\] \[**\--enforce-container-sigpolicy**\] -\[**\--skip-fetch-check**\] \[**\--run-fetch-check**\] +\[**\--run-fetch-check**\] \[**\--skip-fetch-check**\] +\[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] \[**\--bound-images**\] \[**\--stateroot**\] -\[**\--acknowledge-destructive**\] \[**-h**\|**\--help**\] -\[*ROOT_PATH*\] +\[**\--acknowledge-destructive**\] \[**\--cleanup**\] +\[**-h**\|**\--help**\] \[*ROOT_PATH*\] # DESCRIPTION @@ -19,9 +20,9 @@ Install to the host root filesystem. This is a variant of \`install to-filesystem\` that is designed to install \"alongside\" the running host root filesystem. Currently, the -host root filesystems \`/boot\` partition will be wiped, but the content -of the existing root will otherwise be retained, and will need to be -cleaned up if desired when rebooted into the new root. +host root filesystem\'s \`/boot\` partition will be wiped, but the +content of the existing root will otherwise be retained, and will need +to be cleaned up if desired when rebooted into the new root. # OPTIONS @@ -47,8 +48,8 @@ cleaned up if desired when rebooted into the new root. By default, bootc install and install-to-filesystem assumes that it runs in a podman container, and it takes the container image to - install from the podmans container registry. If \--source-imgref is - given, bootc uses it as the installation source, instead of the + install from the podman\'s container registry. If \--source-imgref + is given, bootc uses it as the installation source, instead of the behaviour explained in the previous paragraph. See skopeo(1) for accepted formats. @@ -68,16 +69,17 @@ cleaned up if desired when rebooted into the new root. Enabling this option enforces that \`/etc/containers/policy.json\` includes a default policy which requires signatures -**\--skip-fetch-check (deprecated, see --run-fetch-check)** - -: This is now the default and has no effect. - **\--run-fetch-check** -: Verify the target image can be pulled using the bootc image. +: Verify the image can be fetched from the bootc image. Updates may + fail when the installation host is authenticated with the registry + but the pull secret is not in the bootc image + +**\--skip-fetch-check** - This will ensure the bootc system can be upgraded, - i.e. the registry credentials are available on the bootc image. +: Verify the image can be fetched from the bootc image. Updates may + fail when the installation host is authenticated with the registry + but the pull secret is not in the bootc image **\--disable-selinux** @@ -119,11 +121,11 @@ cleaned up if desired when rebooted into the new root. \ *Possible values:* - - stored: Bound images must exist in the sources root container + - stored: Bound images must exist in the source\'s root container storage (default) - pull: Bound images will be pulled and stored directly in the - targets bootc container storage + target\'s bootc container storage **\--stateroot**=*STATEROOT* @@ -133,9 +135,14 @@ cleaned up if desired when rebooted into the new root. : Accept that this is a destructive action and skip a warning timer +**\--cleanup** + +: Add the bootc-destructive-cleanup systemd service to delete files + from the previous install on first boot + **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') \[*ROOT_PATH*\] \[default: /target\] @@ -145,4 +152,4 @@ cleaned up if desired when rebooted into the new root. # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-install-to-filesystem.md b/docs/src/man/bootc-install-to-filesystem.md index 0d75da229..21adb687a 100644 --- a/docs/src/man/bootc-install-to-filesystem.md +++ b/docs/src/man/bootc-install-to-filesystem.md @@ -10,7 +10,7 @@ filesystem structure \[**\--acknowledge-destructive**\] \[**\--skip-finalize**\] \[**\--source-imgref**\] \[**\--target-transport**\] \[**\--target-imgref**\] \[**\--enforce-container-sigpolicy**\] -\[**\--skip-fetch-check**\] \[**\--run-fetch-check**\] +\[**\--run-fetch-check**\] \[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] \[**\--bound-images**\] \[**\--stateroot**\] \[**-h**\|**\--help**\] @@ -61,8 +61,8 @@ is currently expected to be empty by default. **\--acknowledge-destructive** -: If the target is the running systems root filesystem, this will skip - any warnings +: If the target is the running system\'s root filesystem, this will + skip any warnings **\--skip-finalize** @@ -77,8 +77,8 @@ is currently expected to be empty by default. By default, bootc install and install-to-filesystem assumes that it runs in a podman container, and it takes the container image to - install from the podmans container registry. If \--source-imgref is - given, bootc uses it as the installation source, instead of the + install from the podman\'s container registry. If \--source-imgref + is given, bootc uses it as the installation source, instead of the behaviour explained in the previous paragraph. See skopeo(1) for accepted formats. @@ -98,16 +98,17 @@ is currently expected to be empty by default. Enabling this option enforces that \`/etc/containers/policy.json\` includes a default policy which requires signatures -**\--skip-fetch-check (deprecated, see --run-fetch-check)** - -: This is now the default and has no effect. - **\--run-fetch-check** -: Verify the target image can be pulled using the bootc image. +: Verify the image can be fetched from the bootc image. Updates may + fail when the installation host is authenticated with the registry + but the pull secret is not in the bootc image + +**\--skip-fetch-check** - This will ensure the bootc system can be upgraded, - i.e. the registry credentials are available on the bootc image. +: Verify the image can be fetched from the bootc image. Updates may + fail when the installation host is authenticated with the registry + but the pull secret is not in the bootc image **\--disable-selinux** @@ -149,11 +150,11 @@ is currently expected to be empty by default. \ *Possible values:* - - stored: Bound images must exist in the sources root container + - stored: Bound images must exist in the source\'s root container storage (default) - pull: Bound images will be pulled and stored directly in the - targets bootc container storage + target\'s bootc container storage **\--stateroot**=*STATEROOT* @@ -161,7 +162,7 @@ is currently expected to be empty by default. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') \<*ROOT_PATH*\> @@ -172,4 +173,4 @@ is currently expected to be empty by default. # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-install.md b/docs/src/man/bootc-install.md index 5c8b01466..71ad36a89 100644 --- a/docs/src/man/bootc-install.md +++ b/docs/src/man/bootc-install.md @@ -32,7 +32,7 @@ includes other setup and metadata. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # SUBCOMMANDS @@ -71,4 +71,4 @@ bootc-install-help(8) # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-rollback.md b/docs/src/man/bootc-rollback.md index c1b41a77c..2282e12c9 100644 --- a/docs/src/man/bootc-rollback.md +++ b/docs/src/man/bootc-rollback.md @@ -7,7 +7,7 @@ queued upgrade) then it will be discarded # SYNOPSIS -**bootc rollback** \[**\--apply**\] \[**-h**\|**\--help**\] +**bootc rollback** \[**\--apply**\] \[**-h**\|**\--help**\] # DESCRIPTION @@ -19,8 +19,8 @@ will be discarded. Note that absent any additional control logic, if there is an active agent doing automated upgrades (such as the default \`bootc-fetch-apply-updates.timer\` and associated \`.service\`) the -change here may be reverted. Its recommended to only use this in concert -with an agent that is in active control. +change here may be reverted. It\'s recommended to only use this in +concert with an agent that is in active control. A systemd journal message will be logged with \`MESSAGE_ID=26f3b1eb24464d12aa5e7b544a6b5468\` in order to detect a @@ -38,8 +38,21 @@ rollback invocation. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') + +# EXTRA + +Note on Rollbacks and the \`/etc\` Directory: + +When you perform a rollback (e.g., with \`bootc rollback\`), any changes +made to files in the \`/etc\` directory won't carry over to the +rolled-back deployment. The \`/etc\` files will revert to their state +from that previous deployment instead. + +This is because \`bootc rollback\` just reorders the existing +deployments. It doesn\'t create new deployments. The \`/etc\` merges +happen when new deployments are created. # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-status.md b/docs/src/man/bootc-status.md index 194d07745..e407b5ea1 100644 --- a/docs/src/man/bootc-status.md +++ b/docs/src/man/bootc-status.md @@ -55,8 +55,8 @@ not \`null\`. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-switch.md b/docs/src/man/bootc-switch.md index bcb4f33c3..23b33ca84 100644 --- a/docs/src/man/bootc-switch.md +++ b/docs/src/man/bootc-switch.md @@ -28,7 +28,7 @@ updates via container image tags; for example, **\--quiet** -: Dont display progress +: Don\'t display progress **\--apply** @@ -57,7 +57,7 @@ updates via container image tags; for example, **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') \<*TARGET*\> @@ -65,4 +65,4 @@ updates via container image tags; for example, # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-upgrade.md b/docs/src/man/bootc-upgrade.md index 84104bd8b..de3f07d1d 100644 --- a/docs/src/man/bootc-upgrade.md +++ b/docs/src/man/bootc-upgrade.md @@ -29,7 +29,7 @@ the update in addition. **\--quiet** -: Dont display progress +: Don\'t display progress **\--check** @@ -49,8 +49,8 @@ the update in addition. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc-usr-overlay.md b/docs/src/man/bootc-usr-overlay.md index b2cea46db..154e5cd8f 100644 --- a/docs/src/man/bootc-usr-overlay.md +++ b/docs/src/man/bootc-usr-overlay.md @@ -35,8 +35,8 @@ unmount\". **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') # VERSION -v1.1.6 +v1.4.0 diff --git a/docs/src/man/bootc.md b/docs/src/man/bootc.md index a40277deb..08fec65f3 100644 --- a/docs/src/man/bootc.md +++ b/docs/src/man/bootc.md @@ -22,7 +22,7 @@ pulled and \`bootc upgrade\`. **-h**, **\--help** -: Print help (see a summary with -h) +: Print help (see a summary with \'-h\') **-V**, **\--version** @@ -72,4 +72,4 @@ bootc-help(8) # VERSION -v1.1.6 +v1.4.0