use custom annotation for aliases

thaJeztah · thaJeztah · commit 0f38acf7f6f9 · 2022-06-28T12:15:19.000+02:00
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 &lt;object&gt; &lt;verb&gt;` 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 &lt;github@gone.nl&gt;
diff --git 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
@@ -28,6 +28,7 @@ import (
 
 var (
 	dockerCmd      *cobra.Command
+	buildCmd       *cobra.Command
 	buildxCmd      *cobra.Command
 	buildxBuildCmd *cobra.Command
 	buildxStopCmd  *cobra.Command
@@ -58,6 +59,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
@@ -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
@@ -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 | -

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@ import (`
`18`	`18`	`"errors"`
`19`	`19`	`"io"`
`20`	`20`	`"os"`
	`21`	`+ "strings"`
`21`	`22`
`22`	`23`	`"github.com/spf13/cobra"`
`23`	`24`	`)`
`@@ -99,6 +100,13 @@ func copyFile(src string, dst string) error {`
`99`	`100`	`}`
`100`	`101`
`101`	`102`	`func getAliases(cmd *cobra.Command) []string {`
	`103`	`+ if a := cmd.Annotations["aliases"]; a != "" {`
	`104`	`+ aliases := strings.Split(a, ",")`
	`105`	`+ for i := 0; i < len(aliases); i++ {`
	`106`	`+ aliases[i] = strings.TrimSpace(aliases[i])`
	`107`	`+ }`
	`108`	`+ return aliases`
	`109`	`+ }`
`102`	`110`	`if len(cmd.Aliases) == 0 {`
`103`	`111`	`return cmd.Aliases`
`104`	`112`	`}`