From 15a6d25b687e06b1d152b57d11b408da46158bf7 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Tue, 28 Jun 2022 12:15:19 +0200
Subject: [PATCH] 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.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 clidocstool.go                    | 8 ++++++++
 clidocstool_test.go               | 3 +++
 fixtures/buildx_build.md          | 2 +-
 fixtures/docker_buildx_build.yaml | 2 +-
 4 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/clidocstool.go b/clidocstool.go
index 7f1b8a0..d4aeaba 100644
--- a/clidocstool.go
+++ b/clidocstool.go
@@ -18,6 +18,7 @@ import (
 	"errors"
 	"io"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 )
@@ -99,6 +100,13 @@ func copyFile(src string, dst string) error {
 }
 
 func getAliases(cmd *cobra.Command) []string {
+	if a := cmd.Annotations["aliases"]; a != "" {
+		aliases := strings.Split(a, ",")
+		for i := 0; i < len(aliases); i++ {
+			aliases[i] = strings.TrimSpace(aliases[i])
+		}
+		return aliases
+	}
 	if len(cmd.Aliases) == 0 {
 		return cmd.Aliases
 	}
diff --git a/clidocstool_test.go b/clidocstool_test.go
index 2c50733..6d9e4a5 100644
--- a/clidocstool_test.go
+++ b/clidocstool_test.go
@@ -58,6 +58,9 @@ func init() {
 		Aliases: []string{"b"},
 		Short:   "Start a build",
 		Run:     func(cmd *cobra.Command, args []string) {},
+		Annotations: map[string]string{
+			"aliases": "docker image build, docker buildx build, docker buildx b, docker build",
+		},
 	}
 	buildxStopCmd = &cobra.Command{
 		Use:   "stop [NAME]",
diff --git a/fixtures/buildx_build.md b/fixtures/buildx_build.md
index 7248112..1cf0c40 100644
--- a/fixtures/buildx_build.md
+++ b/fixtures/buildx_build.md
@@ -5,7 +5,7 @@ Start a build
 
 ### Aliases
 
-`docker buildx build`, `docker buildx b`
+`docker image build`, `docker buildx build`, `docker buildx b`, `docker build`
 
 ### Options
 
diff --git a/fixtures/docker_buildx_build.yaml b/fixtures/docker_buildx_build.yaml
index 049c831..dfc6b61 100644
--- a/fixtures/docker_buildx_build.yaml
+++ b/fixtures/docker_buildx_build.yaml
@@ -1,5 +1,5 @@
 command: docker buildx build
-aliases: docker buildx build, docker buildx b
+aliases: docker image build, docker buildx build, docker buildx b, docker build
 short: Start a build
 long: Start a build
 usage: docker buildx build [OPTIONS] PATH | URL | -