ostree: Describe subcommands in help output

Added a description argument to all type
of commands. Now when we include -h or --help
for commands that contain subcommands, the description
for those subcommands are shown.

The added subcommands help will be provided to the following commands:
- ostree -h
- ostree admin -h
- ostree admin instutil -h
- ostree remote -h
- ostree static-delta -h

Closes: #1267
Approved by: cgwalters

9 files changed, 140 insertions, 67 deletions

diff --git a/src/ostree/main.c b/src/ostree/main.c
index 66cfae7f..ef8f1f8a 100644
--- a/src/ostree/main.c
+++ b/src/ostree/main.c
@@ -32,37 +32,63 @@
 #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 },
+  { "admin", ostree_builtin_admin ,
+    "Commands that needs admin privilege" },
+  { "cat", ostree_builtin_cat,
+    "Concatenate contents of files"},
+  { "checkout", ostree_builtin_checkout,
+    "Check out a commit into a filesystem tree" },
+  { "checksum", ostree_builtin_checksum,
+    "Checksum a file or directory" },
+  { "commit", ostree_builtin_commit,
+    "Commit a new revision" },
+  { "config", ostree_builtin_config,
+    "Change repo configuration settings" },
+  { "diff", ostree_builtin_diff,
+    "Compare directory TARGETDIR against revision REV"},
+  { "export", 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_find_remotes,
+    "Find remotes to serve the given refs" },
+  { "create-usb", 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_fsck,
+    "Check the repository for consistency" },
+  { "gpg-sign", ostree_builtin_gpg_sign,
+    "Sign a commit" },
+  { "init", ostree_builtin_init,
+    "Initialize a new empty repository" },
+  { "log", ostree_builtin_log,
+    "Show log starting at commit or ref" },
+  { "ls", ostree_builtin_ls,
+    "List file paths" },
+  { "prune", ostree_builtin_prune,
+    "Search for unreachable objects" },
+  { "pull-local", ostree_builtin_pull_local,
+    "Copy data from SRC_REPO" },
 #ifdef HAVE_LIBCURL_OR_LIBSOUP
-  { "pull", ostree_builtin_pull },
+  { "pull", 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_refs,
+    "List refs" },
+  { "remote", ostree_builtin_remote,
+    "Remote commands that may involve internet access" },
+  { "reset", ostree_builtin_reset,
+    "Reset a REF to a previous COMMIT" },
+  { "rev-parse", ostree_builtin_rev_parse,
+    "Output the target of a rev" },
+  { "show", ostree_builtin_show,
+    "Output a metadata object" },
+  { "static-delta", ostree_builtin_static_delta,
+    "Static delta related commands" },
+  { "summary", 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_trivial_httpd,
+    NULL },
 #endif
   { NULL }
 };
diff --git a/src/ostree/ot-admin-builtin-instutil.c b/src/ostree/ot-admin-builtin-instutil.c
index 91c4c114..428c0a2c 100644
--- a/src/ostree/ot-admin-builtin-instutil.c
+++ b/src/ostree/ot-admin-builtin-instutil.c
@@ -31,15 +31,19 @@
 typedef struct {
   const char *name;
   gboolean (*fn) (int argc, char **argv, GCancellable *cancellable, GError **error);
+  const char *description;
 } OstreeAdminInstUtilCommand;
 
 static OstreeAdminInstUtilCommand admin_instutil_subcommands[] = {
 #ifdef HAVE_SELINUX
-  { "selinux-ensure-labeled", ot_admin_instutil_builtin_selinux_ensure_labeled },
+  { "selinux-ensure-labeled", 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", ot_admin_instutil_builtin_set_kargs,
+    "Set new kernel command line arguments(Not stable)"  },
+  { "grub2-generate", ot_admin_instutil_builtin_grub2_generate,
+    "Generate GRUB2 configuration from given BLS entries" },
+  { NULL, NULL, NULL }
 };
 
 static GOptionContext *
@@ -52,7 +56,10 @@ ostree_admin_instutil_option_context_new_with_commands (void)
 
   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++;
     }
 
diff --git a/src/ostree/ot-builtin-admin.c b/src/ostree/ot-builtin-admin.c
index 85db78ec..ba9dc28d 100644
--- a/src/ostree/ot-builtin-admin.c
+++ b/src/ostree/ot-builtin-admin.c
@@ -33,22 +33,35 @@
 typedef struct {
   const char *name;
   gboolean (*fn) (int argc, char **argv, GCancellable *cancellable, GError **error);
+  const char *description;
 } OstreeAdminCommand;
 
 static OstreeAdminCommand admin_subcommands[] = {
-  { "cleanup", ot_admin_builtin_cleanup },
-  { "config-diff", ot_admin_builtin_diff },
-  { "deploy", ot_admin_builtin_deploy }, 
-  { "init-fs", ot_admin_builtin_init_fs },
-  { "instutil", ot_admin_builtin_instutil },
-  { "os-init", ot_admin_builtin_os_init },
-  { "set-origin", ot_admin_builtin_set_origin },
-  { "status", ot_admin_builtin_status },
-  { "switch", ot_admin_builtin_switch },
-  { "undeploy", ot_admin_builtin_undeploy },
-  { "unlock", ot_admin_builtin_unlock }, 
-  { "upgrade", ot_admin_builtin_upgrade },
-  { NULL, NULL }
+  { "cleanup", ot_admin_builtin_cleanup,
+    "Delete untagged deployments and repository objects" },
+  { "config-diff", ot_admin_builtin_diff,
+    "Diff current /etc configuration versus default" },
+  { "deploy", ot_admin_builtin_deploy,
+    "Checkout revision REFSPEC as the new default deployment" },
+  { "init-fs", ot_admin_builtin_init_fs,
+    "Initialize a root filesystem" },
+  { "instutil", ot_admin_builtin_instutil,
+    "Provide instutil commands, allow admin to change boot configuration and relabel selinux " },
+  { "os-init", ot_admin_builtin_os_init,
+    "Initialize empty state for given operating system" },
+  { "set-origin", ot_admin_builtin_set_origin,
+    "Set Origin and create a new origin file" },
+  { "status", ot_admin_builtin_status,
+    "List deployments" },
+  { "switch", ot_admin_builtin_switch,
+    "Construct new tree from REF and deploy it" },
+  { "undeploy", ot_admin_builtin_undeploy,
+    "Delete deployment INDEX" },
+  { "unlock", ot_admin_builtin_unlock,
+    "Make the current deployment mutable (as a hotfix or development)" },
+  { "upgrade", ot_admin_builtin_upgrade,
+    "Construct new tree from current origin and deploy it, if it changed" },
+  { NULL, NULL, NULL }
 };
 
 static GOptionContext *
@@ -61,7 +74,9 @@ ostree_admin_option_context_new_with_commands (void)
 
   while (command->name != NULL)
     {
-      g_string_append_printf (summary, "\n  %s", command->name);
+      g_string_append_printf (summary, "\n  %-19s", command->name);
+        if (command->description != NULL)
+          g_string_append_printf (summary, "%s", command->description);
       command++;
     }
 
diff --git a/src/ostree/ot-builtin-remote.c b/src/ostree/ot-builtin-remote.c
index c9b3be35..0b1c02a2 100644
--- a/src/ostree/ot-builtin-remote.c
+++ b/src/ostree/ot-builtin-remote.c
@@ -28,22 +28,33 @@
 typedef struct {
   const char *name;
   gboolean (*fn) (int argc, char **argv, GCancellable *cancellable, GError **error);
+  const char *description;
 } OstreeRemoteCommand;
 
 static OstreeRemoteCommand remote_subcommands[] = {
-  { "add", ot_remote_builtin_add },
-  { "delete", ot_remote_builtin_delete },
-  { "show-url", ot_remote_builtin_show_url },
-  { "list", ot_remote_builtin_list },
-  { "gpg-import", ot_remote_builtin_gpg_import },
+  { "add", ot_remote_builtin_add,
+    "Add a remote repository" },
+  { "delete", ot_remote_builtin_delete,
+    "Delete a remote repository" },
+  { "show-url", ot_remote_builtin_show_url,
+    "Show remote repository URL" },
+  { "list", ot_remote_builtin_list,
+    "List remote repository names" },
+  { "gpg-import", ot_remote_builtin_gpg_import,
+    "Import GPG keys" },
 #ifdef HAVE_LIBSOUP
-  { "add-cookie", ot_remote_builtin_add_cookie },
-  { "delete-cookie", ot_remote_builtin_delete_cookie },
-  { "list-cookies", ot_remote_builtin_list_cookies },
+  { "add-cookie", ot_remote_builtin_add_cookie,
+    "Add a cookie to remote" },
+  { "delete-cookie", ot_remote_builtin_delete_cookie,
+    "Remove one cookie from remote" },
+  { "list-cookies", ot_remote_builtin_list_cookies,
+    "Show remote repository cookies" },
 #endif
-  { "refs", ot_remote_builtin_refs },
-  { "summary", ot_remote_builtin_summary },
-  { NULL, NULL }
+  { "refs", ot_remote_builtin_refs,
+    "List remote refs" },
+  { "summary", ot_remote_builtin_summary,
+    "Show remote summary" },
+  { NULL, NULL, NULL }
 };
 
 static GOptionContext *
@@ -56,7 +67,10 @@ remote_option_context_new_with_commands (void)
 
   while (subcommand->name != NULL)
     {
-      g_string_append_printf (summary, "\n  %s", subcommand->name);
+      g_string_append_printf (summary, "\n  %-18s", subcommand->name);
+      if (subcommand->description != NULL)
+        g_string_append_printf (summary, "%s", subcommand->description);
+
       subcommand++;
     }
 
diff --git a/src/ostree/ot-builtin-static-delta.c b/src/ostree/ot-builtin-static-delta.c
index c5d22dad..b2af1d66 100644
--- a/src/ostree/ot-builtin-static-delta.c
+++ b/src/ostree/ot-builtin-static-delta.c
@@ -50,12 +50,17 @@ BUILTINPROTO(apply_offline);
 #undef BUILTINPROTO
 
 static OstreeCommand static_delta_subcommands[] = {
-  { "list", ot_static_delta_builtin_list },
-  { "show", ot_static_delta_builtin_show },
-  { "delete", ot_static_delta_builtin_delete },
-  { "generate", ot_static_delta_builtin_generate },
-  { "apply-offline", ot_static_delta_builtin_apply_offline },
-  { NULL, NULL }
+  { "list", ot_static_delta_builtin_list,
+    "List static delta files" },
+  { "show", ot_static_delta_builtin_show,
+    "Dump information on a delta" },
+  { "delete", ot_static_delta_builtin_delete,
+    "Remove a delta" },
+  { "generate", ot_static_delta_builtin_generate,
+    "Generate static delta files" },
+  { "apply-offline", ot_static_delta_builtin_apply_offline,
+    "Apply static delta file" },
+  { NULL, NULL, NULL }
 };
 
 /* ATTENTION:
@@ -105,7 +110,7 @@ static_delta_usage (char    **argv,
 
   while (command->name)
     {
-      print_func ("  %s\n", command->name);
+      print_func ("  %-17s%s\n", command->name, command->description ?: "");
       command++;
     }
 
diff --git a/src/ostree/ot-main.c b/src/ostree/ot-main.c
index 8e8c4631..d81b802c 100644
--- a/src/ostree/ot-main.c
+++ b/src/ostree/ot-main.c
@@ -64,7 +64,11 @@ ostree_option_context_new_with_commands (OstreeCommand *commands)
 
   while (commands->name != NULL)
     {
-      g_string_append_printf (summary, "\n  %s", commands->name);
+      g_string_append_printf (summary, "\n  %-18s", commands->name);
+
+      if (commands->description != NULL )
+        g_string_append_printf (summary, "%s", commands->description);
+
       commands++;
     }
 
diff --git a/src/ostree/ot-main.h b/src/ostree/ot-main.h
index 11fc287e..d795e531 100644
--- a/src/ostree/ot-main.h
+++ b/src/ostree/ot-main.h
@@ -40,6 +40,7 @@ typedef enum {
 typedef struct {
   const char *name;
   gboolean (*fn) (int argc, char **argv, GCancellable *cancellable, GError **error);
+  const char *description;
 } OstreeCommand;
 
 int ostree_run (int argc, char **argv, OstreeCommand *commands, GError **error);
diff --git a/src/ostree/ot-remote-builtin-delete-cookie.c b/src/ostree/ot-remote-builtin-delete-cookie.c
index ecb2451b..17f356a1 100644
--- a/src/ostree/ot-remote-builtin-delete-cookie.c
+++ b/src/ostree/ot-remote-builtin-delete-cookie.c
@@ -41,7 +41,7 @@ gboolean
 ot_remote_builtin_delete_cookie (int argc, char **argv, GCancellable *cancellable, GError **error)
 {
   g_autoptr(OstreeRepo) repo = NULL;
-  g_autoptr(GOptionContext) context = g_option_context_new ("NAME DOMAIN PATH COOKIE_NAME- Remote one cookie from remote");
+  g_autoptr(GOptionContext) context = g_option_context_new ("NAME DOMAIN PATH COOKIE_NAME- Remove one cookie from remote");
 
   if (!ostree_option_context_parse (context, option_entries, &argc, &argv,
                                     OSTREE_BUILTIN_FLAG_NONE, &repo, cancellable, error))
diff --git a/tests/test-help.sh b/tests/test-help.sh
index ad74aaf9..840d6fb6 100755
--- a/tests/test-help.sh
+++ b/tests/test-help.sh
@@ -46,7 +46,8 @@ test_recursive() {
     test_usage_output out "$cmd"
     assert_file_empty err
 
-    builtins=`sed -n '/^Builtin \("[^"]*" \)\?Commands:$/,/^$/p' <out | tail -n +2`
+    # Select the list of commands, for each line, remove the leading spaces, and take the first word(command) of each line
+    builtins=`sed -n '/^Builtin \("[^"]*" \)\?Commands:$/,/^$/p' <out | tail -n +2 | sed -e 's/^[[:space:]]*//' | cut -d " " -f1`
     if [ "$builtins" != "" ] ; then
 
         found_subcommands=1