Merge pull request #1010 from buildpacks/fix-command-shorts

Standardize command short descriptions
Signed-off-by: David Freilich <[email protected]>

cmd/cmd.go

@@ -69,8 +69,8 @@ func NewPackCommand(logger ConfigurableLogger) (*cobra.Command, error) {
 	rootCmd.AddCommand(commands.NewBuilderCommand(logger, cfg, &packClient))
 	rootCmd.AddCommand(commands.NewBuildpackCommand(logger, cfg, &packClient, buildpackage.NewConfigReader()))
 	rootCmd.AddCommand(commands.NewConfigCommand(logger, cfg, cfgPath, &packClient))
-	rootCmd.AddCommand(commands.Rebase(logger, cfg, &packClient))
 	rootCmd.AddCommand(commands.NewStackCommand(logger))
+	rootCmd.AddCommand(commands.Rebase(logger, cfg, &packClient))
 
 	rootCmd.AddCommand(commands.InspectImage(logger, imagewriter.NewFactory(), cfg, &packClient))
 	rootCmd.AddCommand(commands.InspectBuildpack(logger, &cfg, &packClient))

internal/commands/builder_suggest.go

@@ -10,7 +10,7 @@ func BuilderSuggest(logger logging.Logger, inspector BuilderInspector) *cobra.Co
 	cmd := &cobra.Command{
 		Use:     "suggest",
 		Args:    cobra.NoArgs,
-		Short:   "Display list of recommended builders",
+		Short:   "List the recommended builders",
 		Example: "pack builder suggest",
 		Run: func(cmd *cobra.Command, s []string) {
 			suggestBuilders(logger, inspector)

internal/commands/buildpack_package.go

@@ -37,7 +37,7 @@ func BuildpackPackage(logger logging.Logger, client BuildpackPackager, packageCo
 	var flags BuildpackPackageFlags
 	cmd := &cobra.Command{
 		Use:     "package <name> --config <config-path>",
-		Short:   "Package buildpack in OCI format.",
+		Short:   "Package a buildpack in OCI format.",
 		Args:    cobra.ExactValidArgs(1),
 		Example: "pack buildpack package my-buildpack --config ./package.toml",
 		Long: "buildpack package allows users to package (a) buildpack(s) into OCI format, which can then to be hosted in " +

internal/commands/buildpack_pull.go

@@ -22,7 +22,7 @@ func BuildpackPull(logger logging.Logger, cfg config.Config, client PackClient)
 	cmd := &cobra.Command{
 		Use:     "pull <uri>",
 		Args:    cobra.ExactArgs(1),
-		Short:   prependExperimental("Pull the buildpack from a registry and store it locally"),
+		Short:   prependExperimental("Pull a buildpack from a registry and store it locally"),
 		Example: "pack buildpack pull example/[email protected]",
 		RunE: logError(logger, func(cmd *cobra.Command, args []string) error {
 			registry, err := config.GetRegistry(cfg, flags.BuildpackRegistry)

internal/commands/buildpack_register.go

@@ -20,7 +20,7 @@ func BuildpackRegister(logger logging.Logger, cfg config.Config, client PackClie
 	cmd := &cobra.Command{
 		Use:     "register <image>",
 		Args:    cobra.ExactArgs(1),
-		Short:   prependExperimental("Register the buildpack to a registry"),
+		Short:   prependExperimental("Register a buildpack to a registry"),
 		Example: "pack register my-buildpack",
 		RunE: logError(logger, func(cmd *cobra.Command, args []string) error {
 			registry, err := config.GetRegistry(cfg, flags.BuildpackRegistry)

internal/commands/buildpack_yank.go

@@ -23,7 +23,7 @@ func BuildpackYank(logger logging.Logger, cfg config.Config, client PackClient)
 	cmd := &cobra.Command{
 		Use:     "yank <buildpack-id-and-version>",
 		Args:    cobra.ExactArgs(1),
-		Short:   prependExperimental("Yank the buildpack from the registry"),
+		Short:   prependExperimental("Yank a buildpack from a registry"),
 		Example: "pack yank [email protected]",
 		RunE: logError(logger, func(cmd *cobra.Command, args []string) error {
 			buildpackIDVersion := args[0]

internal/commands/config.go

@@ -12,14 +12,14 @@ import (
 func NewConfigCommand(logger logging.Logger, cfg config.Config, cfgPath string, client PackClient) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "config",
-		Short: "Interact with Pack's configuration",
+		Short: "Interact with your local pack config file",
 		RunE:  nil,
 	}
 
 	cmd.AddCommand(ConfigDefaultBuilder(logger, cfg, cfgPath, client))
 	cmd.AddCommand(ConfigExperimental(logger, cfg, cfgPath))
-	cmd.AddCommand(ConfigTrustedBuilder(logger, cfg, cfgPath))
 	cmd.AddCommand(ConfigRunImagesMirrors(logger, cfg, cfgPath))
+	cmd.AddCommand(ConfigTrustedBuilder(logger, cfg, cfgPath))
 
 	if cfg.Experimental {
 		cmd.AddCommand(ConfigRegistries(logger, cfg, cfgPath))

internal/commands/config_experimental.go

@@ -15,7 +15,7 @@ func ConfigExperimental(logger logging.Logger, cfg config.Config, cfgPath string
 	cmd := &cobra.Command{
 		Use:   "experimental [<true | false>]",
 		Args:  cobra.MaximumNArgs(1),
-		Short: "Print and set the current 'experimental' value from the config",
+		Short: "List and set the current 'experimental' value from the config",
 		Long: "Experimental features in pack are gated, and require you adding setting `experimental=true` to the Pack Config, either manually, or using this command.\n\n" +
 			"* Running `pack config experimental` prints whether experimental features are currently enabled.\n" +
 			"* Running `pack config experimental <true | false>` enables or disables experimental features.",

internal/commands/config_registries.go

@@ -28,13 +28,20 @@ func ConfigRegistries(logger logging.Logger, cfg config.Config, cfgPath string)
 	cmd := &cobra.Command{
 		Use:     "registries",
 		Aliases: []string{"registry", "registreis"},
-		Short:   prependExperimental("Interact with registries"),
+		Short:   prependExperimental("List, add and remove registries"),
+		Long:    bpRegistryExplanation + "\nYou can use the attached commands to list, add, and remove registries from your config",
 		RunE: logError(logger, func(cmd *cobra.Command, args []string) error {
 			listRegistries(args, logger, cfg)
 			return nil
 		}),
 	}
 
+	listCmd := generateListCmd("registries", logger, cfg, listRegistries)
+	listCmd.Example = "pack config registries list"
+	listCmd.Short = prependExperimental(listCmd.Short)
+	listCmd.Long = bpRegistryExplanation + "List Registries saved in the pack config.\n\nShow the registries that are either added by default or have been explicitly added by using `pack config registries add`"
+	cmd.AddCommand(listCmd)
+
 	addCmd := generateAdd("registries", logger, cfg, cfgPath, addRegistry)
 	addCmd.Args = cobra.ExactArgs(2)
 	addCmd.Example = "pack config registries add my-registry https://github.com/buildpacks/my-registry"
@@ -50,12 +57,6 @@ func ConfigRegistries(logger logging.Logger, cfg config.Config, cfgPath string)
 	rmCmd.Long = bpRegistryExplanation + "Users can remove registries from the config by using `pack config registries remove <registry>`"
 	cmd.AddCommand(rmCmd)
 
-	listCmd := generateListCmd("registries", logger, cfg, listRegistries)
-	listCmd.Example = "pack config registries list"
-	listCmd.Short = prependExperimental(listCmd.Short)
-	listCmd.Long = bpRegistryExplanation + "List Registries saved in the pack config.\n\nShow the registries that are either added by default or have been explicitly added by using `pack config registries add`"
-	cmd.AddCommand(listCmd)
-
 	cmd.AddCommand(ConfigRegistriesDefault(logger, cfg, cfgPath))
 
 	AddHelpFlag(cmd, "registries")

internal/commands/config_registries_test.go

@@ -78,7 +78,6 @@ func testConfigRegistries(t *testing.T, when spec.G, it spec.S) {
 			cmd.SetArgs([]string{"-h"})
 			assert.Nil(cmd.Execute())
 			output := outBuf.String()
-			assert.Contains(output, "Interact with registries")
 			assert.Contains(output, "Usage:")
 			for _, command := range []string{"add", "remove", "list", "default"} {
 				assert.Contains(output, command)

internal/commands/config_run_image_mirrors.go

@@ -19,14 +19,20 @@ var mirrors []string
 func ConfigRunImagesMirrors(logger logging.Logger, cfg config.Config, cfgPath string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run-image-mirrors",
-		Short: "Interact with run image mirrors",
+		Short: "List, add and remove run image mirrors",
 		Args:  cobra.MaximumNArgs(3),
 		RunE: logError(logger, func(cmd *cobra.Command, args []string) error {
 			listRunImageMirror(args, logger, cfg)
 			return nil
 		}),
 	}
 
+	listCmd := generateListCmd(cmd.Use, logger, cfg, listRunImageMirror)
+	listCmd.Long = "List all run image mirrors. If a run image is provided, it will return "
+	listCmd.Use = "list [<run-image>]"
+	listCmd.Example = "pack config run-image-mirrors list"
+	cmd.AddCommand(listCmd)
+
 	addCmd := generateAdd("mirror for a run image", logger, cfg, cfgPath, addRunImageMirror)
 	addCmd.Use = "add <image> [-m <mirror...]"
 	addCmd.Long = "Set mirrors to other repositories for a given run image"
@@ -42,12 +48,6 @@ func ConfigRunImagesMirrors(logger logging.Logger, cfg config.Config, cfgPath st
 	rmCmd.Flags().StringSliceVarP(&mirrors, "mirror", "m", nil, "Run image mirror"+multiValueHelp("mirror"))
 	cmd.AddCommand(rmCmd)
 
-	listCmd := generateListCmd(cmd.Use, logger, cfg, listRunImageMirror)
-	listCmd.Long = "List all run image mirrors. If a run image is provided, it will return "
-	listCmd.Use = "list [<run-image>]"
-	listCmd.Example = "pack config run-image-mirrors list"
-	cmd.AddCommand(listCmd)
-
 	AddHelpFlag(cmd, "run-image-mirrors")
 	return cmd
 }

internal/commands/config_test.go

@@ -61,7 +61,6 @@ func testConfigCommand(t *testing.T, when spec.G, it spec.S) {
 			command.SetArgs([]string{})
 			h.AssertNil(t, command.Execute())
 			output := outBuf.String()
-			h.AssertContains(t, output, "Interact with Pack's configuration")
 			h.AssertContains(t, output, "Usage:")
 			for _, command := range []string{"trusted-builders", "run-image-mirrors", "default-builder", "experimental", "registries"} {
 				h.AssertContains(t, output, command)

internal/commands/config_trusted_builder.go

@@ -13,15 +13,25 @@ import (
 
 func ConfigTrustedBuilder(logger logging.Logger, cfg config.Config, cfgPath string) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "trusted-builders",
-		Short:   "Interact with trusted builders",
+		Use:   "trusted-builders",
+		Short: "List, add and remove trusted builders",
+		Long: "When pack considers a builder to be trusted, `pack build` operations will use a single lifecycle binary " +
+			"called the creator. This is more efficient than using an untrusted builder, where pack will execute " +
+			"five separate lifecycle binaries: detect, analyze, restore, build and export.\n\n" +
+			"For more on trusted builders, and when to trust or untrust a builder, " +
+			"check out our docs here: https://buildpacks.io/docs/tools/pack/concepts/trusted_builders/",
 		Aliases: []string{"trusted-builder", "trust-builder", "trust-builders"},
 		RunE: logError(logger, func(cmd *cobra.Command, args []string) error {
 			listTrustedBuilders(args, logger, cfg)
 			return nil
 		}),
 	}
 
+	listCmd := generateListCmd("trusted-builders", logger, cfg, listTrustedBuilders)
+	listCmd.Long = "List Trusted Builders.\n\nShow the builders that are either trusted by default or have been explicitly trusted locally using `trust-builder`"
+	listCmd.Example = "pack config trusted-builders list"
+	cmd.AddCommand(listCmd)
+
 	addCmd := generateAdd("trusted-builders", logger, cfg, cfgPath, addTrustedBuilder)
 	addCmd.Long = "Trust builder.\n\nWhen building with this builder, all lifecycle phases will be run in a single container using the builder image."
 	addCmd.Example = "pack config trusted-builders add cnbs/sample-stack-run:bionic"
@@ -32,11 +42,6 @@ func ConfigTrustedBuilder(logger logging.Logger, cfg config.Config, cfgPath stri
 	rmCmd.Example = "pack config trusted-builders remove cnbs/sample-stack-run:bionic"
 	cmd.AddCommand(rmCmd)
 
-	listCmd := generateListCmd("trusted-builders", logger, cfg, listTrustedBuilders)
-	listCmd.Long = "List Trusted Builders.\n\nShow the builders that are either trusted by default or have been explicitly trusted locally using `trust-builder`"
-	listCmd.Example = "pack config trusted-builders list"
-	cmd.AddCommand(listCmd)
-
 	AddHelpFlag(cmd, "trusted-builders")
 	return cmd
 }

internal/commands/stack.go

@@ -9,7 +9,7 @@ import (
 func NewStackCommand(logger logging.Logger) *cobra.Command {
 	command := cobra.Command{
 		Use:   "stack",
-		Short: "Displays stack information",
+		Short: "Interact with stacks",
 		RunE:  nil,
 	}
 

internal/commands/stack_suggest.go

@@ -53,7 +53,7 @@ func stackSuggest(logger logging.Logger) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "suggest",
 		Args:    cobra.NoArgs,
-		Short:   "Display list of recommended stacks",
+		Short:   "List the recommended stacks",
 		Example: "pack stacks suggest",
 		RunE: logError(logger, func(*cobra.Command, []string) error {
 			Suggest(logger)