Uh oh!
There was an error while loading. Please reload this page.
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
80b1285ComparethaJeztah
commented
Jun 30, 2022
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)