ostree: Describe subcommands in help output

src/ostree/main.c

@@ -32,37 +32,94 @@
 #include "ot-builtins.h"
 
 static OstreeCommand commands[] = {
-  { "admin", ostree_builtin_admin },
-  { "cat", ostree_builtin_cat },
-  { "checkout", ostree_builtin_checkout },
-  { "checksum", ostree_builtin_checksum },
-  { "commit", ostree_builtin_commit },
-  { "config", ostree_builtin_config },
-  { "diff", ostree_builtin_diff },
-  { "export", ostree_builtin_export },
+  /* Note: all admin related commands have
+   * no_repo as their command flag, but each
+   * admin command may have their own
+   * admin flag
+   */
+  { "admin", OSTREE_BUILTIN_FLAG_NO_REPO,
+    ostree_builtin_admin,
+    "Commands that needs admin privilege" },
+  { "cat", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_cat,
+    "Concatenate contents of files"},
+  { "checkout", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_checkout,
+    "Check out a commit into a filesystem tree" },
+  { "checksum", OSTREE_BUILTIN_FLAG_NO_REPO,
+    ostree_builtin_checksum,
+    "Checksum a file or directory" },
+  { "commit", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_commit,
+    "Commit a new revision" },
+  { "config", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_config,
+    "Change repo configuration settings" },
+  { "diff", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_diff,
+    "Compare directory TARGETDIR against revision REV"},
+  { "export", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_export,
+    "Stream COMMIT to stdout in tar format" },
 #ifdef OSTREE_ENABLE_EXPERIMENTAL_API
-  { "find-remotes", ostree_builtin_find_remotes },
-  { "create-usb", ostree_builtin_create_usb },
+  { "find-remotes", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_find_remotes,
+    "Find remotes to serve the given refs" },
+  { "create-usb", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_create_usb,
+    "Copy the refs to a USB stick" },
 #endif
-  { "fsck", ostree_builtin_fsck },
-  { "gpg-sign", ostree_builtin_gpg_sign },
-  { "init", ostree_builtin_init },
-  { "log", ostree_builtin_log },
-  { "ls", ostree_builtin_ls },
-  { "prune", ostree_builtin_prune },
-  { "pull-local", ostree_builtin_pull_local },
+  { "fsck", OSTREE_BUILTIN_FLAG_NONE,
+     ostree_builtin_fsck,
+    "Check the repository for consistency" },
+  { "gpg-sign", OSTREE_BUILTIN_FLAG_NONE,
+     ostree_builtin_gpg_sign,
+    "Sign a commit" },
+  { "init", OSTREE_BUILTIN_FLAG_NO_CHECK,
+    ostree_builtin_init,
+    "Initialize a new empty repository" },
+  { "log", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_log,
+    "Show log starting at commit or ref" },
+  { "ls", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_ls,
+    "List file paths" },
+  { "prune", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_prune,
+    "Search for unreachable objects" },
+  { "pull-local", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_pull_local,
+    "Copy data from SRC_REPO" },
 #ifdef HAVE_LIBCURL_OR_LIBSOUP
-  { "pull", ostree_builtin_pull },
+  { "pull", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_pull,
+    "Download data from remote repository" },
 #endif
-  { "refs", ostree_builtin_refs },
-  { "remote", ostree_builtin_remote },
-  { "reset", ostree_builtin_reset },
-  { "rev-parse", ostree_builtin_rev_parse },
-  { "show", ostree_builtin_show },
-  { "static-delta", ostree_builtin_static_delta },
-  { "summary", ostree_builtin_summary },
+  { "refs", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_refs,
+    "List refs" },
+  { "remote", OSTREE_BUILTIN_FLAG_NO_REPO,
+    ostree_builtin_remote,
+    "Remote commands that may involve internet access" },
+  { "reset", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_reset,
+    "Reset a REF to a previous COMMIT" },
+  { "rev-parse", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_rev_parse,
+    "Output the target of a rev" },
+  { "show", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_show,
+    "Output a metadata object" },
+  { "static-delta", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_static_delta,
+    "Static delta related commands" },
+  { "summary", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_summary,
+    "Manage summary metadata" },
 #if defined(HAVE_LIBSOUP) && defined(BUILDOPT_ENABLE_TRIVIAL_HTTPD_CMDLINE)
-  { "trivial-httpd", ostree_builtin_trivial_httpd },
+  { "trivial-httpd", OSTREE_BUILTIN_FLAG_NONE,
+    ostree_builtin_trivial_httpd,
+    NULL },
 #endif
   { NULL }
 };

src/ostree/ot-admin-builtin-cleanup.c

@@ -38,17 +38,17 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_cleanup (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_cleanup (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   g_autoptr(GOptionContext) context = NULL;
   g_autoptr(OstreeSysroot) sysroot = NULL;
   gboolean ret = FALSE;
 
-  context = g_option_context_new ("Delete untagged deployments and repository objects");
+  context = g_option_context_new ("");
 
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     goto out;
 
   if (!ostree_sysroot_cleanup (sysroot, cancellable, error))

src/ostree/ot-admin-builtin-deploy.c

@@ -60,17 +60,17 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_deploy (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_deploy (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   __attribute__((cleanup(_ostree_kernel_args_cleanup))) OstreeKernelArgs *kargs = NULL;
 
   g_autoptr(GOptionContext) context =
-    g_option_context_new ("REFSPEC - Checkout revision REFSPEC as the new default deployment");
+    g_option_context_new ("REFSPEC");
 
   g_autoptr(OstreeSysroot) sysroot = NULL;
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     return FALSE;
 
   if (argc < 2)

src/ostree/ot-admin-builtin-diff.c

@@ -41,7 +41,7 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_diff (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_diff (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   g_autoptr(GOptionContext) context = NULL;
   g_autoptr(OstreeSysroot) sysroot = NULL;
@@ -54,13 +54,13 @@ ot_admin_builtin_diff (int argc, char **argv, GCancellable *cancellable, GError
   g_autoptr(GFile) orig_etc_path = NULL;
   g_autoptr(GFile) new_etc_path = NULL;
 
-  context = g_option_context_new ("Diff current /etc configuration versus default");
+  context = g_option_context_new ("");
 
   g_option_context_add_main_entries (context, options, NULL);
 
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER | OSTREE_ADMIN_BUILTIN_FLAG_UNLOCKED,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     goto out;
 
   if (!ot_admin_require_booted_deployment_or_osname (sysroot, opt_osname,

src/ostree/ot-admin-builtin-init-fs.c

@@ -38,15 +38,15 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_init_fs (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_init_fs (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
-  g_autoptr(GOptionContext) context = g_option_context_new ("PATH - Initialize a root filesystem");
+  g_autoptr(GOptionContext) context = g_option_context_new ("PATH");
 
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER |
-                                           OSTREE_ADMIN_BUILTIN_FLAG_UNLOCKED |
-                                           OSTREE_ADMIN_BUILTIN_FLAG_NO_SYSROOT,
-                                          NULL, cancellable, error))
+                                          OSTREE_ADMIN_BUILTIN_FLAG_UNLOCKED |
+                                          OSTREE_ADMIN_BUILTIN_FLAG_NO_SYSROOT,
+                                          invocation, NULL, cancellable, error))
     return FALSE;
 
   if (argc < 2)

src/ostree/ot-admin-builtin-instutil.c

@@ -28,31 +28,35 @@
 
 #include <glib/gi18n.h>
 
-typedef struct {
-  const char *name;
-  gboolean (*fn) (int argc, char **argv, GCancellable *cancellable, GError **error);
-} OstreeAdminInstUtilCommand;
-
-static OstreeAdminInstUtilCommand admin_instutil_subcommands[] = {
+static OstreeCommand admin_instutil_subcommands[] = {
 #ifdef HAVE_SELINUX
-  { "selinux-ensure-labeled", ot_admin_instutil_builtin_selinux_ensure_labeled },
+  { "selinux-ensure-labeled", OSTREE_BUILTIN_FLAG_NO_REPO,
+    ot_admin_instutil_builtin_selinux_ensure_labeled,
+    "Relabel all or part of a deployment" },
 #endif
-  { "set-kargs", ot_admin_instutil_builtin_set_kargs },
-  { "grub2-generate", ot_admin_instutil_builtin_grub2_generate },
-  { NULL, NULL }
+  { "set-kargs", OSTREE_BUILTIN_FLAG_NO_REPO,
+    ot_admin_instutil_builtin_set_kargs,
+    "Set new kernel command line arguments(Not stable)"  },
+  { "grub2-generate", OSTREE_BUILTIN_FLAG_NO_REPO,
+    ot_admin_instutil_builtin_grub2_generate,
+    "Generate GRUB2 configuration from given BLS entries" },
+  { NULL, 0, NULL, NULL }
 };
 
 static GOptionContext *
 ostree_admin_instutil_option_context_new_with_commands (void)
 {
-  OstreeAdminInstUtilCommand *command = admin_instutil_subcommands;
+  OstreeCommand *command = admin_instutil_subcommands;
   GOptionContext *context = g_option_context_new ("COMMAND");
 
   g_autoptr(GString) summary = g_string_new ("Builtin \"admin instutil\" Commands:");
 
   while (command->name != NULL)
     {
-      g_string_append_printf (summary, "\n  %s", command->name);
+      g_string_append_printf (summary, "\n  %-24s", command->name);
+        if (command->description != NULL)
+          g_string_append_printf (summary, "%s", command->description);
+
       command++;
     }
 
@@ -62,7 +66,7 @@ ostree_admin_instutil_option_context_new_with_commands (void)
 }
 
 gboolean
-ot_admin_builtin_instutil (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_instutil (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   const char *subcommand_name = NULL;
   int in, out;
@@ -90,7 +94,7 @@ ot_admin_builtin_instutil (int argc, char **argv, GCancellable *cancellable, GEr
 
   argc = out;
 
-  OstreeAdminInstUtilCommand *subcommand = admin_instutil_subcommands;
+  OstreeCommand *subcommand = admin_instutil_subcommands;
   while (subcommand->name)
     {
       if (g_strcmp0 (subcommand_name, subcommand->name) == 0)
@@ -106,7 +110,7 @@ ot_admin_builtin_instutil (int argc, char **argv, GCancellable *cancellable, GEr
       /* This will not return for some options (e.g. --version). */
       if (ostree_admin_option_context_parse (context, NULL, &argc, &argv,
                                              OSTREE_ADMIN_BUILTIN_FLAG_NO_SYSROOT,
-                                             NULL, cancellable, error))
+                                             invocation, NULL, cancellable, error))
         {
           if (subcommand_name == NULL)
             {
@@ -128,7 +132,8 @@ ot_admin_builtin_instutil (int argc, char **argv, GCancellable *cancellable, GEr
   g_autofree char *prgname = g_strdup_printf ("%s %s", g_get_prgname (), subcommand_name);
   g_set_prgname (prgname);
 
-  if (!subcommand->fn (argc, argv, cancellable, error))
+  OstreeCommandInvocation sub_invocation = { .command = subcommand };
+  if (!subcommand->fn (argc, argv, &sub_invocation, cancellable, error))
     return FALSE;
 
   return TRUE;

src/ostree/ot-admin-builtin-os-init.c

@@ -38,18 +38,18 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_os_init (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_os_init (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   g_autoptr(GOptionContext) context = NULL;
   g_autoptr(OstreeSysroot) sysroot = NULL;
   gboolean ret = FALSE;
   const char *osname = NULL;
 
-  context = g_option_context_new ("OSNAME - Initialize empty state for given operating system");
+  context = g_option_context_new ("OSNAME");
 
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER | OSTREE_ADMIN_BUILTIN_FLAG_UNLOCKED,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     goto out;
 
   if (!ostree_sysroot_ensure_initialized (sysroot, cancellable, error))

src/ostree/ot-admin-builtin-set-origin.c

@@ -45,7 +45,7 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_set_origin (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_set_origin (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   gboolean ret = FALSE;
   g_autoptr(GOptionContext) context = NULL;
@@ -60,7 +60,7 @@ ot_admin_builtin_set_origin (int argc, char **argv, GCancellable *cancellable, G
 
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     goto out;
 
   if (argc < 3)

src/ostree/ot-admin-builtin-status.c

@@ -85,7 +85,7 @@ deployment_get_gpg_verify (OstreeDeployment *deployment,
 }
 
 gboolean
-ot_admin_builtin_status (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_status (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   g_autoptr(GOptionContext) context = NULL;
   g_autoptr(OstreeSysroot) sysroot = NULL;
@@ -100,11 +100,11 @@ ot_admin_builtin_status (int argc, char **argv, GCancellable *cancellable, GErro
   const char *red_bold_suffix = is_tty ? "\x1b[22m\x1b[0m" : "";
   guint i;
 
-  context = g_option_context_new ("List deployments");
+  context = g_option_context_new ("");
 
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_UNLOCKED,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     goto out;
 
   if (!ostree_sysroot_get_repo (sysroot, &repo, cancellable, error))

src/ostree/ot-admin-builtin-switch.c

@@ -44,14 +44,14 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_switch (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_switch (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   g_autoptr(GOptionContext) context =
-    g_option_context_new ("REF - Construct new tree from REF and deploy it");
+    g_option_context_new ("REF");
   g_autoptr(OstreeSysroot) sysroot = NULL;
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     return FALSE;
 
   if (argc < 2)

src/ostree/ot-admin-builtin-undeploy.c

@@ -37,7 +37,7 @@ static GOptionEntry options[] = {
 };
 
 gboolean
-ot_admin_builtin_undeploy (int argc, char **argv, GCancellable *cancellable, GError **error)
+ot_admin_builtin_undeploy (int argc, char **argv, OstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error)
 {
   g_autoptr(GOptionContext) context = NULL;
   g_autoptr(OstreeSysroot) sysroot = NULL;
@@ -46,11 +46,11 @@ ot_admin_builtin_undeploy (int argc, char **argv, GCancellable *cancellable, GEr
   g_autoptr(GPtrArray) current_deployments = NULL;
   g_autoptr(OstreeDeployment) target_deployment = NULL;
 
-  context = g_option_context_new ("INDEX - Delete deployment INDEX");
+  context = g_option_context_new ("INDEX");
 
   if (!ostree_admin_option_context_parse (context, options, &argc, &argv,
                                           OSTREE_ADMIN_BUILTIN_FLAG_SUPERUSER,
-                                          &sysroot, cancellable, error))
+                                          invocation, &sysroot, cancellable, error))
     return FALSE;
 
   if (argc < 2)