Help text improvement for cfsctl

- Bump clap version to enable "wrap_help" feature for better terminal visibility

Signed-off-by: Chaser Huang <huangkangjing@gmail.com>
Signed-off-by: Colin Walters <walters@verbum.org>

Author: chaserhkj

crates/cfsctl/Cargo.toml

@@ -20,7 +20,7 @@ rhel9 = ['composefs/rhel9']
 [dependencies]
 anyhow = { version = "1.0.87", default-features = false }
 fn-error-context = "0.2"
-clap = { version = "4.0.1", default-features = false, features = ["std", "help", "usage", "derive"] }
+clap = { version = "4.5.0", default-features = false, features = ["std", "help", "usage", "derive", "wrap_help"] }
 composefs = { workspace = true }
 composefs-boot = { workspace = true }
 composefs-oci = { workspace = true, optional = true }

crates/cfsctl/src/main.rs

@@ -26,10 +26,13 @@ use composefs::{
 #[derive(Debug, Parser)]
 #[clap(name = "cfsctl", version)]
 pub struct App {
+    /// Operate on repo at path
     #[clap(long, group = "repopath")]
     repo: Option<PathBuf>,
+    /// Operate on repo at standard user location $HOME/.var/lib/composefs
     #[clap(long, group = "repopath")]
     user: bool,
+    /// Operate on repo at standard system location /sysroot/composefs
     #[clap(long, group = "repopath")]
     system: bool,
 
@@ -54,58 +57,91 @@ enum HashType {
     Sha512,
 }
 
+/// Common options for operations using OCI config manifest streams that may transform the image rootfs
+#[derive(Debug, Parser)]
+struct OCIConfigFilesystemOptions {
+    #[clap(flatten)]
+    base_config: OCIConfigOptions,
+    /// Whether bootable transformation should be performed on the image rootfs
+    #[clap(long)]
+    bootable: bool,
+}
+
+/// Common options for operations using OCI config manifest streams
+#[derive(Debug, Parser)]
+struct OCIConfigOptions {
+    /// the name of the target OCI manifest stream, either a stream ID in format oci-config-<hash_type>:<hash_digest> or a reference in 'ref/'
+    config_name: String,
+    /// verity digest for the manifest stream to be verified against
+    config_verity: Option<String>,
+}
+
 #[cfg(feature = "oci")]
 #[derive(Debug, Subcommand)]
 enum OciCommand {
-    /// Stores a tar file as a splitstream in the repository.
+    /// Stores a tar layer file as a splitstream in the repository.
     ImportLayer {
         digest: String,
         name: Option<String>,
     },
     /// Lists the contents of a tar stream
     LsLayer {
-        /// the name of the stream
+        /// the name of the stream to list, either a stream ID in format oci-config-<hash_type>:<hash_digest> or a reference in 'ref/'
         name: String,
     },
+    /// Dump full content of the rootfs of a stored OCI image to a composefs dumpfile and write to stdout
     Dump {
-        config_name: String,
-        config_verity: Option<String>,
-        #[clap(long)]
-        bootable: bool,
+        #[clap(flatten)]
+        config_opts: OCIConfigFilesystemOptions,
     },
+    /// Pull an OCI image to be stored in repo then prints the stream and verity digest of its manifest
     Pull {
+        /// source image reference, as accepted by skopeo
         image: String,
+        /// optional reference name for the manifest, use as 'ref/<name>' elsewhere
         name: Option<String>,
     },
+    /// Compute the composefs image object id of the rootfs of a stored OCI image
     ComputeId {
-        config_name: String,
-        config_verity: Option<String>,
-        #[clap(long)]
-        bootable: bool,
+        #[clap(flatten)]
+        config_opts: OCIConfigFilesystemOptions,
     },
+    /// Create the composefs image of the rootfs of a stored OCI image, commit it to the repo, and print its image object ID
     CreateImage {
-        config_name: String,
-        config_verity: Option<String>,
-        #[clap(long)]
-        bootable: bool,
+        #[clap(flatten)]
+        config_opts: OCIConfigFilesystemOptions,
+        /// optional reference name for the image, use as 'ref/<name>' elsewhere
         #[clap(long)]
         image_name: Option<String>,
     },
+    /// Seal a stored OCI image by creating a cloned manifest with embedded verity digest (a.k.a. composefs image object ID)
+    /// in the repo, then prints the stream and verity digest of the new sealed manifest
     Seal {
-        config_name: String,
-        config_verity: Option<String>,
+        #[clap(flatten)]
+        config_opts: OCIConfigOptions,
     },
+    /// Mounts a stored and sealed OCI image by looking up its composefs image. Note that the composefs image must be built
+    /// and committed to the repo first
     Mount {
+        /// the name of the target OCI manifest stream, either a stream ID in format oci-config-<hash_type>:<hash_digest> or a reference in 'ref/'
         name: String,
+        /// the mountpoint
         mountpoint: String,
     },
+    /// Create the composefs image of the rootfs of a stored OCI image, perform bootable transformation, commit it to the repo,
+    /// then configure boot for the image by writing new boot resources and bootloader entries to boot partition. Performs
+    /// state preparation for composefs-setup-root consumption as well. Note that state preparation here is not suitable for
+    /// consumption by bootc.
     PrepareBoot {
-        config_name: String,
-        config_verity: Option<String>,
+        #[clap(flatten)]
+        config_opts: OCIConfigOptions,
+        /// boot partition mount point
         #[clap(long, default_value = "/boot")]
         bootdir: PathBuf,
+        /// Boot entry identifier to use. By default uses ID provided by the image or kernel version
         #[clap(long)]
         entry_id: Option<String>,
+        /// additional kernel command line
         #[clap(long)]
         cmdline: Vec<String>,
     },
@@ -145,37 +181,44 @@ enum Command {
     },
     /// Imports a composefs image (unsafe!)
     ImportImage { reference: String },
-    /// Commands for dealing with OCI layers
+    /// Commands for dealing with OCI images and layers
     #[cfg(feature = "oci")]
     Oci {
         #[clap(subcommand)]
         cmd: OciCommand,
     },
-    /// Mounts a composefs, possibly enforcing fsverity of the image
+    /// Mounts a composefs image, possibly enforcing fsverity of the image
     Mount {
         /// the name of the image to mount, either an fs-verity hash or prefixed with 'ref/'
         name: String,
         /// the mountpoint
         mountpoint: String,
     },
-    /// Creates a composefs image from a filesystem
+    /// Read rootfs located at a path, add all files to the repo, then create the composefs image of the rootfs,
+    /// commit it to the repo, and print its image object ID
     CreateImage {
         #[clap(flatten)]
         fs_opts: FsReadOptions,
+        /// optional reference name for the image, use as 'ref/<name>' elsewhere
         image_name: Option<String>,
     },
-    /// Computes the composefs image ID for a filesystem
+    /// Read rootfs located at a path, add all files to the repo, then compute the composefs image object id of the rootfs.
+    /// Note that this does not create or commit the composefs image itself.
     ComputeId {
         #[clap(flatten)]
         fs_opts: FsReadOptions,
     },
-    /// Outputs the composefs dumpfile format for a filesystem
+    /// Read rootfs located at a path, add all files to the repo, then dump full content of the rootfs to a composefs dumpfile
+    /// and write to stdout.
     CreateDumpfile {
         #[clap(flatten)]
         fs_opts: FsReadOptions,
     },
     /// Lists all object IDs referenced by an image
-    ImageObjects { name: String },
+    ImageObjects {
+        /// the name of the image to read, either an object ID digest or prefixed with 'ref/'
+        name: String,
+    },
     #[cfg(feature = "http")]
     Fetch { url: String, name: String },
 }
@@ -256,9 +299,15 @@ where
                 composefs_oci::ls_layer(&repo, &name)?;
             }
             OciCommand::Dump {
-                ref config_name,
-                ref config_verity,
-                bootable,
+                config_opts:
+                    OCIConfigFilesystemOptions {
+                        base_config:
+                            OCIConfigOptions {
+                                ref config_name,
+                                ref config_verity,
+                            },
+                        bootable,
+                    },
             } => {
                 let verity = verity_opt(config_verity)?;
                 let mut fs =
@@ -269,9 +318,15 @@ where
                 fs.print_dumpfile()?;
             }
             OciCommand::ComputeId {
-                ref config_name,
-                ref config_verity,
-                bootable,
+                config_opts:
+                    OCIConfigFilesystemOptions {
+                        base_config:
+                            OCIConfigOptions {
+                                ref config_name,
+                                ref config_verity,
+                            },
+                        bootable,
+                    },
             } => {
                 let verity = verity_opt(config_verity)?;
                 let mut fs =
@@ -283,9 +338,15 @@ where
                 println!("{}", id.to_hex());
             }
             OciCommand::CreateImage {
-                ref config_name,
-                ref config_verity,
-                bootable,
+                config_opts:
+                    OCIConfigFilesystemOptions {
+                        base_config:
+                            OCIConfigOptions {
+                                ref config_name,
+                                ref config_verity,
+                            },
+                        bootable,
+                    },
                 ref image_name,
             } => {
                 let verity = verity_opt(config_verity)?;
@@ -305,8 +366,11 @@ where
                 println!("verity {}", verity.to_hex());
             }
             OciCommand::Seal {
-                ref config_name,
-                ref config_verity,
+                config_opts:
+                    OCIConfigOptions {
+                        ref config_name,
+                        ref config_verity,
+                    },
             } => {
                 let verity = verity_opt(config_verity)?;
                 let (digest, verity) =
@@ -321,8 +385,11 @@ where
                 composefs_oci::mount(&repo, name, mountpoint, None)?;
             }
             OciCommand::PrepareBoot {
-                ref config_name,
-                ref config_verity,
+                config_opts:
+                    OCIConfigOptions {
+                        ref config_name,
+                        ref config_verity,
+                    },
                 ref bootdir,
                 ref entry_id,
                 ref cmdline,