From 224e8c37e31726c2aafd846a11daf56412c9985a Mon Sep 17 00:00:00 2001 From: Nick Kubala Date: Mon, 16 Aug 2021 15:52:33 -0700 Subject: [PATCH] Various small UX improvements (#6426) --- cmd/skaffold/app/cmd/cmd.go | 12 +-- cmd/skaffold/app/cmd/config.go | 2 +- cmd/skaffold/app/cmd/credits.go | 1 + cmd/skaffold/app/cmd/debug.go | 2 +- cmd/skaffold/app/cmd/delete.go | 2 +- cmd/skaffold/app/cmd/filter.go | 2 +- cmd/skaffold/app/cmd/init.go | 2 +- cmd/skaffold/app/cmd/render.go | 4 +- cmd/skaffold/app/cmd/schema.go | 3 +- cmd/skaffold/app/skaffold_test.go | 8 +- docs/content/en/docs/references/cli/_index.md | 93 ++++--------------- 11 files changed, 39 insertions(+), 92 deletions(-) diff --git a/cmd/skaffold/app/cmd/cmd.go b/cmd/skaffold/app/cmd/cmd.go index 99574776d6b..d6589cd8ef7 100644 --- a/cmd/skaffold/app/cmd/cmd.go +++ b/cmd/skaffold/app/cmd/cmd.go @@ -154,7 +154,7 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command { groups := templates.CommandGroups{ { - Message: "End-to-end pipelines:", + Message: "End-to-end Pipelines:", Commands: []*cobra.Command{ NewCmdRun(), NewCmdDev(), @@ -162,7 +162,7 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command { }, }, { - Message: "Pipeline building blocks for CI/CD:", + Message: "Pipeline Building Blocks:", Commands: []*cobra.Command{ NewCmdBuild(), NewCmdTest(), @@ -173,10 +173,9 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command { }, }, { - Message: "Getting started with a new project:", + Message: "Getting Started With a New Project:", Commands: []*cobra.Command{ NewCmdInit(), - NewCmdFix(), }, }, } @@ -184,6 +183,7 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command { // other commands rootCmd.AddCommand(NewCmdVersion()) + rootCmd.AddCommand(NewCmdFix()) rootCmd.AddCommand(NewCmdCompletion()) rootCmd.AddCommand(NewCmdConfig()) rootCmd.AddCommand(NewCmdFindConfigs()) @@ -198,12 +198,12 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command { rootCmd.AddCommand(NewCmdInspect()) templates.ActsAsRootCommand(rootCmd, nil, groups...) - rootCmd.PersistentFlags().StringVarP(&v, "verbosity", "v", constants.DefaultLogLevel.String(), "Log level (debug, info, warn, error, fatal, panic)") + rootCmd.PersistentFlags().StringVarP(&v, "verbosity", "v", constants.DefaultLogLevel.String(), fmt.Sprintf("Log level: one of %v", logrus.AllLevels)) rootCmd.PersistentFlags().IntVar(&defaultColor, "color", int(output.DefaultColorCode), "Specify the default output color in ANSI escape codes") rootCmd.PersistentFlags().BoolVar(&forceColors, "force-colors", false, "Always print color codes (hidden)") rootCmd.PersistentFlags().BoolVar(&interactive, "interactive", true, "Allow user prompts for more information") rootCmd.PersistentFlags().BoolVar(&update.EnableCheck, "update-check", true, "Check for a more recent version of Skaffold") - rootCmd.PersistentFlags().BoolVar(×tamps, "timestamps", false, "Print timestamps in logs.") + rootCmd.PersistentFlags().BoolVar(×tamps, "timestamps", false, "Print timestamps in logs") rootCmd.PersistentFlags().MarkHidden("force-colors") setFlagsFromEnvVariables(rootCmd) diff --git a/cmd/skaffold/app/cmd/config.go b/cmd/skaffold/app/cmd/config.go index fcc279f62e4..063b2f5537c 100644 --- a/cmd/skaffold/app/cmd/config.go +++ b/cmd/skaffold/app/cmd/config.go @@ -26,7 +26,7 @@ import ( func NewCmdConfig() *cobra.Command { cmd := &cobra.Command{ Use: "config", - Short: "Interact with the global skaffold config file (defaults to `$HOME/.skaffold/config`)", + Short: "Interact with the global Skaffold config file (defaults to `$HOME/.skaffold/config`)", } cmd.AddCommand(NewCmdSet()) diff --git a/cmd/skaffold/app/cmd/credits.go b/cmd/skaffold/app/cmd/credits.go index 5d28ce16f35..17174520857 100644 --- a/cmd/skaffold/app/cmd/credits.go +++ b/cmd/skaffold/app/cmd/credits.go @@ -24,6 +24,7 @@ import ( func NewCmdCredits() *cobra.Command { return NewCmd("credits"). + Hidden(). // internal command WithDescription("Export third party notices to given path (./skaffold-credits by default)"). WithExample("export third party licenses to ~/skaffold-credits", "credits -d ~/skaffold-credits"). WithFlags([]*Flag{ diff --git a/cmd/skaffold/app/cmd/debug.go b/cmd/skaffold/app/cmd/debug.go index ff3a048fc91..bd6268b4eee 100644 --- a/cmd/skaffold/app/cmd/debug.go +++ b/cmd/skaffold/app/cmd/debug.go @@ -33,7 +33,7 @@ var doDebug = runDebug // Unlike `dev`, `debug` defaults `auto-build` and `auto-deploy` to `false`. func NewCmdDebug() *cobra.Command { return NewCmd("debug"). - WithDescription("[beta] Run a pipeline in debug mode"). + WithDescription("Run a pipeline in debug mode"). WithLongDescription("Similar to `dev`, but configures the pipeline for debugging. "+ "Auto-build and sync is disabled by default to prevent accidentally tearing down debug sessions."). WithCommonFlags(). diff --git a/cmd/skaffold/app/cmd/delete.go b/cmd/skaffold/app/cmd/delete.go index 6c0f5e2f836..3c8abc7dd3a 100644 --- a/cmd/skaffold/app/cmd/delete.go +++ b/cmd/skaffold/app/cmd/delete.go @@ -29,7 +29,7 @@ import ( // NewCmdDelete describes the CLI command to delete deployed resources. func NewCmdDelete() *cobra.Command { return NewCmd("delete"). - WithDescription("Delete the deployed application"). + WithDescription("Delete any resources deployed by Skaffold"). WithCommonFlags(). NoArgs(doDelete) } diff --git a/cmd/skaffold/app/cmd/filter.go b/cmd/skaffold/app/cmd/filter.go index b8231e6e14b..232fa880a65 100644 --- a/cmd/skaffold/app/cmd/filter.go +++ b/cmd/skaffold/app/cmd/filter.go @@ -44,7 +44,7 @@ func NewCmdFilter() *cobra.Command { return NewCmd("filter"). Hidden(). // internal command - WithDescription("[alpha] Filter and transform a set of Kubernetes manifests from stdin"). + WithDescription("Filter and transform a set of Kubernetes manifests from stdin"). WithLongDescription("Unlike `render`, this command does not build artifacts."). WithCommonFlags(). WithFlags([]*Flag{ diff --git a/cmd/skaffold/app/cmd/init.go b/cmd/skaffold/app/cmd/init.go index b4d3160798d..f0a0660a447 100644 --- a/cmd/skaffold/app/cmd/init.go +++ b/cmd/skaffold/app/cmd/init.go @@ -51,7 +51,7 @@ var initEntrypoint = initializer.DoInit // NewCmdInit describes the CLI command to generate a Skaffold configuration. func NewCmdInit() *cobra.Command { return NewCmd("init"). - WithDescription("[alpha] Generate configuration for deploying an application"). + WithDescription("Generate configuration for deploying an application"). WithCommonFlags(). WithFlags([]*Flag{ {Value: &skipBuild, Name: "skip-build", DefValue: false, Usage: "Skip generating build artifacts in Skaffold config", IsEnum: true}, diff --git a/cmd/skaffold/app/cmd/render.go b/cmd/skaffold/app/cmd/render.go index 633cda6bec6..0af7b4861ca 100644 --- a/cmd/skaffold/app/cmd/render.go +++ b/cmd/skaffold/app/cmd/render.go @@ -40,14 +40,14 @@ var ( // NewCmdRender describes the CLI command to build artifacts render Kubernetes manifests. func NewCmdRender() *cobra.Command { return NewCmd("render"). - WithDescription("[alpha] Perform all image builds, and output rendered Kubernetes manifests"). + WithDescription("Perform all image builds, and output rendered Kubernetes manifests"). WithExample("Hydrate Kubernetes manifests without building the images, using digest resolved from tag in remote registry ", "render --digest-source=remote"). WithCommonFlags(). WithFlags([]*Flag{ {Value: &showBuild, Name: "loud", DefValue: false, Usage: "Show the build logs and output", IsEnum: true}, {Value: &renderFromBuildOutputFile, Name: "build-artifacts", Shorthand: "a", Usage: "File containing build result from a previous 'skaffold build --file-output'"}, {Value: &offline, Name: "offline", DefValue: false, Usage: `Do not connect to Kubernetes API server for manifest creation and validation. This is helpful when no Kubernetes cluster is available (e.g. GitOps model). No metadata.namespace attribute is injected in this case - the manifest content does not get changed.`, IsEnum: true}, - {Value: &renderOutputPath, Name: "output", Shorthand: "o", DefValue: "", Usage: "file to write rendered manifests to"}, + {Value: &renderOutputPath, Name: "output", Shorthand: "o", DefValue: "", Usage: "File to write rendered manifests to"}, }). NoArgs(doRender) } diff --git a/cmd/skaffold/app/cmd/schema.go b/cmd/skaffold/app/cmd/schema.go index ce2609a5a77..a8dfa76bea0 100644 --- a/cmd/skaffold/app/cmd/schema.go +++ b/cmd/skaffold/app/cmd/schema.go @@ -28,7 +28,7 @@ import ( func NewCmdSchema() *cobra.Command { cmd := &cobra.Command{ Use: "schema", - Short: "List and print json schemas used to validate skaffold.yaml configuration", + Short: "List JSON schemas used to validate skaffold.yaml configuration", } cmd.AddCommand(NewCmdSchemaGet()) @@ -38,6 +38,7 @@ func NewCmdSchema() *cobra.Command { func NewCmdSchemaList() *cobra.Command { return NewCmd("list"). + Hidden(). // internal command WithDescription("List skaffold.yaml's json schema versions"). WithExample("List all the versions", "schema list"). WithExample("List all the versions, in json format", "schema list -o json"). diff --git a/cmd/skaffold/app/skaffold_test.go b/cmd/skaffold/app/skaffold_test.go index 08c790c108b..d6aa73294c2 100644 --- a/cmd/skaffold/app/skaffold_test.go +++ b/cmd/skaffold/app/skaffold_test.go @@ -37,8 +37,8 @@ func TestMainHelp(t *testing.T) { err := Run(&output, &errOutput) t.CheckNoError(err) - t.CheckContains("End-to-end pipelines", output.String()) - t.CheckContains("Getting started with a new project", output.String()) + t.CheckContains("End-to-end Pipelines", output.String()) + t.CheckContains("Getting Started With a New Project", output.String()) t.CheckEmpty(errOutput.String()) }) } @@ -67,8 +67,8 @@ func TestSkaffoldCmdline_MainHelp(t *testing.T) { err := Run(&output, &errOutput) t.CheckNoError(err) - t.CheckContains("End-to-end pipelines", output.String()) - t.CheckContains("Getting started with a new project", output.String()) + t.CheckContains("End-to-end Pipelines", output.String()) + t.CheckContains("Getting Started With a New Project", output.String()) t.CheckEmpty(errOutput.String()) }) } diff --git a/docs/content/en/docs/references/cli/_index.md b/docs/content/en/docs/references/cli/_index.md index f2ae39250bf..494328634ca 100644 --- a/docs/content/en/docs/references/cli/_index.md +++ b/docs/content/en/docs/references/cli/_index.md @@ -66,29 +66,28 @@ To edit this file above edit index_header - the rest of the file is autogenerate ``` -End-to-end pipelines: +End-to-end Pipelines: run Run a pipeline dev Run a pipeline in development mode - debug [beta] Run a pipeline in debug mode + debug Run a pipeline in debug mode -Pipeline building blocks for CI/CD: +Pipeline Building Blocks: build Build the artifacts test Run tests against your built application images deploy Deploy pre-built artifacts - delete Delete the deployed application - render [alpha] Perform all image builds, and output rendered Kubernetes manifests + delete Delete any resources deployed by Skaffold + render Perform all image builds, and output rendered Kubernetes manifests apply Apply hydrated manifests to a cluster -Getting started with a new project: - init [alpha] Generate configuration for deploying an application - fix Update old configuration to a newer schema version +Getting Started With a New Project: + init Generate configuration for deploying an application Other Commands: completion Output shell completion for the given shell (bash or zsh) - config Interact with the global skaffold config file (defaults to `$HOME/.skaffold/config`) - credits Export third party notices to given path (./skaffold-credits by default) + config Interact with the global Skaffold config file (defaults to `$HOME/.skaffold/config`) diagnose Run a diagnostic on Skaffold - schema List and print json schemas used to validate skaffold.yaml configuration + fix Update old configuration to a newer schema version + schema List JSON schemas used to validate skaffold.yaml configuration survey Opens a web browser to fill out the Skaffold survey version Print the version information @@ -274,7 +273,7 @@ Use "skaffold options" for a list of global command-line options (applies to all ### skaffold config -Interact with the global skaffold config file (defaults to `$HOME/.skaffold/config`) +Interact with the global Skaffold config file (defaults to `$HOME/.skaffold/config`) ``` @@ -374,34 +373,9 @@ Env vars: * `SKAFFOLD_GLOBAL` (same as `--global`) * `SKAFFOLD_KUBE_CONTEXT` (same as `--kube-context`) -### skaffold credits - -Export third party notices to given path (./skaffold-credits by default) - -``` - - -Examples: - # export third party licenses to ~/skaffold-credits - skaffold credits -d ~/skaffold-credits - -Options: - -d, --dir='./skaffold-credits': destination directory to place third party licenses - -Usage: - skaffold credits [options] - -Use "skaffold options" for a list of global command-line options (applies to all commands). - - -``` -Env vars: - -* `SKAFFOLD_DIR` (same as `--dir`) - ### skaffold debug -[beta] Run a pipeline in debug mode +Run a pipeline in debug mode ``` @@ -514,7 +488,7 @@ Env vars: ### skaffold delete -Delete the deployed application +Delete any resources deployed by Skaffold ``` @@ -846,7 +820,7 @@ Env vars: ### skaffold init -[alpha] Generate configuration for deploying an application +Generate configuration for deploying an application ``` @@ -897,16 +871,16 @@ The following options can be passed to any command: --color=34: Specify the default output color in ANSI escape codes --interactive=true: Allow user prompts for more information - --timestamps=false: Print timestamps in logs. + --timestamps=false: Print timestamps in logs --update-check=true: Check for a more recent version of Skaffold - -v, --verbosity='warning': Log level (debug, info, warn, error, fatal, panic) + -v, --verbosity='warning': Log level: one of [panic fatal error warning info debug trace] ``` ### skaffold render -[alpha] Perform all image builds, and output rendered Kubernetes manifests +Perform all image builds, and output rendered Kubernetes manifests ``` @@ -927,7 +901,7 @@ Options: -m, --module=[]: Filter Skaffold configs to only the provided named modules -n, --namespace='': Run deployments in the specified namespace --offline=false: Do not connect to Kubernetes API server for manifest creation and validation. This is helpful when no Kubernetes cluster is available (e.g. GitOps model). No metadata.namespace attribute is injected in this case - the manifest content does not get changed. - -o, --output='': file to write rendered manifests to + -o, --output='': File to write rendered manifests to -p, --profile=[]: Activate profiles by name (prefixed with `-` to disable a profile) --profile-auto-activation=true: Set to false to disable profile auto activation --propagate-profiles=true: Setting '--propagate-profiles=false' disables propagating profiles set by the '--profile' flag across config dependencies. This mean that only profiles defined directly in the target 'skaffold.yaml' file are activated. @@ -1069,14 +1043,13 @@ Env vars: ### skaffold schema -List and print json schemas used to validate skaffold.yaml configuration +List JSON schemas used to validate skaffold.yaml configuration ``` Available Commands: get Print a given skaffold.yaml's json schema - list List skaffold.yaml's json schema versions Use "skaffold --help" for more information about a given command. @@ -1102,34 +1075,6 @@ Use "skaffold options" for a list of global command-line options (applies to all ``` -### skaffold schema list - -List skaffold.yaml's json schema versions - -``` - - -Examples: - # List all the versions - skaffold schema list - - # List all the versions, in json format - skaffold schema list -o json - -Options: - -o, --output='plain': Type of output: `plain` or `json`. - -Usage: - skaffold schema list [options] - -Use "skaffold options" for a list of global command-line options (applies to all commands). - - -``` -Env vars: - -* `SKAFFOLD_OUTPUT` (same as `--output`) - ### skaffold survey Opens a web browser to fill out the Skaffold survey