cli: use custom annotation for aliases #3694
Conversation
Codecov Report
@@ Coverage Diff @@
## master #3694 +/- ##
=========================================
Coverage ? 59.02%
=========================================
Files ? 289
Lines ? 24651
Branches ? 0
=========================================
Hits ? 14551
Misses ? 9226
Partials ? 874 |
| // formatted as the full command as they're called (contrary to the default | ||
| // Aliases function, which only returns the subcommand). | ||
| func commandAliases(cmd *cobra.Command) string { | ||
| if cmd.Annotations["aliases"] != "" { |
There was a problem hiding this comment.
Should we expose the "aliases" annotation name in cobra pkg to be used in cli plugins projects? Pretty much like https://github.com/docker/cli-docs-tool/blob/main/annotation/annotation.go?
There was a problem hiding this comment.
Hm.. yes, so was a bit on the fence where to define it, as it's not "just" docs of course (we're also using it for the cli usage output).
Perhaps we should define a list of consts for annotations though. Was also thinking "should it have a prefix", but we already have used (e.g.) version for a long time, so I think that ship has sailed.
There was a problem hiding this comment.
Ah yes indeed there is the cli usage output
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>
5097367 to
80b1285
Compare
|
thx! Let me bring this one in |
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 lsas alias fordocker image list). Our CLI has some commands that are available both as atop-level shorthand as well as
docker <object> <verb>subcommands. For example,docker psis a shorthand fordocker 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:
With this patch:
- Description for the changelog
- A picture of a cute animal (not mandatory but encouraged)