cli: use custom annotation for aliases

Cobra allows for aliases to be defined for a command, but only allows these
to be defined at the same level (for example, `docker image ls` as alias for
`docker image list`). Our CLI has some commands that are available both as a
top-level shorthand as well as `docker <object> <verb>` subcommands. For example,
`docker ps` is a shorthand for `docker container ps` / `docker container ls`.

This patch introduces a custom "aliases" annotation that can be used to print
all available aliases for a command. While this requires these aliases to be
defined manually, in practice the list of aliases rarely changes, so maintenance
should be minimal.

As a convention, we could consider the first command in this list to be the
canonical command, so that we can use this information to add redirects in
our documentation in future.

Before this patch:

    docker images --help

    Usage:  docker images [OPTIONS] [REPOSITORY[:TAG]]

    List images

    Options:
      -a, --all             Show all images (default hides intermediate images)
      ...

With this patch:

    docker images --help

    Usage:  docker images [OPTIONS] [REPOSITORY[:TAG]]

    List images

    Aliases:
      docker image ls, docker image list, docker images

    Options:
      -a, --all             Show all images (default hides intermediate images)
      ...

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

docs/reference/commandline/attach.md

@@ -11,6 +11,9 @@ Usage: docker attach [OPTIONS] CONTAINER
 
 Attach local standard input, output, and error streams to a running container
 
+Aliases:
+  docker container attach, docker attach
+
 Options:
       --detach-keys string   Override the key sequence for detaching a container
       --help                 Print usage

docs/reference/commandline/build.md

@@ -11,6 +11,9 @@ Usage:  docker build [OPTIONS] PATH | URL | -
 
 Build an image from a Dockerfile
 
+Aliases:
+  docker image build, docker build, docker buildx build, docker builder build
+
 Options:
       --add-host value          Add a custom host-to-IP mapping (host:ip) (default [])
       --build-arg value         Set build-time variables (default [])

docs/reference/commandline/commit.md

@@ -11,6 +11,9 @@ Usage:  docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
 
 Create a new image from a container's changes
 
+Aliases:
+  docker container commit, docker commit
+
 Options:
   -a, --author string    Author (e.g., "John Hannibal Smith <hannibal@a-team.com>")
   -c, --change value     Apply Dockerfile instruction to the created image (default [])

docs/reference/commandline/cp.md

@@ -17,6 +17,9 @@ and extract it to a directory destination in a container.
 Use '-' as the destination to stream a tar archive of a
 container source to stdout.
 
+Aliases:
+  docker container cp, docker cp
+
 Options:
   -L, --follow-link   Always follow symbol link in SRC_PATH
   -a, --archive       Archive mode (copy all uid/gid information)

docs/reference/commandline/create.md

@@ -13,6 +13,9 @@ Usage:  docker create [OPTIONS] IMAGE [COMMAND] [ARG...]
 
 Create a new container
 
+Aliases:
+  docker container create, docker create
+
 Options:
       --add-host value                Add a custom host-to-IP mapping (host:ip) (default [])
   -a, --attach value                  Attach to STDIN, STDOUT or STDERR (default [])

docs/reference/commandline/diff.md

@@ -11,6 +11,9 @@ Usage:  docker diff CONTAINER
 
 Inspect changes to files or directories on a container's filesystem
 
+Aliases:
+  docker container diff, docker diff
+
 Options:
       --help   Print usage
 ```

docs/reference/commandline/events.md

@@ -11,6 +11,9 @@ Usage:  docker events [OPTIONS]
 
 Get real time events from the server
 
+Aliases:
+  docker system events, docker events
+
 Options:
   -f, --filter value   Filter output based on conditions provided (default [])
       --format string  Format the output using the given Go template

docs/reference/commandline/exec.md

@@ -11,6 +11,9 @@ Usage:  docker exec [OPTIONS] CONTAINER COMMAND [ARG...]
 
 Execute a command in a running container
 
+Aliases:
+  docker container exec, docker exec
+
 Options:
   -d, --detach         Detached mode: run command in the background
       --detach-keys    Override the key sequence for detaching a container

docs/reference/commandline/export.md

@@ -11,6 +11,9 @@ Usage:  docker export [OPTIONS] CONTAINER
 
 Export a container's filesystem as a tar archive
 
+Aliases:
+  docker container export, docker export
+
 Options:
       --help            Print usage
   -o, --output string   Write to a file, instead of STDOUT

docs/reference/commandline/history.md

@@ -11,6 +11,9 @@ Usage:  docker history [OPTIONS] IMAGE
 
 Show the history of an image
 
+Aliases:
+  docker image history, docker history
+
 Options:
       --format string   Pretty-print images using a Go template
       --help            Print usage

docs/reference/commandline/images.md

@@ -11,6 +11,9 @@ Usage:  docker images [OPTIONS] [REPOSITORY[:TAG]]
 
 List images
 
+Aliases:
+  docker image ls, docker image list, docker images
+
 Options:
   -a, --all             Show all images (default hides intermediate images)
       --digests         Show digests

docs/reference/commandline/import.md

@@ -11,6 +11,9 @@ Usage:  docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]
 
 Import the contents from a tarball to create a filesystem image
 
+Aliases:
+  docker image import, docker import
+
 Options:
   -c, --change value     Apply Dockerfile instruction to the created image (default [])
       --help             Print usage

docs/reference/commandline/info.md

@@ -11,6 +11,9 @@ Usage:  docker info [OPTIONS]
 
 Display system-wide information
 
+Aliases:
+  docker system info, docker info
+
 Options:
   -f, --format string   Format the output using the given Go template
       --help            Print usage

docs/reference/commandline/kill.md

@@ -11,6 +11,9 @@ Usage:  docker kill [OPTIONS] CONTAINER [CONTAINER...]
 
 Kill one or more running containers
 
+Aliases:
+  docker container kill, docker kill
+
 Options:
       --help            Print usage
   -s, --signal string   Signal to send to the container

docs/reference/commandline/load.md

@@ -12,6 +12,9 @@ Usage:  docker load [OPTIONS]
 Load an image or repository from a tar archive (even if compressed with gzip,
 bzip2, or xz) from a file or STDIN.
 
+Aliases:
+  docker image load, docker load
+
 Options:
       --help           Print usage
   -i, --input string   Read from tar archive file, instead of STDIN.

docs/reference/commandline/logs.md

@@ -11,6 +11,9 @@ Usage:  docker logs [OPTIONS] CONTAINER
 
 Fetch the logs of a container
 
+Aliases:
+  docker container logs, docker logs
+
 Options:
       --details        Show extra details provided to logs
   -f, --follow         Follow log output

docs/reference/commandline/pause.md

@@ -11,6 +11,9 @@ Usage:  docker pause CONTAINER [CONTAINER...]
 
 Pause all processes within one or more containers
 
+Aliases:
+  docker container pause, docker pause
+
 Options:
       --help   Print usage
 ```

docs/reference/commandline/port.md

@@ -11,6 +11,9 @@ Usage:  docker port CONTAINER [PRIVATE_PORT[/PROTO]]
 
 List port mappings or a specific mapping for the container
 
+Aliases:
+  docker container port, docker port
+
 Options:
       --help   Print usage
 ```

docs/reference/commandline/ps.md

@@ -11,6 +11,9 @@ Usage: docker ps [OPTIONS]
 
 List containers
 
+Aliases:
+  docker container ls, docker container list, docker container ps, docker ps
+
 Options:
   -a, --all             Show all containers (default shows just running)
   -f, --filter value    Filter output based on conditions provided (default [])

docs/reference/commandline/pull.md

@@ -11,6 +11,9 @@ Usage:  docker pull [OPTIONS] NAME[:TAG|@DIGEST]
 
 Download an image from a registry
 
+Aliases:
+  docker image pull, docker pull
+
 Options:
   -a, --all-tags                Download all tagged images in the repository
       --disable-content-trust   Skip image verification (default true)

docs/reference/commandline/push.md

@@ -11,6 +11,9 @@ Usage:  docker push [OPTIONS] NAME[:TAG]
 
 Upload an image to a registry
 
+Aliases:
+  docker image push, docker push
+
 Options:
   -a, --all-tags                Push all tags of an image to the repository
       --disable-content-trust   Skip image signing (default true)

docs/reference/commandline/rename.md

@@ -11,6 +11,9 @@ Usage:  docker rename CONTAINER NEW_NAME
 
 Rename a container
 
+Aliases:
+  docker container rename, docker rename
+
 Options:
       --help   Print usage
 ```

docs/reference/commandline/restart.md

@@ -11,6 +11,9 @@ Usage:  docker restart [OPTIONS] CONTAINER [CONTAINER...]
 
 Restart one or more containers
 
+Aliases:
+  docker container restart, docker restart
+
 Options:
   -s, --signal string   Signal to send to the container
   -t, --time int        Seconds to wait before killing the container

docs/reference/commandline/rm.md

@@ -11,6 +11,9 @@ Usage:  docker rm [OPTIONS] CONTAINER [CONTAINER...]
 
 Remove one or more containers
 
+Aliases:
+  docker container rm, docker rm
+
 Options:
   -f, --force     Force the removal of a running container (uses SIGKILL)
       --help      Print usage

docs/reference/commandline/rmi.md

@@ -11,6 +11,9 @@ Usage:  docker rmi [OPTIONS] IMAGE [IMAGE...]
 
 Remove one or more images
 
+Aliases:
+  docker image rm, docker rmi
+
 Options:
   -f, --force      Force removal of the image
       --help       Print usage

docs/reference/commandline/run.md

@@ -11,6 +11,9 @@ Usage:  docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
 
 Create and run a new container from an image
 
+Aliases:
+  docker container run, docker run
+
 Options:
       --add-host value                Add a custom host-to-IP mapping (host:ip) (default [])
   -a, --attach value                  Attach to STDIN, STDOUT or STDERR (default [])

docs/reference/commandline/save.md

@@ -11,6 +11,9 @@ Usage:  docker save [OPTIONS] IMAGE [IMAGE...]
 
 Save one or more images to a tar archive (streamed to STDOUT by default)
 
+Aliases:
+  docker image save, docker save
+
 Options:
       --help            Print usage
   -o, --output string   Write to a file, instead of STDOUT

docs/reference/commandline/start.md

@@ -11,6 +11,9 @@ Usage:  docker start [OPTIONS] CONTAINER [CONTAINER...]
 
 Start one or more stopped containers
 
+Aliases:
+  docker container start, docker start
+
 Options:
   -a, --attach               Attach STDOUT/STDERR and forward signals
       --detach-keys string   Override the key sequence for detaching a container

docs/reference/commandline/stats.md

@@ -11,6 +11,9 @@ Usage:  docker stats [OPTIONS] [CONTAINER...]
 
 Display a live stream of container(s) resource usage statistics
 
+Aliases:
+  docker container stats, docker stats
+
 Options:
   -a, --all             Show all containers (default shows just running)
       --format string   Pretty-print images using a Go template

docs/reference/commandline/stop.md

@@ -11,6 +11,9 @@ Usage:  docker stop [OPTIONS] CONTAINER [CONTAINER...]
 
 Stop one or more running containers
 
+Aliases:
+  docker container stop, docker stop
+
 Options:
   -s, --signal string   Signal to send to the container
   -t, --time int        Seconds to wait before killing the container

docs/reference/commandline/tag.md

@@ -11,6 +11,9 @@ Usage:  docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
 
 Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
 
+Aliases:
+  docker image tag, docker tag
+
 Options:
       --help   Print usage
 ```

docs/reference/commandline/top.md

@@ -11,6 +11,9 @@ Usage:  docker top CONTAINER [ps OPTIONS]
 
 Display the running processes of a container
 
+Aliases:
+  docker container top, docker top
+
 Options:
       --help   Print usage
 ```

docs/reference/commandline/unpause.md

@@ -11,6 +11,9 @@ Usage:  docker unpause CONTAINER [CONTAINER...]
 
 Unpause all processes within one or more containers
 
+Aliases:
+  docker container unpause, docker unpause
+
 Options:
       --help   Print usage
 ```

docs/reference/commandline/update.md

@@ -11,6 +11,9 @@ Usage:  docker update [OPTIONS] CONTAINER [CONTAINER...]
 
 Update configuration of one or more containers
 
+Aliases:
+  docker container update, docker update
+
 Options:
       --blkio-weight uint16         Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)
       --cpu-period int              Limit CPU CFS (Completely Fair Scheduler) period

docs/reference/commandline/wait.md

@@ -11,6 +11,9 @@ Usage:  docker wait CONTAINER [CONTAINER...]
 
 Block until one or more containers stop, then print their exit codes
 
+Aliases:
+  docker container wait, docker wait
+
 Options:
       --help        Print usage
 ```