Merge pull request #704 from carolinebriaud/fix-usages-examples

silvin-lubecki · web-flow · commit 6e215e76fb62 · 2019-10-24T21:35:49.000+02:00
Consistent object naming in usage command and examples
diff --git a/e2e/commands_test.go b/e2e/commands_test.go
@@ -190,7 +190,7 @@ func TestRunOnlyOne(t *testing.T) {
 	cmd.Command = dockerCli.Command("app", "run", "--cnab-bundle-json", "bundle.json", "myapp")
 	icmd.RunCmd(cmd).Assert(t, icmd.Expected{
 		ExitCode: 1,
-		Err:      `"docker app run" cannot run a bundle and an app image`,
+		Err:      `"docker app run" cannot run a bundle and an App image`,
 	})
 }
 
@@ -238,7 +238,7 @@ func testDockerAppLifecycle(t *testing.T, useBindMount bool) {
 	cmd.Command = dockerCli.Command("app", "update", appName)
 	icmd.RunCmd(cmd).Assert(t, icmd.Expected{
 		ExitCode: 1,
-		Err:      fmt.Sprintf("Installation %q has failed and cannot be updated, reinstall it using 'docker app install'", appName),
+		Err:      fmt.Sprintf("Installation %q has failed and cannot be updated, reinstall it using 'docker app run'", appName),
 	})
 
 	// Install a Docker Application Package with an existing failed installation is fine
diff --git a/e2e/plugin_test.go b/e2e/plugin_test.go
@@ -15,7 +15,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
 	// docker --help should list app as a top command
 	cmd.Command = dockerCli.Command("--help")
 	icmd.RunCmd(cmd).Assert(t, icmd.Expected{
-		Out: "app*        Docker Application (Docker Inc.,",
+		Out: "app*        Docker App (Docker Inc.,",
 	})
 
 	// docker app --help prints docker-app help
@@ -27,7 +27,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
 
 	// docker info should print app version and short description
 	cmd.Command = dockerCli.Command("info")
-	re := regexp.MustCompile(`app: Docker Application \(Docker Inc\., .*\)`)
+	re := regexp.MustCompile(`app: Docker App \(Docker Inc\., .*\)`)
 	output := icmd.RunCmd(cmd).Assert(t, icmd.Success).Combined()
 	assert.Assert(t, re.MatchString(output))
 }
diff --git a/e2e/testdata/plugin-usage.golden b/e2e/testdata/plugin-usage.golden
@@ -1,23 +1,23 @@
 
 Usage:	docker app [OPTIONS] COMMAND
 
-A tool to build and manage Docker Applications.
+A tool to build, share and run a Docker App
 
 Options:
       --version   Print version information
 
 Management Commands:
-  image       Manage application images
+  image       Manage App images
 
 Commands:
-  build       Build service images for the application
-  init        Initialize Docker Application definition
-  ls          List the installations and their last known installation result
-  pull        Pull an application package from a registry
-  push        Push an application package to a registry
-  rm          Remove an application
-  run         Run an application
-  update      Update a running application
-  validate    Checks the rendered application is syntactically correct
+  build       Build an App image from an App definition (.dockerapp)
+  init        Initialize an App definition
+  ls          List running Apps
+  pull        Pull an App image from a registry
+  push        Push an App image to a registry
+  rm          Remove a running App
+  run         Run an App from an App image
+  update      Update a running App
+  validate    Check that an App definition (.dockerapp) is syntactically correct
 
 Run 'docker app COMMAND --help' for more information on a command.
diff --git a/internal/commands/build/build.go b/internal/commands/build/build.go
@@ -45,24 +45,25 @@ type buildOptions struct {
 func Cmd(dockerCli command.Cli) *cobra.Command {
 	var opts buildOptions
 	cmd := &cobra.Command{
-		Use:     "build [OPTIONS] [CONTEXT_PATH]",
-		Short:   "Build service images for the application",
-		Example: `$ docker app build --tag my/app:1.0.0 .`,
-		Args:    cli.ExactArgs(1),
+		Use:   "build [OPTIONS] [BUILD_PATH]",
+		Short: "Build an App image from an App definition (.dockerapp)",
+		Example: `$ docker app build .
+$ docker app build . -f myapp.dockerapp -t myrepo/myapp:1.0.0`,
+		Args: cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runBuild(dockerCli, args[0], opts)
 		},
 	}
 
 	flags := cmd.Flags()
-	flags.BoolVar(&opts.noCache, "no-cache", false, "Do not use cache when building the image")
+	flags.BoolVar(&opts.noCache, "no-cache", false, "Do not use cache when building the App image")
 	flags.StringVar(&opts.progress, "progress", "auto", "Set type of progress output (auto, plain, tty). Use plain to show container output")
-	flags.StringVarP(&opts.tag, "tag", "t", "", "Application image and optionally a tag in the 'image:tag' format")
-	flags.StringVarP(&opts.folder, "folder", "f", "", "Docker app folder containing application definition")
-	flags.BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the image")
+	flags.StringVarP(&opts.tag, "tag", "t", "", "App image tag, optionally in the 'repo:tag' format")
+	flags.StringVarP(&opts.folder, "folder", "f", "", "App definition as a .dockerapp directory")
+	flags.BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the App image")
 	flags.StringArrayVar(&opts.args, "build-arg", []string{}, "Set build-time variables")
-	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress the build output and print app image ID on success")
-	flags.StringVar(&opts.imageIDFile, "iidfile", "", "Write the app image ID to the file")
+	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress the build output and print App image ID on success")
+	flags.StringVar(&opts.imageIDFile, "iidfile", "", "Write the App image ID to the file")
 
 	return cmd
 }
@@ -190,7 +191,7 @@ func getAppFolder(opt buildOptions, contextPath string) (string, error) {
 		for _, f := range files {
 			if strings.HasSuffix(f.Name(), ".dockerapp") {
 				if application != "" {
-					return "", fmt.Errorf("%s contains multiple *.dockerapp folders, use -f option to select the one to build", contextPath)
+					return "", fmt.Errorf("%s contains multiple .dockerapp directories, use -f option to select the one to build", contextPath)
 				}
 				application = filepath.Join(contextPath, f.Name())
 				if !f.IsDir() {
diff --git a/internal/commands/image/command.go b/internal/commands/image/command.go
@@ -8,7 +8,7 @@ import (
 // Cmd is the image top level command
 func Cmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Short: "Manage application images",
+		Short: "Manage App images",
 		Use:   "image",
 	}
 
diff --git a/internal/commands/image/inspect.go b/internal/commands/image/inspect.go
@@ -30,16 +30,18 @@ func muteDockerCli(dockerCli command.Cli) func() {
 func inspectCmd(dockerCli command.Cli) *cobra.Command {
 	var opts inspectOptions
 	cmd := &cobra.Command{
-		Use:   "inspect [APP_NAME] [OPTIONS]",
-		Short: "Shows metadata, parameters and a summary of the Compose file for a given application",
-		Example: `$ docker app inspect my-installed-app
-$docker app inspect my-app:1.0.0`,
+		Use:   "inspect [OPTIONS] APP_IMAGE",
+		Short: "Display detailed information about an App image",
+		Example: `$ docker app image inspect myapp
+$ docker app image inspect myapp:1.0.0
+$ docker app image inspect myrepo/myapp:1.0.0
+$ docker app image inspect 34be4a0c5f50`,
 		Args: cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInspect(dockerCli, args[0], opts)
 		},
 	}
-	cmd.Flags().BoolVar(&opts.pretty, "pretty", false, "Pretty print the output")
+	cmd.Flags().BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format")
 
 	return cmd
 }
diff --git a/internal/commands/image/list.go b/internal/commands/image/list.go
@@ -23,7 +23,7 @@ type imageListOption struct {
 func listCmd(dockerCli command.Cli) *cobra.Command {
 	options := imageListOption{}
 	cmd := &cobra.Command{
-		Short:   "List application images",
+		Short:   "List App images",
 		Use:     "ls",
 		Aliases: []string{"list"},
 		RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/image/rm.go b/internal/commands/image/rm.go
@@ -14,13 +14,14 @@ import (
 
 func rmCmd() *cobra.Command {
 	return &cobra.Command{
-		Short:   "Remove an application image",
-		Use:     "rm [APP_IMAGE] [APP_IMAGE...]",
+		Short:   "Remove an App image",
+		Use:     "rm APP_IMAGE [APP_IMAGE...]",
 		Aliases: []string{"remove"},
 		Args:    cli.RequiresMinArgs(1),
 		Example: `$ docker app image rm myapp
 $ docker app image rm myapp:1.0.0
-$ docker app image rm docker.io/library/myapp@sha256:beef...`,
+$ docker app image rm myrepo/myapp@sha256:c0de...
+$ docker app image rm 34be4a0c5f50`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appstore, err := store.NewApplicationStore(config.Dir())
 			if err != nil {
diff --git a/internal/commands/image/tag.go b/internal/commands/image/tag.go
@@ -12,9 +12,12 @@ import (
 
 func tagCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Short: "Create a new tag from an application image",
+		Short: "Create a new tag from an App image",
 		Use:   "tag SOURCE_APP_IMAGE[:TAG] TARGET_APP_IMAGE[:TAG]",
-		Args:  cli.ExactArgs(2),
+		Example: `$ docker app image tag myapp myrepo/myapp:mytag
+$ docker app image tag myapp:tag myrepo/mynewapp:mytag
+$ docker app image tag 34be4a0c5f50 myrepo/mynewapp:mytag`,
+		Args: cli.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appstore, err := store.NewApplicationStore(config.Dir())
 			if err != nil {
diff --git a/internal/commands/init.go b/internal/commands/init.go
@@ -15,11 +15,11 @@ var (
 
 func initCmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "init APP_NAME [--compose-file COMPOSE_FILE] [OPTIONS]",
-		Short:   "Initialize Docker Application definition",
-		Long:    `Start building a Docker Application package.`,
-		Example: `$ docker app init myapp`,
-		Args:    cli.ExactArgs(1),
+		Use:   "init [OPTIONS] APP_DEFINITION",
+		Short: "Initialize an App definition",
+		Example: `$ docker app init myapp
+$ docker app init myapp --compose-file docker-compose.yml`,
+		Args: cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			created, err := packager.Init(args[0], initComposeFile)
 			if err != nil {
@@ -29,6 +29,6 @@ func initCmd(dockerCli command.Cli) *cobra.Command {
 			return nil
 		},
 	}
-	cmd.Flags().StringVar(&initComposeFile, "compose-file", "", "Compose file to use as application base (optional)")
+	cmd.Flags().StringVar(&initComposeFile, "compose-file", "", "Compose file to use to bootstrap a Docker App definition")
 	return cmd
 }
diff --git a/internal/commands/list.go b/internal/commands/list.go
@@ -44,14 +44,14 @@ func listCmd(dockerCli command.Cli) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "ls [OPTIONS]",
-		Short:   "List the installations and their last known installation result",
+		Short:   "List running Apps",
 		Aliases: []string{"list"},
 		Args:    cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runList(dockerCli, opts)
 		},
 	}
-	cmd.Flags().StringVar(&opts.targetContext, "target-context", "", "List installations on this context")
+	cmd.Flags().StringVar(&opts.targetContext, "target-context", "", "List running Apps on this context")
 
 	return cmd
 }
diff --git a/internal/commands/pull.go b/internal/commands/pull.go
@@ -16,9 +16,9 @@ import (
 
 func pullCmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "pull NAME:TAG [OPTIONS]",
-		Short:   "Pull an application package from a registry",
-		Example: `$ docker app pull docker/app-example:0.1.0`,
+		Use:     "pull APP_IMAGE",
+		Short:   "Pull an App image from a registry",
+		Example: `$ docker app pull myrepo/myapp:0.1.0`,
 		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runPull(dockerCli, args[0])
diff --git a/internal/commands/push.go b/internal/commands/push.go
@@ -53,8 +53,8 @@ type pushOptions struct {
 func pushCmd(dockerCli command.Cli) *cobra.Command {
 	var opts pushOptions
 	cmd := &cobra.Command{
-		Use:     "push [APP_NAME] --tag TARGET_REFERENCE [OPTIONS]",
-		Short:   "Push an application package to a registry",
+		Use:     "push [OPTIONS] APP_IMAGE",
+		Short:   "Push an App image to a registry",
 		Example: `$ docker app push myapp --tag myrepo/myapp:mytag`,
 		Args:    cli.RequiresMaxArgs(1),
 		PreRunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/remove.go b/internal/commands/remove.go
@@ -21,17 +21,17 @@ func removeCmd(dockerCli command.Cli) *cobra.Command {
 	var opts removeOptions
 
 	cmd := &cobra.Command{
-		Use:     "rm INSTALLATION_NAME [--target-context TARGET_CONTEXT] [OPTIONS]",
-		Short:   "Remove an application",
+		Use:     "rm [OPTIONS] RUNNING_APP",
+		Short:   "Remove a running App",
 		Aliases: []string{"remove"},
-		Example: `$ docker app rm myinstallation --target-context=mycontext`,
+		Example: `$ docker app rm myrunningapp`,
 		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runRemove(dockerCli, args[0], opts)
 		},
 	}
 	opts.addFlags(cmd.Flags())
-	cmd.Flags().BoolVar(&opts.force, "force", false, "Force removal of installation")
+	cmd.Flags().BoolVar(&opts.force, "force", false, "Force the removal of a running App")
 
 	return cmd
 }
diff --git a/internal/commands/render.go b/internal/commands/render.go
@@ -25,9 +25,9 @@ type renderOptions struct {
 func renderCmd(dockerCli command.Cli) *cobra.Command {
 	var opts renderOptions
 	cmd := &cobra.Command{
-		Use:     "render [APP_NAME] [--set KEY=VALUE ...] [--parameters-file PARAMETERS-FILE ...] [OPTIONS]",
-		Short:   "Render the Compose file for an Application Package",
-		Example: `$ docker app render myapp.dockerapp --set key=value`,
+		Use:     "render [OPTIONS] APP_IMAGE",
+		Short:   "Render the Compose file for an App image",
+		Example: `$ docker app render myrepo/myapp:1.0.0 --set key=value --parameters-file myparam.yml`,
 		Args:    cli.RequiresMaxArgs(1),
 		Hidden:  true,
 		RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/root.go b/internal/commands/root.go
@@ -24,8 +24,8 @@ var (
 // NewRootCmd returns the base root command.
 func NewRootCmd(use string, dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Short:       "Docker Application",
-		Long:        `A tool to build and manage Docker Applications.`,
+		Short:       "Docker App",
+		Long:        `A tool to build, share and run a Docker App`,
 		Use:         use,
 		Annotations: map[string]string{"experimentalCLI": "true"},
 		RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/run.go b/internal/commands/run.go
@@ -27,23 +27,24 @@ type runOptions struct {
 	cnabBundle    string
 }
 
-const longDescription = `Run an application based on a docker app image.`
+const longDescription = `Run an App from an App image.`
 
-const example = `$ docker app run --name myinstallation --target-context=mycontext myrepo/myapp:mytag`
+const example = `$ docker app run --name myrunningapp myrepo/myapp:mytag
+$ docker app run 34be4a0c5f50 --name myrunningapp`
 
 func runCmd(dockerCli command.Cli) *cobra.Command {
 	var opts runOptions
 
 	cmd := &cobra.Command{
-		Use:     "run [OPTIONS] [APP_IMAGE]",
+		Use:     "run [OPTIONS] APP_IMAGE",
 		Aliases: []string{"deploy"},
-		Short:   "Run an application",
+		Short:   "Run an App from an App image",
 		Long:    longDescription,
 		Example: example,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if opts.cnabBundle != "" && len(args) != 0 {
 				return errors.Errorf(
-					"%q cannot run a bundle and an app image",
+					"%q cannot run a bundle and an App image",
 					cmd.CommandPath(),
 				)
 			}
@@ -58,10 +59,10 @@ func runCmd(dockerCli command.Cli) *cobra.Command {
 	}
 	opts.parametersOptions.addFlags(cmd.Flags())
 	opts.credentialOptions.addFlags(cmd.Flags())
-	cmd.Flags().StringVar(&opts.orchestrator, "orchestrator", "", "Orchestrator to install on (swarm, kubernetes)")
-	cmd.Flags().StringVar(&opts.kubeNamespace, "namespace", "default", "Kubernetes namespace to install into")
-	cmd.Flags().StringVar(&opts.stackName, "name", "", "Assign a name to the installation")
-	cmd.Flags().StringVar(&opts.cnabBundle, "cnab-bundle-json", "", "Run a CNAB bundle instead of a Docker App")
+	cmd.Flags().StringVar(&opts.orchestrator, "orchestrator", "", "Orchestrator to run on (swarm, kubernetes)")
+	cmd.Flags().StringVar(&opts.kubeNamespace, "namespace", "default", "Kubernetes namespace in which to run the App")
+	cmd.Flags().StringVar(&opts.stackName, "name", "", "Name of the running App")
+	cmd.Flags().StringVar(&opts.cnabBundle, "cnab-bundle-json", "", "Run a CNAB bundle instead of a Docker App image")
 
 	return cmd
 }
diff --git a/internal/commands/update.go b/internal/commands/update.go
@@ -21,16 +21,16 @@ func updateCmd(dockerCli command.Cli) *cobra.Command {
 	var opts updateOptions
 	cmd := &cobra.Command{
 		Use:     "update [OPTIONS] RUNNING_APP",
-		Short:   "Update a running application",
-		Example: `$ docker app update myrunningapp --target-context=mycontext --set key=value`,
+		Short:   "Update a running App",
+		Example: `$ docker app update myrunningapp --set key=value`,
 		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runUpdate(dockerCli, args[0], opts)
 		},
 	}
 	opts.parametersOptions.addFlags(cmd.Flags())
 	opts.credentialOptions.addFlags(cmd.Flags())
-	cmd.Flags().StringVar(&opts.bundleOrDockerApp, "image", "", "Override the installation with another Application Package")
+	cmd.Flags().StringVar(&opts.bundleOrDockerApp, "image", "", "Override the running App with another App image")
 
 	return cmd
 }
@@ -50,7 +50,7 @@ func runUpdate(dockerCli command.Cli, installationName string, opts updateOption
 	}
 
 	if isInstallationFailed(installation) {
-		return fmt.Errorf("Installation %q has failed and cannot be updated, reinstall it using 'docker app install'", installationName)
+		return fmt.Errorf("Installation %q has failed and cannot be updated, reinstall it using 'docker app run'", installationName)
 	}
 
 	if opts.bundleOrDockerApp != "" {
diff --git a/internal/commands/validate.go b/internal/commands/validate.go
@@ -19,9 +19,10 @@ type validateOptions struct {
 func validateCmd() *cobra.Command {
 	var opts validateOptions
 	cmd := &cobra.Command{
-		Use:   "validate [APP_NAME] [--set KEY=VALUE ...] [--parameters-file PARAMETERS_FILE]",
-		Short: "Checks the rendered application is syntactically correct",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "validate [OPTIONS] APP_DEFINITION",
+		Short:   "Check that an App definition (.dockerapp) is syntactically correct",
+		Example: `$ docker app validate myapp.dockerapp --set key=value --parameters-file myparam.yml`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			app, err := packager.Extract(firstOrEmpty(args),
 				types.WithParametersFiles(opts.parametersFiles...),

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ import (`
`8`	`8`	`// Cmd is the image top level command`
`9`	`9`	`func Cmd(dockerCli command.Cli) *cobra.Command {`
`10`	`10`	`cmd := &cobra.Command{`
`11`		`- Short: "Manage application images",`
	`11`	`+ Short: "Manage App images",`
`12`	`12`	`Use: "image",`
`13`	`13`	`}`
`14`	`14`