diff --git a/cmd/ci/ci.go b/cmd/ci/ci.go index 0cc61f6e10..5b0e4d595e 100644 --- a/cmd/ci/ci.go +++ b/cmd/ci/ci.go @@ -51,9 +51,10 @@ func NewCICmd(flags *flags.GlobalFlags) *cobra.Command { ciCmd := &cobra.Command{ Use: "ci [flags] [workspace-path|workspace-name] -- [args...]", Short: "Build a devcontainer, run a command inside it, then tear it down", - Long: `Builds an ephemeral devcontainer, runs the given command inside it, and -deletes the workspace afterwards. A non-zero exit from that command propagates as the -exit code of "devsy ci".`, + Long: `Build a devcontainer, run a command inside it, then tear it down. + +The workspace is deleted afterwards. A non-zero exit from the command is +returned as the exit code of "devsy ci".`, RunE: func(cobraCmd *cobra.Command, args []string) error { source, runCmd, err := splitArgs(cobraCmd, args, cmd.RunCmdString) if err != nil { diff --git a/cmd/config/read.go b/cmd/config/read.go index 5eb2a00771..0334a047c0 100644 --- a/cmd/config/read.go +++ b/cmd/config/read.go @@ -35,7 +35,7 @@ func NewReadCmd(f *flags.GlobalFlags) *cobra.Command { cmd := &ReadCmd{GlobalFlags: f} readConfigCmd := &cobra.Command{ Use: "read", - Short: "Reads and outputs the merged devcontainer configuration as JSON", + Short: "Read the merged devcontainer configuration as JSON", RunE: cmd.Run, } diff --git a/cmd/context/create.go b/cmd/context/create.go index 050dc48c78..876e235612 100644 --- a/cmd/context/create.go +++ b/cmd/context/create.go @@ -28,7 +28,7 @@ func NewCreateCmd(flags *flags.GlobalFlags) *cobra.Command { } createCmd := &cobra.Command{ Use: "create CONTEXT", - Short: "Create a new Devsy context", + Short: "Create a context", Args: cobra.ExactArgs(1), RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args[0]) diff --git a/cmd/context/delete.go b/cmd/context/delete.go index 5c6564ba00..8b54d6a409 100644 --- a/cmd/context/delete.go +++ b/cmd/context/delete.go @@ -23,7 +23,7 @@ func NewDeleteCmd(flags *flags.GlobalFlags) *cobra.Command { deleteCmd := &cobra.Command{ Use: "delete", Aliases: []string{"rm"}, - Short: "Delete a Devsy context", + Short: "Delete a context", RunE: func(cobraCmd *cobra.Command, args []string) error { if len(args) > 1 { return fmt.Errorf("specify the context to delete") diff --git a/cmd/context/list.go b/cmd/context/list.go index 036e5ab9ce..9a27331ace 100644 --- a/cmd/context/list.go +++ b/cmd/context/list.go @@ -27,7 +27,7 @@ func NewListCmd(flags *flags.GlobalFlags) *cobra.Command { listCmd := &cobra.Command{ Use: "list", Aliases: []string{"ls"}, - Short: "List Devsy contexts", + Short: "List contexts", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context()) }, diff --git a/cmd/context/options.go b/cmd/context/options.go index 9ca7682752..2226ec144f 100644 --- a/cmd/context/options.go +++ b/cmd/context/options.go @@ -26,7 +26,7 @@ func NewOptionsCmd(flags *flags.GlobalFlags) *cobra.Command { } optionsCmd := &cobra.Command{ Use: "get", - Short: "Show options of a context", + Short: "Show a context's options", Annotations: telemetry.SkipInUIAnnotation(), RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) diff --git a/cmd/context/set_options.go b/cmd/context/set_options.go index c94040b30d..360e576df0 100644 --- a/cmd/context/set_options.go +++ b/cmd/context/set_options.go @@ -25,7 +25,7 @@ func NewSetOptionsCmd(flags *flags.GlobalFlags) *cobra.Command { } setOptionsCmd := &cobra.Command{ Use: "set", - Short: "Set options for a Devsy context", + Short: "Set a context's options", RunE: func(cobraCmd *cobra.Command, args []string) error { if len(args) > 1 { return fmt.Errorf("specify the context") diff --git a/cmd/context/use.go b/cmd/context/use.go index 33af291b3a..f62fd02184 100644 --- a/cmd/context/use.go +++ b/cmd/context/use.go @@ -25,7 +25,7 @@ func NewUseCmd(flags *flags.GlobalFlags) *cobra.Command { } useCmd := &cobra.Command{ Use: "use", - Short: "Set a Devsy context as the default", + Short: "Set the default context", RunE: func(cobraCmd *cobra.Command, args []string) error { if len(args) != 1 { return fmt.Errorf("specify the context to use") diff --git a/cmd/feature/generatedocs.go b/cmd/feature/generatedocs.go index df97852440..e963d6ed05 100644 --- a/cmd/feature/generatedocs.go +++ b/cmd/feature/generatedocs.go @@ -34,9 +34,11 @@ func NewGenerateDocsCmd(globalFlags *flags.GlobalFlags) *cobra.Command { cmd := &GenerateDocsCmd{GlobalFlags: globalFlags} generateDocsCmd := &cobra.Command{ Use: "docs", - Short: "Generate markdown documentation from feature metadata", - Long: `Scan a feature project's src/ directory and generate markdown -documentation for each feature based on its devcontainer-feature.json.`, + Short: "Generate markdown docs from feature metadata", + Long: `Generate markdown docs from feature metadata. + +Scan a feature project's src/ directory and write markdown documentation +for each feature from its devcontainer-feature.json.`, SilenceUsage: true, SilenceErrors: true, RunE: func(_ *cobra.Command, _ []string) error { diff --git a/cmd/feature/info.go b/cmd/feature/info.go index 977d6f2265..c2acea5874 100644 --- a/cmd/feature/info.go +++ b/cmd/feature/info.go @@ -43,12 +43,11 @@ func NewInfoCmd(globalFlags *flags.GlobalFlags) *cobra.Command { cmd := &InfoCmd{GlobalFlags: globalFlags} infoCmd := &cobra.Command{ Use: "info ", - Short: "Fetch and display OCI metadata for a published feature", - Long: `Fetch and display OCI metadata for a published dev container feature. + Short: "Show OCI metadata for a published feature", + Long: `Show OCI metadata for a published feature. -Accepts a feature ID like ghcr.io/devcontainers/features/go or -ghcr.io/devcontainers/features/go:1 and pulls its OCI manifest -to display metadata.`, +Accept a feature ID such as ghcr.io/devcontainers/features/go or +ghcr.io/devcontainers/features/go:1.`, Args: cobra.ExactArgs(1), SilenceUsage: true, SilenceErrors: true, diff --git a/cmd/feature/info_manifest.go b/cmd/feature/info_manifest.go index bc517c7f2a..4b0d2ad541 100644 --- a/cmd/feature/info_manifest.go +++ b/cmd/feature/info_manifest.go @@ -22,11 +22,11 @@ func NewInfoManifestCmd(globalFlags *flags.GlobalFlags) *cobra.Command { cmd := &InfoManifestCmd{GlobalFlags: globalFlags} manifestCmd := &cobra.Command{ Use: "manifest ", - Short: "Display the OCI manifest for a published feature", - Long: `Fetch and display the raw OCI manifest for a published dev container feature. + Short: "Show the OCI manifest for a published feature", + Long: `Show the OCI manifest for a published feature. -Accepts a feature ID like ghcr.io/devcontainers/features/go or -ghcr.io/devcontainers/features/go:1 and outputs the OCI image manifest.`, +Accept a feature ID such as ghcr.io/devcontainers/features/go or +ghcr.io/devcontainers/features/go:1 and print its OCI image manifest.`, Args: cobra.ExactArgs(1), SilenceUsage: true, SilenceErrors: true, diff --git a/cmd/feature/info_tags.go b/cmd/feature/info_tags.go index 67b9cc66a1..3f18f4290a 100644 --- a/cmd/feature/info_tags.go +++ b/cmd/feature/info_tags.go @@ -24,10 +24,10 @@ func NewInfoTagsCmd(globalFlags *flags.GlobalFlags) *cobra.Command { tagsCmd := &cobra.Command{ Use: "tags ", Short: "List available tags for a published feature", - Long: `List all available tags from the registry for a published dev container feature. + Long: `List available tags for a published feature. -Accepts a feature ID like ghcr.io/devcontainers/features/go and -queries the registry for all available image tags.`, +Accept a feature ID such as ghcr.io/devcontainers/features/go and list the +image tags in its registry.`, Args: cobra.ExactArgs(1), SilenceUsage: true, SilenceErrors: true, diff --git a/cmd/feature/outdated.go b/cmd/feature/outdated.go index 6244540545..fcda34b8be 100644 --- a/cmd/feature/outdated.go +++ b/cmd/feature/outdated.go @@ -40,7 +40,7 @@ func NewOutdatedCmd(f *flags.GlobalFlags) *cobra.Command { cmd := &OutdatedCmd{GlobalFlags: f} outdatedCmd := &cobra.Command{ Use: "outdated", - Short: "Checks for newer versions of installed devcontainer features", + Short: "Check for newer versions of installed devcontainer features", Args: cobra.NoArgs, RunE: func(cobraCmd *cobra.Command, _ []string) error { return cmd.Run(cobraCmd.Context()) diff --git a/cmd/feature/package.go b/cmd/feature/package.go index 927f159d57..4f92d696a9 100644 --- a/cmd/feature/package.go +++ b/cmd/feature/package.go @@ -36,10 +36,11 @@ func NewPackageCmd(globalFlags *flags.GlobalFlags) *cobra.Command { packageCmd := &cobra.Command{ Use: "package", Short: "Package feature source directories into OCI-compliant tarballs", - Long: `Bundle feature source directories into devcontainer-feature-.tgz archives. + Long: `Package feature source directories into OCI-compliant tarballs. -Scans the target directory for subdirectories containing devcontainer-feature.json -and creates gzipped tar archives suitable for OCI distribution.`, +Find subdirectories of the target directory that contain +devcontainer-feature.json and write a devcontainer-feature-.tgz archive +for each.`, SilenceUsage: true, SilenceErrors: true, RunE: func(_ *cobra.Command, _ []string) error { diff --git a/cmd/feature/publish.go b/cmd/feature/publish.go index 421807a630..bcec092e53 100644 --- a/cmd/feature/publish.go +++ b/cmd/feature/publish.go @@ -24,12 +24,12 @@ func NewPublishCmd(globalFlags *flags.GlobalFlags) *cobra.Command { publishFlags := &PublishFlags{} publishCmd := &cobra.Command{ Use: "publish", - Short: "Package and push features to OCI registry", - Long: `Publish packaged dev container features to an OCI registry. + Short: "Package and push features to an OCI registry", + Long: `Package and push features to an OCI registry. -Takes the path to a packaged feature directory (output of 'features package' -or a directory containing devcontainer-feature.json) and pushes it as an -OCI artifact.`, +Pass the path to a packaged feature directory (output of +'devsy feature package') or a directory containing devcontainer-feature.json. +It is pushed as an OCI artifact.`, SilenceUsage: true, SilenceErrors: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/feature/resolvedeps.go b/cmd/feature/resolvedeps.go index ad5972526f..05b89b9383 100644 --- a/cmd/feature/resolvedeps.go +++ b/cmd/feature/resolvedeps.go @@ -37,8 +37,10 @@ func NewResolveDepsCmd(globalFlags *flags.GlobalFlags) *cobra.Command { resolveDepsCmd := &cobra.Command{ Use: "resolve-dependencies", Short: "Resolve feature install order from a devcontainer.json", - Long: `Read a devcontainer.json and output the resolved feature -install order based on dependency declarations and install ordering.`, + Long: `Resolve feature install order from a devcontainer.json. + +Read the file and print the install order from its dependency and ordering +declarations.`, SilenceUsage: true, SilenceErrors: true, RunE: func(cobraCmd *cobra.Command, _ []string) error { diff --git a/cmd/feature/root.go b/cmd/feature/root.go index 8ac8886b8e..d94fc849fb 100644 --- a/cmd/feature/root.go +++ b/cmd/feature/root.go @@ -8,7 +8,7 @@ import ( func NewFeatureCmd(globalFlags *flags.GlobalFlags) *cobra.Command { featureCmd := &cobra.Command{ Use: "feature", - Short: "Commands for inspecting and managing dev container features", + Short: "Manage devcontainer features", SilenceUsage: true, SilenceErrors: true, Args: cobra.NoArgs, diff --git a/cmd/feature/test.go b/cmd/feature/test.go index 7e0030b915..7aab5199a4 100644 --- a/cmd/feature/test.go +++ b/cmd/feature/test.go @@ -43,12 +43,12 @@ func NewTestCmd(globalFlags *flags.GlobalFlags) *cobra.Command { cmd := &TestCmd{GlobalFlags: globalFlags} testCmd := &cobra.Command{ Use: "test", - Short: "Test dev container features in isolation", - Long: `Run lifecycle hook tests for dev container features. + Short: "Test devcontainer features in isolation", + Long: `Test devcontainer features in isolation. -Scans the project's src/ directory for features, builds test containers -from a base image, installs each feature, and runs the corresponding -test scripts from the test/ directory.`, +Scan the project's src/ directory for features, build a test container from a +base image, install each feature, and run its test scripts from the test/ +directory.`, SilenceUsage: true, SilenceErrors: true, RunE: func(_ *cobra.Command, _ []string) error { diff --git a/cmd/feature/upgrade.go b/cmd/feature/upgrade.go index 91b5293942..76bcee6b63 100644 --- a/cmd/feature/upgrade.go +++ b/cmd/feature/upgrade.go @@ -28,10 +28,11 @@ func NewUpgradeCmd(f *flags.GlobalFlags) *cobra.Command { cmd := &UpgradeCmd{GlobalFlags: f} upgradeCmd := &cobra.Command{ Use: "upgrade [feature...]", - Short: "Upgrades devcontainer feature versions to the latest available", - Long: `Upgrades devcontainer feature versions in devcontainer.json to the latest -available versions. If specific features are provided as arguments, only those -features are upgraded. Otherwise, all outdated features are upgraded.`, + Short: "Upgrade devcontainer feature versions to the latest available", + Long: `Upgrade devcontainer feature versions to the latest available. + +Versions are updated in devcontainer.json. Pass feature names to upgrade only +those features, or none to upgrade all outdated features.`, RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/ide/options.go b/cmd/ide/options.go index 393ed8dbb7..aa7d90bd08 100644 --- a/cmd/ide/options.go +++ b/cmd/ide/options.go @@ -28,7 +28,7 @@ func NewOptionsCmd(flags *flags.GlobalFlags) *cobra.Command { } optionsCmd := &cobra.Command{ Use: "get ", - Short: "Get IDE options (list available IDEs with 'devsy ide list')", + Short: "Show IDE options", Args: cobra.ExactArgs(1), ValidArgsFunction: ideNameCompletion, RunE: func(cobraCmd *cobra.Command, args []string) error { diff --git a/cmd/ide/set.go b/cmd/ide/set.go index 7d1ed02aa5..6aab08f457 100644 --- a/cmd/ide/set.go +++ b/cmd/ide/set.go @@ -33,8 +33,8 @@ func NewSetCmd(flags *flags.GlobalFlags) *cobra.Command { Long: `Set global options for the named IDE. To assign an IDE to a specific workspace, use -'devsy workspace set-ide '. Available IDEs can be listed -with 'devsy ide list'.`, +'devsy workspace set-ide '. List available IDEs with +'devsy ide list'.`, Args: cobra.ExactArgs(1), ValidArgsFunction: ideNameCompletion, RunE: func(cobraCmd *cobra.Command, args []string) error { diff --git a/cmd/ide/use.go b/cmd/ide/use.go index f83b8c76c1..cf3d8b2264 100644 --- a/cmd/ide/use.go +++ b/cmd/ide/use.go @@ -30,10 +30,10 @@ func NewUseCmd(flags *flags.GlobalFlags) *cobra.Command { } useCmd := &cobra.Command{ Use: "use ", - Short: "Configure the default IDE to use (list available IDEs with 'devsy ide list')", - Long: `Configure the default IDE to use + Short: "Set the default IDE", + Long: `Set the default IDE. -Available IDEs can be listed with 'devsy ide list'`, +List available IDEs with 'devsy ide list'.`, Args: cobra.ExactArgs(1), ValidArgsFunction: ideNameCompletion, RunE: func(cobraCmd *cobra.Command, args []string) error { diff --git a/cmd/machine/create.go b/cmd/machine/create.go index 5486f6187c..6e5caa6d58 100644 --- a/cmd/machine/create.go +++ b/cmd/machine/create.go @@ -25,7 +25,7 @@ func NewCreateCmd(flags *flags.GlobalFlags) *cobra.Command { } createCmd := &cobra.Command{ Use: "create [name]", - Short: "Creates a new machine", + Short: "Create a machine", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/machine/delete.go b/cmd/machine/delete.go index 82dc4b95c8..2cda8dc204 100644 --- a/cmd/machine/delete.go +++ b/cmd/machine/delete.go @@ -31,7 +31,7 @@ func NewDeleteCmd(flags *flags.GlobalFlags) *cobra.Command { deleteCmd := &cobra.Command{ Use: "delete [name]", Aliases: []string{"rm"}, - Short: "Deletes an existing machine", + Short: "Delete a machine", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/machine/describe.go b/cmd/machine/describe.go index 1516506f16..be76ce8748 100644 --- a/cmd/machine/describe.go +++ b/cmd/machine/describe.go @@ -23,7 +23,7 @@ func NewDescribeCmd(flags *flags.GlobalFlags) *cobra.Command { } describeCmd := &cobra.Command{ Use: "describe [name]", - Short: "Retrieves the description of an existing machine", + Short: "Show a machine's description", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/machine/diagnostics.go b/cmd/machine/diagnostics.go index e5f5491b4d..98ee864cb7 100644 --- a/cmd/machine/diagnostics.go +++ b/cmd/machine/diagnostics.go @@ -76,7 +76,7 @@ func NewDiagnosticsCmd(globalFlags *flags.GlobalFlags) *cobra.Command { cmd := &DiagnosticsCmd{GlobalFlags: globalFlags} c := &cobra.Command{ Use: "diagnostics [name]", - Short: "Show Devsy machine diagnostic events and daemon status", + Short: "Show machine diagnostic events and daemon status", RunE: func(c *cobra.Command, args []string) error { return cmd.Run(c.Context(), args) }, } cliflags.Add( diff --git a/cmd/machine/inspect.go b/cmd/machine/inspect.go index 156dd7fd61..812af536fe 100644 --- a/cmd/machine/inspect.go +++ b/cmd/machine/inspect.go @@ -22,7 +22,7 @@ func NewInspectCmd(flags *flags.GlobalFlags) *cobra.Command { } inspectCmd := &cobra.Command{ Use: "inspect", - Short: "Inspects an existing machine", + Short: "Inspect a machine", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/machine/list.go b/cmd/machine/list.go index b9d0492de6..f4193cdca1 100644 --- a/cmd/machine/list.go +++ b/cmd/machine/list.go @@ -29,7 +29,7 @@ func NewListCmd(flags *flags.GlobalFlags) *cobra.Command { listCmd := &cobra.Command{ Use: "list", Aliases: []string{"ls"}, - Short: "Lists existing machines", + Short: "List machines", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context()) }, diff --git a/cmd/machine/logs.go b/cmd/machine/logs.go index 91f1c440c1..6f82e025e2 100644 --- a/cmd/machine/logs.go +++ b/cmd/machine/logs.go @@ -28,7 +28,7 @@ func NewLogsCmd(globalFlags *flags.GlobalFlags) *cobra.Command { cmd := &LogsCmd{GlobalFlags: globalFlags} c := &cobra.Command{ Use: "logs [name]", - Short: "Show Devsy machine diagnostic events", + Short: "Show machine diagnostic events", RunE: func(c *cobra.Command, args []string) error { return cmd.Run(c.Context(), args) }, } cliflags.Add( diff --git a/cmd/machine/ssh.go b/cmd/machine/ssh.go index 8ebe3c6fed..350b68cb1f 100644 --- a/cmd/machine/ssh.go +++ b/cmd/machine/ssh.go @@ -86,7 +86,7 @@ func NewSSHCmd(flags *flags.GlobalFlags) *cobra.Command { } sshCmd := &cobra.Command{ Use: "ssh [name]", - Short: "SSH into the machine", + Short: "Open an SSH session to a machine", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/machine/start.go b/cmd/machine/start.go index 6534bb3d61..6a275d2098 100644 --- a/cmd/machine/start.go +++ b/cmd/machine/start.go @@ -21,7 +21,7 @@ func NewStartCmd(flags *flags.GlobalFlags) *cobra.Command { } startCmd := &cobra.Command{ Use: "start [name]", - Short: "Starts an existing machine", + Short: "Start a machine", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/machine/status.go b/cmd/machine/status.go index b065815386..2d917e6916 100644 --- a/cmd/machine/status.go +++ b/cmd/machine/status.go @@ -26,7 +26,7 @@ func NewStatusCmd(flags *flags.GlobalFlags) *cobra.Command { } statusCmd := &cobra.Command{ Use: "status [name]", - Short: "Retrieves the status of an existing machine", + Short: "Show a machine's status", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/machine/stop.go b/cmd/machine/stop.go index 0021dd75d9..712889de19 100644 --- a/cmd/machine/stop.go +++ b/cmd/machine/stop.go @@ -22,7 +22,7 @@ func NewStopCmd(flags *flags.GlobalFlags) *cobra.Command { } stopCmd := &cobra.Command{ Use: "stop [name]", - Short: "Stops an existing machine", + Short: "Stop a machine", RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) }, diff --git a/cmd/provider/add.go b/cmd/provider/add.go index b9693e4fa7..5bde1e79b1 100644 --- a/cmd/provider/add.go +++ b/cmd/provider/add.go @@ -41,7 +41,7 @@ func NewAddCmd(f *flags.GlobalFlags) *cobra.Command { } addCmd := &cobra.Command{ Use: "add [name, GitHub link, URL or path]", - Short: "Adds a new provider to Devsy", + Short: "Add a provider", Args: cobra.MaximumNArgs(1), PreRunE: func(cobraCommand *cobra.Command, args []string) error { if cmd.FromExisting != "" { diff --git a/cmd/provider/delete.go b/cmd/provider/delete.go index 42ecb7dc2c..a9a5d61482 100644 --- a/cmd/provider/delete.go +++ b/cmd/provider/delete.go @@ -33,7 +33,7 @@ func NewDeleteCmd(flags *flags.GlobalFlags) *cobra.Command { deleteCmd := &cobra.Command{ Use: "delete [name]", Aliases: []string{"rm"}, - Short: "Deletes an existing provider", + Short: "Delete a provider", Args: cobra.MaximumNArgs(1), RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args) diff --git a/cmd/provider/icon.go b/cmd/provider/icon.go index 54433c390e..cce5f03a25 100644 --- a/cmd/provider/icon.go +++ b/cmd/provider/icon.go @@ -37,10 +37,11 @@ func NewIconCmd(flags *flags.GlobalFlags) *cobra.Command { } iconCmd := &cobra.Command{ Use: "icon [name]", - Short: "Print an installed provider's cached icon as JSON", - Long: "Reads the icon cached for an installed provider. The result is always JSON: " + - "{revision, mimeType, dataBase64} for an image or {revision, missing: true} " + - "when the provider has no usable image for the theme. Never uses the network.", + Short: "Print a provider's cached icon as JSON", + Long: "Print a provider's cached icon as JSON.\n\n" + + "The output is {revision, mimeType, dataBase64} for an image, or " + + "{revision, missing: true} when the provider has no usable image for the " + + "theme. It never uses the network.", Args: cobra.ExactArgs(1), Annotations: telemetry.SkipInUIAnnotation(), RunE: func(_ *cobra.Command, args []string) error { diff --git a/cmd/provider/init.go b/cmd/provider/init.go index 3ab5c79358..9a50ad5714 100644 --- a/cmd/provider/init.go +++ b/cmd/provider/init.go @@ -27,7 +27,7 @@ func NewInitCmd(f *flags.GlobalFlags) *cobra.Command { cmd := &InitCmd{GlobalFlags: f} initCmd := &cobra.Command{ Use: "init [name]", - Short: "Run or re-run init and option resolution for an existing provider", + Short: "Initialize a provider and resolve its options", Args: cobra.MaximumNArgs(1), RunE: func(cobraCmd *cobra.Command, args []string) error { devsyConfig, err := config.LoadConfig(cmd.Context, cmd.Provider) diff --git a/cmd/provider/set_source.go b/cmd/provider/set_source.go index 542c23999b..bc32f7408b 100644 --- a/cmd/provider/set_source.go +++ b/cmd/provider/set_source.go @@ -32,7 +32,7 @@ func NewSetSourceCmd(flags *flags.GlobalFlags) *cobra.Command { } setSourceCmd := &cobra.Command{ Use: "set-source [name] [name, GitHub link, URL or path]", - Short: "Set or change a provider's source (replaces the registered name, repo, URL, or path)", + Short: "Set a provider's source", RunE: func(cobraCmd *cobra.Command, args []string) error { ctx := cobraCmd.Context() diff --git a/cmd/provider/versions.go b/cmd/provider/versions.go index aafae8b1ab..5536ea3dc1 100644 --- a/cmd/provider/versions.go +++ b/cmd/provider/versions.go @@ -30,7 +30,7 @@ func NewVersionsCmd(f *flags.GlobalFlags) *cobra.Command { cmd := &VersionsCmd{GlobalFlags: f} versionsCmd := &cobra.Command{ Use: "versions [name]", - Short: "List available upstream versions for a provider", + Short: "List upstream versions for a provider", Args: cobra.MaximumNArgs(1), RunE: func(cobraCmd *cobra.Command, args []string) error { devsyConfig, err := config.LoadConfig(cmd.Context, cmd.Provider) diff --git a/cmd/secrets/bind.go b/cmd/secrets/bind.go index 335a961037..60fbf64e54 100644 --- a/cmd/secrets/bind.go +++ b/cmd/secrets/bind.go @@ -20,7 +20,7 @@ func NewAttachCmd(flags *flags.GlobalFlags) *cobra.Command { cmd := &AttachCmd{GlobalFlags: flags} attachCmd := &cobra.Command{ Use: "attach NAME", - Short: "Bind a secret reference to the active context so it is injected automatically on up", + Short: "Bind a secret reference to the active context", Args: cobra.ExactArgs(1), RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args[0]) diff --git a/cmd/secrets/get.go b/cmd/secrets/get.go index 60f93d7203..0aad86f4fa 100644 --- a/cmd/secrets/get.go +++ b/cmd/secrets/get.go @@ -21,8 +21,7 @@ func NewGetCmd(flags *flags.GlobalFlags) *cobra.Command { Short: "Print a secret's value", Long: `Print a secret's value to standard output. -Intended for scripting. The value is written without a trailing newline -alteration beyond a single terminating newline.`, +Use it in scripts. The value is followed by a single newline.`, Args: cobra.ExactArgs(1), RunE: func(cobraCmd *cobra.Command, args []string) error { return cmd.Run(cobraCmd.Context(), args[0]) diff --git a/cmd/template/apply.go b/cmd/template/apply.go index 2f78060c92..6dc1db4bb1 100644 --- a/cmd/template/apply.go +++ b/cmd/template/apply.go @@ -36,7 +36,7 @@ func NewApplyCmd(globalFlags *flags.GlobalFlags) *cobra.Command { applyFlags := &ApplyFlags{} applyCmd := &cobra.Command{ Use: "apply", - Short: "Fetch template from OCI registry and scaffold devcontainer config", + Short: "Scaffold devcontainer config from an OCI registry template", RunE: func(cmd *cobra.Command, args []string) error { return runApply(applyFlags) }, diff --git a/cmd/template/metadata.go b/cmd/template/metadata.go index d2af955eb5..9e69d7776d 100644 --- a/cmd/template/metadata.go +++ b/cmd/template/metadata.go @@ -21,7 +21,7 @@ func NewMetadataCmd(globalFlags *flags.GlobalFlags) *cobra.Command { metadataFlags := &MetadataFlags{} metadataCmd := &cobra.Command{ Use: "metadata", - Short: "Fetch published template metadata from OCI registry", + Short: "Show published template metadata from an OCI registry", RunE: func(cmd *cobra.Command, args []string) error { return runMetadata(metadataFlags) }, diff --git a/cmd/template/publish.go b/cmd/template/publish.go index 97c9e2ae6a..0fe9c1ef04 100644 --- a/cmd/template/publish.go +++ b/cmd/template/publish.go @@ -23,7 +23,7 @@ func NewPublishCmd(globalFlags *flags.GlobalFlags) *cobra.Command { publishFlags := &PublishFlags{} publishCmd := &cobra.Command{ Use: "publish", - Short: "Package and push templates to OCI registry", + Short: "Package and push templates to an OCI registry", RunE: func(cmd *cobra.Command, args []string) error { return runPublish(publishFlags) }, diff --git a/cmd/template/template.go b/cmd/template/template.go index 4ba8fd4e4d..9dd944d26e 100644 --- a/cmd/template/template.go +++ b/cmd/template/template.go @@ -8,7 +8,7 @@ import ( func NewTemplateCmd(globalFlags *flags.GlobalFlags) *cobra.Command { templateCmd := &cobra.Command{ Use: "template", - Short: "Devcontainer template commands", + Short: "Manage devcontainer templates", SilenceUsage: true, SilenceErrors: true, Args: cobra.NoArgs, diff --git a/cmd/workspace/set_ide.go b/cmd/workspace/set_ide.go index 06978a68be..f2aa2a7aad 100644 --- a/cmd/workspace/set_ide.go +++ b/cmd/workspace/set_ide.go @@ -34,7 +34,9 @@ func NewSetIDECmd(globalFlags *flags.GlobalFlags) *cobra.Command { setIDECmd := &cobra.Command{ Use: "set-ide ", Short: "Set a workspace's IDE", - Long: `Set a workspace's IDE, persisted to its config and applied on the next + Long: `Set a workspace's IDE. + +The setting is saved to the workspace config and applied on the next 'devsy workspace up'. List available IDEs with 'devsy ide list'.`, Args: cobra.ExactArgs(2), RunE: func(cobraCmd *cobra.Command, args []string) error { diff --git a/cmd/workspace/task.go b/cmd/workspace/task.go index 0fed237d99..cf6ec49388 100644 --- a/cmd/workspace/task.go +++ b/cmd/workspace/task.go @@ -24,7 +24,7 @@ import ( func NewTaskCmd(globalFlags *flags.GlobalFlags) *cobra.Command { taskCmd := &cobra.Command{ Use: "task", - Short: "Manage background tasks (e.g. from 'up --detach')", + Short: "Manage background tasks", } taskCmd.AddCommand(newTaskListCmd(globalFlags)) taskCmd.AddCommand(newTaskGetCmd(globalFlags)) @@ -43,7 +43,7 @@ func newTaskListCmd(globalFlags *flags.GlobalFlags) *cobra.Command { return &cobra.Command{ Use: "list", Aliases: []string{"ls"}, - Short: "List background tasks, most recently started first", + Short: "List background tasks", Args: cobra.NoArgs, RunE: func(*cobra.Command, []string) error { return cmd.run() diff --git a/pkg/clihelp/help.go b/pkg/clihelp/help.go index b9558fb0ec..ffa1971ee3 100644 --- a/pkg/clihelp/help.go +++ b/pkg/clihelp/help.go @@ -21,6 +21,7 @@ const ( indent = " " descIndent = " " nameColumn = 12 + maxNameCol = 28 defaultWidth = 80 maxWidth = 100 minWidth = 40 @@ -48,6 +49,7 @@ func render(cmd *cobra.Command, out io.Writer) { var b strings.Builder writeIntro(&b, cmd, width) writeUsage(&b, cmd) + writeAliases(&b, cmd) writeCommands(&b, cmd, width) writeFlags(&b, cmd, width) writeFooter(&b, cmd) @@ -122,19 +124,67 @@ func writeCommands(b *strings.Builder, cmd *cobra.Command, width int) { section(b, "SUBCOMMANDS") sort.Slice(subs, func(i, j int) bool { return subs[i].Name() < subs[j].Name() }) - for _, sub := range subs { - name := sub.Name() + // Keep the description column inside the terminal so wrapped text never + // runs past the right edge. + limit := clamp(width/3, nameColumn, maxNameCol) + labels := make([]string, len(subs)) + col := nameColumn + for i, sub := range subs { + labels[i] = commandLabel(sub) + col = clamp(len(labels[i])+2, col, limit) + } + for i, sub := range subs { b.WriteString(indent) - b.WriteString(theme.Command.Render(name)) + b.WriteString(theme.Command.Render(sub.Name())) + if names := aliasNames(sub); len(names) > 0 { + b.WriteString(theme.Muted.Render(" (" + strings.Join(names, ", ") + ")")) + } if sub.Short == "" { b.WriteString("\n") continue } - // Pad from the plain name - the styled string carries escape bytes + // Pad from the plain label - the styled string carries escape bytes // that would otherwise be counted as visible columns. - b.WriteString(strings.Repeat(" ", max(1, nameColumn-len(name)))) - descCol := len(indent) + nameColumn - b.WriteString(wrapHanging(sub.Short, width, descCol)) + if len(labels[i]) >= col { + // Label overflows the column: start the description on its own line. + b.WriteString("\n" + strings.Repeat(" ", len(indent)+col)) + } else { + b.WriteString(strings.Repeat(" ", col-len(labels[i]))) + } + b.WriteString(wrapHanging(sub.Short, width, len(indent)+col)) + b.WriteString("\n") + } + b.WriteString("\n") +} + +func aliasNames(cmd *cobra.Command) []string { + var names []string + for _, alias := range cmd.Aliases { + if alias != cmd.Name() { + names = append(names, alias) + } + } + return names +} + +func commandLabel(cmd *cobra.Command) string { + label := cmd.Name() + if names := aliasNames(cmd); len(names) > 0 { + label += " (" + strings.Join(names, ", ") + ")" + } + return label +} + +func writeAliases(b *strings.Builder, cmd *cobra.Command) { + names := aliasNames(cmd) + if len(names) == 0 || !cmd.HasParent() { + return + } + section(b, "ALIASES") + parent := cmd.Parent().CommandPath() + for _, name := range names { + b.WriteString(indent) + b.WriteString(parent + " " + theme.Command.Render(name)) b.WriteString("\n") } b.WriteString("\n") diff --git a/pkg/clihelp/help_test.go b/pkg/clihelp/help_test.go index c751cc3111..ee4620e801 100644 --- a/pkg/clihelp/help_test.go +++ b/pkg/clihelp/help_test.go @@ -22,8 +22,10 @@ func newTestRoot(t *testing.T) *cobra.Command { require.NoError(t, pf.MarkHidden("hidden-global")) noop := func(*cobra.Command, []string) {} - ws := &cobra.Command{Use: "workspace", Short: "Manage workspaces"} - list := &cobra.Command{Use: "list", Short: "List workspaces", Run: noop} + ws := &cobra.Command{Use: "workspace", Aliases: []string{"ws"}, Short: "Manage workspaces"} + list := &cobra.Command{ + Use: "list", Aliases: []string{"ls"}, Short: "List workspaces", Run: noop, + } list.Flags().Bool("skip-platform", false, "Don't list platform workspaces") ws.AddCommand(list) root.AddCommand(ws) @@ -148,3 +150,51 @@ func sectionBody(t *testing.T, out, header string) string { } return strings.Join(body, "\n") } + +func TestRender_SubcommandListShowsAliases(t *testing.T) { + root := newTestRoot(t) + + assert.Contains(t, sectionBody(t, renderHelp(t, root), "SUBCOMMANDS:"), "workspace (ws)") + assert.Contains( + t, + sectionBody(t, renderHelp(t, root, "workspace"), "SUBCOMMANDS:"), + "list (ls)", + ) +} + +func TestRender_AliasesSection(t *testing.T) { + root := newTestRoot(t) + + body := sectionBody(t, renderHelp(t, root, "workspace", "list"), "ALIASES:") + assert.Equal(t, "devsy workspace ls", strings.TrimSpace(body)) + assert.NotContains(t, renderHelp(t, root, "loose"), "ALIASES:") +} + +func TestRender_SubcommandDescriptionsAlign(t *testing.T) { + root := newTestRoot(t) + root.AddCommand(&cobra.Command{ + Use: "resolve-dependencies", Short: "Resolve order", Run: func(*cobra.Command, []string) {}, + }) + + body := sectionBody(t, renderHelp(t, root), "SUBCOMMANDS:") + assert.Contains(t, body, "resolve-dependencies Resolve order") + assert.Contains(t, body, "loose A loose command") + assert.Contains(t, body, "workspace (ws) Manage workspaces") +} + +func TestRender_LongAliasedLabelStaysInsideWidth(t *testing.T) { + root := newTestRoot(t) + root.AddCommand(&cobra.Command{ + Use: "describe", + Aliases: []string{"show", "inspect", "details", "info"}, + Short: "Show details", + Run: func(*cobra.Command, []string) {}, + }) + + body := sectionBody(t, renderHelp(t, root), "SUBCOMMANDS:") + for line := range strings.SplitSeq(body, "\n") { + assert.LessOrEqual(t, len(line), defaultWidth, line) + } + assert.Contains(t, body, "describe (show, inspect, details, info)\n") + assert.Contains(t, body, "\n"+strings.Repeat(" ", 28)+"Show details") +}