lib: Add --verbose flag to the CLI for providing a debug output option

.gitignore

@@ -5,3 +5,6 @@ bootc.tar.zst
 
 # Added by cargo
 /target
+
+# IDEs / Editors
+.idea/

docs/src/SUMMARY.md

@@ -56,6 +56,10 @@
 
 - [bootc image](experimental-bootc-image.md)
 - [--progress-fd](experimental-progress-fd.md)
+- 
+# Troubleshooting
+
+- [increasing_logging_verbosity](increasing_logging_verbosity.md)
 
 # More information
 

docs/src/increasing_logging_verbosity.md

@@ -0,0 +1,48 @@
+# Increasing Logging Verbosity
+
+When troubleshooting issues with **bootc**, it is often helpful to enable **verbose logging** to gain additional insights into its execution flow.
+
+## Using the `--verbose` Flag
+Most **bootc** commands support the `--verbose` flag, which enables detailed logging output. The verbosity level determines how much information is logged.
+
+### **Verbosity Levels**
+The `--verbose` flag can be used multiple times (`-v`, `-vv`, `-vvv`) to increase the verbosity of logging:
+
+| Verbosity Level | Flag Used | Logs Enabled |
+|---------------|-----------|--------------|
+| **WARN** (default) | *(no flag)* | Only warnings and errors |
+| **INFO** | `-v` | Warnings, errors, and general information |
+| **DEBUG** | `-vv` | Info, warnings, errors, and debug logs |
+| **TRACE** | `-vvv` or more | All logs, including low-level tracing |
+
+### Example Usage
+To switch to a new container image with verbose logging enabled:
+```sh
+bootc switch --apply -vv quay.io/centos-bootc/centos-bootc:stream9
+```
+This command will print **INFO, DEBUG, and WARN logs**, helping diagnose issues during the `switch` process.
+
+### Example Output (Verbose Mode Enabled with `-vv`)
+```sh
+$ bootc switch --apply -vvv quay.io/centos-bootc/centos-bootc:stream9
+TRACE Verified uid 0 with CAP_SYS_ADMIN
+DEBUG Re-executing current process for _ostree_unshared
+DEBUG Already in a mount namespace
+DEBUG Current security context is unconfined_u:system_r:install_t:s0:c1023
+INFO We have install_t
+INFO Staged: None
+DEBUG Rollback queued=false
+DEBUG Wrote merge commit b8761b75924d7f21e7f92abc8fd8b3c645d289fc91555
+DEBUG new_with_config: Spawned skopeo pid=1023
+TRACE new_with_config: impl_request: sending request Initialize
+TRACE new_with_config: impl_request: completed request Config=ImageProxy
+```
+With `-vvv`, the output includes **INFO, DEBUG, WARN, and TRACE** level messages.
+
+## Using the `RUST_LOG` Environment Variable
+For even more detailed logging, use the `RUST_LOG` environment variable (if applicable for Rust-based components):
+
+```sh
+RUST_LOG=debug bootc switch --apply -vvv quay.io/centos-bootc/centos-bootc:stream9
+```
+The environment variable will override the `-vvv` and enable **DEBUG** level logs for Rust-based sub-components within **bootc**.

docs/src/man/bootc-container-lint.md

@@ -22,6 +22,12 @@ part of a build process; it will error if any problems are detected.
 
 :   Operate on the provided rootfs
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--fatal-warnings**
 
 :   Make warnings fatal

docs/src/man/bootc-container.md

@@ -13,6 +13,12 @@ Operations which can be executed as part of a container build
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **-h**, **\--help**
 
 :   Print help

docs/src/man/bootc-edit.md

@@ -26,6 +26,12 @@ Only changes to the \`spec\` section are honored.
 
 :   Use filename to edit system specification
 
+**-v**, **\--verbose...**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--quiet**
 
 :   Dont display progress

docs/src/man/bootc-install-ensure-completion.md

@@ -21,6 +21,12 @@ your code is using \`bootc install to-filesystem\` from the start.
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **-h**, **\--help**
 
 :   Print help (see a summary with -h)

docs/src/man/bootc-install-print-configuration.md

@@ -21,6 +21,12 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`.
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **-h**, **\--help**
 
 :   Print help (see a summary with -h)

docs/src/man/bootc-install-to-disk.md

@@ -28,6 +28,12 @@ more complex such as RAID, LVM, LUKS etc.
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--wipe**
 
 :   Automatically wipe all existing data on device

docs/src/man/bootc-install-to-existing-root.md

@@ -41,6 +41,12 @@ cleaned up if desired when rebooted into the new root.
         However, the running system (and all files) will remain in place
         until reboot
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--source-imgref**=*SOURCE_IMGREF*
 
 :   Install the system from an explicitly given source.

docs/src/man/bootc-install-to-filesystem.md

@@ -33,6 +33,12 @@ is currently expected to be empty by default.
 
     If not provided, the UUID of the target filesystem will be used.
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--boot-mount-spec**=*BOOT_MOUNT_SPEC*
 
 :   Mount specification for the /boot filesystem.

docs/src/man/bootc-install.md

@@ -30,6 +30,12 @@ includes other setup and metadata.
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **-h**, **\--help**
 
 :   Print help (see a summary with -h)

docs/src/man/bootc-rollback.md

@@ -28,6 +28,12 @@ rollback invocation.
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **-h**, **\--help**
 
 :   Print help (see a summary with -h)

docs/src/man/bootc-status.md

@@ -29,6 +29,12 @@ not \`null\`.
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--format**=*FORMAT*
 
 :   The output format\

docs/src/man/bootc-switch.md

@@ -30,6 +30,12 @@ updates via container image tags; for example,
 
 :   Dont display progress
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--apply**
 
 :   Restart or reboot into the new target image.

docs/src/man/bootc-upgrade.md

@@ -31,6 +31,12 @@ the update in addition.
 
 :   Dont display progress
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **\--check**
 
 :   Check if an update is available without applying it.

docs/src/man/bootc-usr-overlay.md

@@ -33,6 +33,12 @@ unmount\".
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **-h**, **\--help**
 
 :   Print help (see a summary with -h)

docs/src/man/bootc.md

@@ -20,6 +20,12 @@ pulled and \`bootc upgrade\`.
 
 # OPTIONS
 
+**-v**, **\--verbose**
+
+:   Increase logging verbosity
+
+    Use `-vv`, `-vvv` to increase verbosity more.
+
 **-h**, **\--help**
 
 :   Print help (see a summary with -h)

lib/Cargo.toml

@@ -54,6 +54,7 @@ uuid = { version = "1.8.0", features = ["v4"] }
 tini = "1.3.0"
 comfy-table = "7.1.1"
 thiserror = { workspace = true }
+nix = "0.27.1"
 
 [dev-dependencies]
 similar-asserts = { workspace = true }