update usage strings for consistency

This updates the format of various usage strings to be more consistent
with other parts of the CLI.

- Use `[OPTIONS]` to indicate where command-specific options should be added
- Use `[SERVICE...]` to indicate zero-or-more services
- Remove some usage strings for specific options (e.g. `-e NAME=VAL`), as that
  option is part of the already mentioned `[OPTIONS]` and we don't provide usage
  for each possible option that can be passed.
- Remove `[--]`, which (I think) was needed for the Python implementation, but is
  a general feature to stop processing flag-options.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

cmd/compose/build.go

@@ -77,7 +77,7 @@ func buildCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	cmd := &cobra.Command{
-		Use:   "build [SERVICE...]",
+		Use:   "build [OPTIONS] [SERVICE...]",
 		Short: "Build or rebuild services",
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {
 			if opts.memory != "" {

cmd/compose/convert.go

@@ -58,7 +58,7 @@ func convertCommand(p *projectOptions, backend api.Service) *cobra.Command {
 	}
 	cmd := &cobra.Command{
 		Aliases: []string{"config"},
-		Use:     "convert SERVICES",
+		Use:     "convert [OPTIONS] [SERVICE...]",
 		Short:   "Converts the compose file to platform's canonical format",
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {
 			if opts.quiet {

cmd/compose/create.go

@@ -45,7 +45,7 @@ type createOptions struct {
 func createCommand(p *projectOptions, backend api.Service) *cobra.Command {
 	opts := createOptions{}
 	cmd := &cobra.Command{
-		Use:   "create [SERVICE...]",
+		Use:   "create [OPTIONS] [SERVICE...]",
 		Short: "Creates containers for a service.",
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {
 			if opts.Build && opts.noBuild {

cmd/compose/down.go

@@ -45,7 +45,7 @@ func downCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	downCmd := &cobra.Command{
-		Use:   "down",
+		Use:   "down [OPTIONS]",
 		Short: "Stop and remove containers, networks",
 		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
 			opts.timeChanged = cmd.Flags().Changed("timeout")

cmd/compose/events.go

@@ -38,7 +38,7 @@ func eventsCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		},
 	}
 	cmd := &cobra.Command{
-		Use:   "events [options] [--] [SERVICE...]",
+		Use:   "events [OPTIONS] [SERVICE...]",
 		Short: "Receive real time events from containers.",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runEvents(ctx, backend, opts, args)

cmd/compose/exec.go

@@ -50,7 +50,7 @@ func execCommand(p *projectOptions, dockerCli command.Cli, backend api.Service)
 		},
 	}
 	runCmd := &cobra.Command{
-		Use:   "exec [options] [-e KEY=VAL...] [--] SERVICE COMMAND [ARGS...]",
+		Use:   "exec [OPTIONS] SERVICE COMMAND [ARGS...]",
 		Short: "Execute a command in a running container.",
 		Args:  cobra.MinimumNArgs(2),
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {

cmd/compose/images.go

@@ -43,7 +43,7 @@ func imagesCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	imgCmd := &cobra.Command{
-		Use:   "images [SERVICE...]",
+		Use:   "images [OPTIONS] [SERVICE...]",
 		Short: "List images used by the created containers",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runImages(ctx, backend, opts, args)

cmd/compose/kill.go

@@ -34,7 +34,7 @@ func killCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	cmd := &cobra.Command{
-		Use:   "kill [options] [SERVICE...]",
+		Use:   "kill [OPTIONS] [SERVICE...]",
 		Short: "Force stop service containers.",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runKill(ctx, backend, opts, args)

cmd/compose/list.go

@@ -41,7 +41,7 @@ type lsOptions struct {
 func listCommand(backend api.Service) *cobra.Command {
 	lsOpts := lsOptions{Filter: opts.NewFilterOpt()}
 	lsCmd := &cobra.Command{
-		Use:   "ls",
+		Use:   "ls [OPTIONS]",
 		Short: "List running compose projects",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runList(ctx, backend, lsOpts)

cmd/compose/logs.go

@@ -44,7 +44,7 @@ func logsCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	logsCmd := &cobra.Command{
-		Use:   "logs [SERVICE...]",
+		Use:   "logs [OPTIONS] [SERVICE...]",
 		Short: "View output from containers",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runLogs(ctx, backend, opts, args)

cmd/compose/port.go

@@ -38,7 +38,7 @@ func portCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	cmd := &cobra.Command{
-		Use:   "port [options] [--] SERVICE PRIVATE_PORT",
+		Use:   "port [OPTIONS] SERVICE PRIVATE_PORT",
 		Short: "Print the public port for a port binding.",
 		Args:  cobra.MinimumNArgs(2),
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {

cmd/compose/ps.go

@@ -70,7 +70,7 @@ func psCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	psCmd := &cobra.Command{
-		Use:   "ps [SERVICE...]",
+		Use:   "ps [OPTIONS] [SERVICE...]",
 		Short: "List containers",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			return opts.parseFilter()

cmd/compose/pull.go

@@ -43,7 +43,7 @@ func pullCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	cmd := &cobra.Command{
-		Use:   "pull [SERVICE...]",
+		Use:   "pull [OPTIONS] [SERVICE...]",
 		Short: "Pull service images",
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {
 			if opts.noParallel {

cmd/compose/push.go

@@ -36,7 +36,7 @@ func pushCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	pushCmd := &cobra.Command{
-		Use:   "push [SERVICE...]",
+		Use:   "push [OPTIONS] [SERVICE...]",
 		Short: "Push service images",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runPush(ctx, backend, opts, args)

cmd/compose/remove.go

@@ -35,7 +35,7 @@ func removeCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	cmd := &cobra.Command{
-		Use:   "rm [SERVICE...]",
+		Use:   "rm [OPTIONS] [SERVICE...]",
 		Short: "Removes stopped service containers",
 		Long: `Removes stopped service containers
 

cmd/compose/restart.go

@@ -35,7 +35,7 @@ func restartCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	restartCmd := &cobra.Command{
-		Use:   "restart [SERVICE...]",
+		Use:   "restart [OPTIONS] [SERVICE...]",
 		Short: "Restart service containers",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runRestart(ctx, backend, opts, args)

cmd/compose/run.go

@@ -114,7 +114,7 @@ func runCommand(p *projectOptions, dockerCli command.Cli, backend api.Service) *
 		},
 	}
 	cmd := &cobra.Command{
-		Use:   "run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...] SERVICE [COMMAND] [ARGS...]",
+		Use:   "run [OPTIONS] SERVICE [COMMAND] [ARGS...]",
 		Short: "Run a one-off command on a service.",
 		Args:  cobra.MinimumNArgs(1),
 		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {

cmd/compose/stop.go

@@ -36,7 +36,7 @@ func stopCommand(p *projectOptions, backend api.Service) *cobra.Command {
 		projectOptions: p,
 	}
 	cmd := &cobra.Command{
-		Use:   "stop [SERVICE...]",
+		Use:   "stop [OPTIONS] [SERVICE...]",
 		Short: "Stop services",
 		PreRun: func(cmd *cobra.Command, args []string) {
 			opts.timeChanged = cmd.Flags().Changed("timeout")

cmd/compose/up.go

@@ -96,7 +96,7 @@ func upCommand(p *projectOptions, backend api.Service) *cobra.Command {
 	up := upOptions{}
 	create := createOptions{}
 	upCmd := &cobra.Command{
-		Use:   "up [SERVICE...]",
+		Use:   "up [OPTIONS] [SERVICE...]",
 		Short: "Create and start containers",
 		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
 			create.timeChanged = cmd.Flags().Changed("timeout")

cmd/compose/version.go

@@ -35,7 +35,7 @@ type versionOptions struct {
 func versionCommand() *cobra.Command {
 	opts := versionOptions{}
 	cmd := &cobra.Command{
-		Use:   "version",
+		Use:   "version [OPTIONS]",
 		Short: "Show the Docker Compose version information",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {

docs/reference/docker_compose_build.yaml

@@ -10,7 +10,7 @@ long: |-
 
     If you change a service's `Dockerfile` or the contents of its build directory,
     run `docker compose build` to rebuild it.
-usage: docker compose build [SERVICE...]
+usage: docker compose build [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_convert.yaml

@@ -7,7 +7,7 @@ long: |-
     fully defined Compose model.
 
     To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`
-usage: docker compose convert SERVICES
+usage: docker compose convert [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_create.yaml

@@ -1,7 +1,7 @@
 command: docker compose create
 short: Creates containers for a service.
 long: Creates containers for a service.
-usage: docker compose create [SERVICE...]
+usage: docker compose create [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_down.yaml

@@ -14,7 +14,7 @@ long: |-
     Anonymous volumes are not removed by default. However, as they don’t have a stable name, they will not be automatically
     mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or
     named volumes.
-usage: docker compose down
+usage: docker compose down [OPTIONS]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_events.yaml

@@ -20,7 +20,7 @@ long: |-
     ```
 
     The events that can be received using this can be seen [here](/engine/reference/commandline/events/#object-types).
-usage: docker compose events [options] [--] [SERVICE...]
+usage: docker compose events [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_exec.yaml

@@ -5,7 +5,7 @@ long: |-
 
     With this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so
     you can use a command such as `docker compose exec web sh` to get an interactive prompt.
-usage: docker compose exec [options] [-e KEY=VAL...] [--] SERVICE COMMAND [ARGS...]
+usage: docker compose exec [OPTIONS] SERVICE COMMAND [ARGS...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_images.yaml

@@ -1,7 +1,7 @@
 command: docker compose images
 short: List images used by the created containers
 long: List images used by the created containers
-usage: docker compose images [SERVICE...]
+usage: docker compose images [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_kill.yaml

@@ -6,7 +6,7 @@ long: |-
     ```console
     $ docker-compose kill -s SIGINT
     ```
-usage: docker compose kill [options] [SERVICE...]
+usage: docker compose kill [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_logs.yaml

@@ -1,7 +1,7 @@
 command: docker compose logs
 short: View output from containers
 long: Displays log output from services.
-usage: docker compose logs [SERVICE...]
+usage: docker compose logs [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_ls.yaml

@@ -1,7 +1,7 @@
 command: docker compose ls
 short: List running compose projects
 long: List Compose projects running on platform.
-usage: docker compose ls
+usage: docker compose ls [OPTIONS]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_port.yaml

@@ -1,7 +1,7 @@
 command: docker compose port
 short: Print the public port for a port binding.
 long: Prints the public port for a port binding.
-usage: docker compose port [options] [--] SERVICE PRIVATE_PORT
+usage: docker compose port [OPTIONS] SERVICE PRIVATE_PORT
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_ps.yaml

@@ -10,7 +10,7 @@ long: |-
     example-bar-1  "/docker-entrypoint.…"   bar       exited (0)
     example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->80/tcp
     ```
-usage: docker compose ps [SERVICE...]
+usage: docker compose ps [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_pull.yaml

@@ -3,7 +3,7 @@ short: Pull service images
 long: |-
     Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on
     those images.
-usage: docker compose pull [SERVICE...]
+usage: docker compose pull [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_push.yaml

@@ -19,7 +19,7 @@ long: |-
         build: .
         image: your-dockerid/yourimage  ## goes to your repository on Docker Hub
     ```
-usage: docker compose push [SERVICE...]
+usage: docker compose push [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_restart.yaml

@@ -11,7 +11,7 @@ long: |-
     If you are looking to configure a service's restart policy, please refer to
     [restart](https://github.com/compose-spec/compose-spec/blob/master/spec.md#restart)
     or [restart_policy](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#restart_policy).
-usage: docker compose restart [SERVICE...]
+usage: docker compose restart [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_rm.yaml

@@ -16,7 +16,7 @@ long: |-
     Are you sure? [yN] y
     Removing djangoquickstart_web_run_1 ... done
     ```
-usage: docker compose rm [SERVICE...]
+usage: docker compose rm [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_run.yaml

@@ -54,7 +54,7 @@ long: |-
 
     This runs a database upgrade script, and removes the container when finished running, even if a restart policy is
     specified in the service configuration.
-usage: docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
+usage: docker compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_stop.yaml

@@ -2,7 +2,7 @@ command: docker compose stop
 short: Stop services
 long: |
     Stops running containers without removing them. They can be started again with `docker compose start`.
-usage: docker compose stop [SERVICE...]
+usage: docker compose stop [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_up.yaml

@@ -17,7 +17,7 @@ long: |-
 
     If the process encounters an error, the exit code for this command is `1`.
     If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`.
-usage: docker compose up [SERVICE...]
+usage: docker compose up [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

docs/reference/docker_compose_version.yaml

@@ -1,7 +1,7 @@
 command: docker compose version
 short: Show the Docker Compose version information
 long: Show the Docker Compose version information
-usage: docker compose version
+usage: docker compose version [OPTIONS]
 pname: docker compose
 plink: docker_compose.yaml
 options:

pkg/compose/hash.go

@@ -23,7 +23,7 @@ import (
 	"github.com/opencontainers/go-digest"
 )
 
-// ServiceHash compute configuration has for a service
+// ServiceHash computes the configuration hash for a service.
 func ServiceHash(o types.ServiceConfig) (string, error) {
 	// remove the Build config when generating the service hash
 	o.Build = nil