From 425fda2a7a9ba97fbeacecba08dd9ef736911d1e Mon Sep 17 00:00:00 2001 From: Aravindhan Ayyanathan Date: Mon, 20 Jul 2026 11:37:55 +0100 Subject: [PATCH] Use custom usage template to avoid duplicate flag info in help output Signed-off-by: Aravindhan Ayyanathan --- .../en/reference/cli/fn/eval/_index.md | 39 ++++++++++++++- .../en/reference/cli/fn/render/_index.md | 5 ++ .../en/reference/cli/live/apply/_index.md | 9 ++++ .../en/reference/cli/live/destroy/_index.md | 9 ++++ .../en/reference/cli/live/init/_index.md | 3 ++ .../en/reference/cli/live/migrate/_index.md | 4 ++ .../en/reference/cli/pkg/cat/_index.md | 24 ++++----- .../en/reference/cli/pkg/diff/_index.md | 4 ++ .../en/reference/cli/pkg/tree/_index.md | 8 +-- internal/docs/generated/fndocs/docs.go | 47 +++++++++++++++++- internal/docs/generated/livedocs/docs.go | 25 ++++++++++ internal/docs/generated/pkgdocs/docs.go | 30 ++++++++++++ run/run.go | 49 +++++++++++++++++++ 13 files changed, 240 insertions(+), 16 deletions(-) diff --git a/documentation/content/en/reference/cli/fn/eval/_index.md b/documentation/content/en/reference/cli/fn/eval/_index.md index 47386318b6..4d02ba3dc7 100644 --- a/documentation/content/en/reference/cli/fn/eval/_index.md +++ b/documentation/content/en/reference/cli/fn/eval/_index.md @@ -53,6 +53,11 @@ fn-args: #### Flags ```shell +--allow-alpha-wasm: + Allow alpha wasm functions to be run. If true, you can specify a wasm image + with --image flag or a path to a wasm file (must have the .wasm file + extension) with --exec flag. Defaults to false. + --as-current-user: Use the `uid` and `gid` of the kpt process for container function execution. By default, container function is executed as `nobody` user. You may want to use @@ -108,7 +113,7 @@ fn-args: --match-api-version: Select resources matching the given apiVersion. ---match-kind +--match-kind: Select resources matching the given kind. --match-name: @@ -117,6 +122,38 @@ fn-args: --match-namespace: Select resources matching the given namespace. +--match-annotations: + Select resources matching the given annotations. The value should be in + `key=value` format. Can be specified multiple times to match multiple + annotations. + +--match-labels: + Select resources matching the given labels. The value should be in + `key=value` format. Can be specified multiple times to match multiple + labels. + +--exclude-api-version: + Exclude resources matching the given apiVersion. + +--exclude-kind: + Exclude resources matching the given kind. + +--exclude-name: + Exclude resources matching the given name. + +--exclude-namespace: + Exclude resources matching the given namespace. + +--exclude-annotations: + Exclude resources matching the given annotations. The value should be in + `key=value` format. Can be specified multiple times to match multiple + annotations. + +--exclude-labels: + Exclude resources matching the given labels. The value should be in + `key=value` format. Can be specified multiple times to match multiple + labels. + --mount: List of storage options to enable reading from the local filesytem. By default, container functions can not access the local filesystem. It accepts the same options diff --git a/documentation/content/en/reference/cli/fn/render/_index.md b/documentation/content/en/reference/cli/fn/render/_index.md index 439b4624a0..3661834620 100644 --- a/documentation/content/en/reference/cli/fn/render/_index.md +++ b/documentation/content/en/reference/cli/fn/render/_index.md @@ -45,6 +45,11 @@ PKG_PATH: #### Flags ```shell +--allow-alpha-wasm: + Allow wasm to be used during pipeline execution. When enabled, function + images that are wasm modules will be executed using the wasm runtime + instead of a container runtime. Defaults to false. + --allow-exec: Allow executable binaries to run as function. Note that executable binaries can perform privileged operations on your system, so ensure that binaries diff --git a/documentation/content/en/reference/cli/live/apply/_index.md b/documentation/content/en/reference/cli/live/apply/_index.md index d8716487b6..d52d06ec97 100644 --- a/documentation/content/en/reference/cli/live/apply/_index.md +++ b/documentation/content/en/reference/cli/live/apply/_index.md @@ -102,6 +102,15 @@ PKG_PATH | -: for all resources. Default is `false`. Does not apply for the `table` output format. + +--status-policy: + Determines which status information should be saved in the inventory + (if compatible). The available options are: + + * all: Save status for all resources in the inventory. + * none: Do not save any status information in the inventory. + + The default value is `all`. ``` diff --git a/documentation/content/en/reference/cli/live/destroy/_index.md b/documentation/content/en/reference/cli/live/destroy/_index.md index be74d63412..a611d54e31 100644 --- a/documentation/content/en/reference/cli/live/destroy/_index.md +++ b/documentation/content/en/reference/cli/live/destroy/_index.md @@ -65,6 +65,15 @@ PKG_PATH | -: for all resources. Default is `false`. Does not apply for the `table` output format. + +--status-policy: + Determines which status information should be saved in the inventory + (if compatible). The available options are: + + * all: Save status for all resources in the inventory. + * none: Do not save any status information in the inventory. + + The default value is `all`. ``` diff --git a/documentation/content/en/reference/cli/live/init/_index.md b/documentation/content/en/reference/cli/live/init/_index.md index 1ce2ad5580..56c0ab6510 100644 --- a/documentation/content/en/reference/cli/live/init/_index.md +++ b/documentation/content/en/reference/cli/live/init/_index.md @@ -51,6 +51,9 @@ PKG_PATH: in the package belong in the same namespace. If they do, that namespace will be used. If they do not, the namespace in the user's context will be chosen. +--quiet: + If true, do not print output message for initialization. Defaults to false. + --rg-file: The name used for the file created for the ResourceGroup CR. Defaults to 'resourcegroup.yaml'. diff --git a/documentation/content/en/reference/cli/live/migrate/_index.md b/documentation/content/en/reference/cli/live/migrate/_index.md index ee28bf783f..7058b447a5 100644 --- a/documentation/content/en/reference/cli/live/migrate/_index.md +++ b/documentation/content/en/reference/cli/live/migrate/_index.md @@ -62,6 +62,10 @@ PKG_PATH: The namespace for the ResourceGroup resource that contains the inventory for the package. If not provided, it defaults to the same namespace as the existing inventory object. + +--rg-file: + The file path to the ResourceGroup object. Defaults to + 'resourcegroup.yaml'. ``` diff --git a/documentation/content/en/reference/cli/pkg/cat/_index.md b/documentation/content/en/reference/cli/pkg/cat/_index.md index f04c0b3b4d..b91d38bb46 100644 --- a/documentation/content/en/reference/cli/pkg/cat/_index.md +++ b/documentation/content/en/reference/cli/pkg/cat/_index.md @@ -32,27 +32,29 @@ FILE | DIR: Binary files are skipped. Defaults to the current directory. ``` - - #### Flags ```shell ---annotate - Annotate resources with their file origins. +--annotate: + Annotate resources with their file origins. Defaults to false. ---format - Format resource before printing. Defaults to true. +--format: + Format resource config YAML before printing (reorders fields to canonical + order). Defaults to true. ---recurse-subpackages, -R +--recurse-subpackages, -R: Print resources recursively in all the nested subpackages. Defaults to true. ---strip-comments - Remove comments from yaml. +--strip-comments: + Remove comments from yaml. Defaults to false. ---style - yaml styles to apply. May be 'TaggedStyle', 'DoubleQuotedStyle', 'LiteralStyle', 'FoldedStyle', 'FlowStyle'. +--style: + yaml styles to apply. May be 'TaggedStyle', 'DoubleQuotedStyle', + 'LiteralStyle', 'FoldedStyle', 'FlowStyle'. ``` + + ### Examples diff --git a/documentation/content/en/reference/cli/pkg/diff/_index.md b/documentation/content/en/reference/cli/pkg/diff/_index.md index d14fccd88a..2889c48500 100644 --- a/documentation/content/en/reference/cli/pkg/diff/_index.md +++ b/documentation/content/en/reference/cli/pkg/diff/_index.md @@ -73,6 +73,10 @@ VERSION: # Show changes using the diff command with recursive options. kpt pkg diff @master --diff-tool meld --diff-tool-opts "-r" + +--debug: + When true, prints additional debug information and does not delete the + staged package directories used for comparison. Defaults to false. ``` #### Environment Variables diff --git a/documentation/content/en/reference/cli/pkg/tree/_index.md b/documentation/content/en/reference/cli/pkg/tree/_index.md index 700b388a8c..d9a974ada0 100644 --- a/documentation/content/en/reference/cli/pkg/tree/_index.md +++ b/documentation/content/en/reference/cli/pkg/tree/_index.md @@ -21,15 +21,17 @@ description: | kpt pkg tree [DIR] ``` - - #### Args ```shell DIR: - Path to a directory containing KRM resource(s). Defaults to the current working directory. + Path to a local package directory. Defaults to the current directory. + Displays KRM resources with their Kind and Name, and non-KRM text files + as plain filenames. Dotfiles and symlinks are excluded. ``` + + ### Examples diff --git a/internal/docs/generated/fndocs/docs.go b/internal/docs/generated/fndocs/docs.go index d2cc2b3f74..5917cbc067 100644 --- a/internal/docs/generated/fndocs/docs.go +++ b/internal/docs/generated/fndocs/docs.go @@ -58,6 +58,11 @@ Args: Flags: + --allow-alpha-wasm: + Allow alpha wasm functions to be run. If true, you can specify a wasm image + with --image flag or a path to a wasm file (must have the .wasm file + extension) with --exec flag. Defaults to false. + --as-current-user: Use the ` + "`" + `uid` + "`" + ` and ` + "`" + `gid` + "`" + ` of the kpt process for container function execution. By default, container function is executed as ` + "`" + `nobody` + "`" + ` user. You may want to use @@ -78,6 +83,9 @@ Flags: --fn-config: Path to the file containing ` + "`" + `functionConfig` + "`" + ` for the function. + The fn-config resource is used to configure the function but is not + treated as an input resource. The function will not modify the fn-config + file, even if it resides inside the package directory. --image, i: Container image of the function to execute e.g. ` + "`" + `ghcr.io/kptdev/krm-functions-catalog/set-namespace:latest` + "`" + `. @@ -110,7 +118,7 @@ Flags: --match-api-version: Select resources matching the given apiVersion. - --match-kind + --match-kind: Select resources matching the given kind. --match-name: @@ -119,6 +127,38 @@ Flags: --match-namespace: Select resources matching the given namespace. + --match-annotations: + Select resources matching the given annotations. The value should be in + ` + "`" + `key=value` + "`" + ` format. Can be specified multiple times to match multiple + annotations. + + --match-labels: + Select resources matching the given labels. The value should be in + ` + "`" + `key=value` + "`" + ` format. Can be specified multiple times to match multiple + labels. + + --exclude-api-version: + Exclude resources matching the given apiVersion. + + --exclude-kind: + Exclude resources matching the given kind. + + --exclude-name: + Exclude resources matching the given name. + + --exclude-namespace: + Exclude resources matching the given namespace. + + --exclude-annotations: + Exclude resources matching the given annotations. The value should be in + ` + "`" + `key=value` + "`" + ` format. Can be specified multiple times to match multiple + annotations. + + --exclude-labels: + Exclude resources matching the given labels. The value should be in + ` + "`" + `key=value` + "`" + ` format. Can be specified multiple times to match multiple + labels. + --mount: List of storage options to enable reading from the local filesytem. By default, container functions can not access the local filesystem. It accepts the same options @@ -256,6 +296,11 @@ Args: Flags: + --allow-alpha-wasm: + Allow wasm to be used during pipeline execution. When enabled, function + images that are wasm modules will be executed using the wasm runtime + instead of a container runtime. Defaults to false. + --allow-exec: Allow executable binaries to run as function. Note that executable binaries can perform privileged operations on your system, so ensure that binaries diff --git a/internal/docs/generated/livedocs/docs.go b/internal/docs/generated/livedocs/docs.go index 81eed54988..bbf8ae637f 100644 --- a/internal/docs/generated/livedocs/docs.go +++ b/internal/docs/generated/livedocs/docs.go @@ -89,6 +89,15 @@ Flags: for all resources. Default is ` + "`" + `false` + "`" + `. Does not apply for the ` + "`" + `table` + "`" + ` output format. + + --status-policy: + Determines which status information should be saved in the inventory + (if compatible). The available options are: + + * all: Save status for all resources in the inventory. + * none: Do not save any status information in the inventory. + + The default value is ` + "`" + `all` + "`" + `. ` var ApplyExamples = ` # apply resources in the current directory @@ -148,6 +157,15 @@ Flags: for all resources. Default is ` + "`" + `false` + "`" + `. Does not apply for the ` + "`" + `table` + "`" + ` output format. + + --status-policy: + Determines which status information should be saved in the inventory + (if compatible). The available options are: + + * all: Save status for all resources in the inventory. + * none: Do not save any status information in the inventory. + + The default value is ` + "`" + `all` + "`" + `. ` var DestroyExamples = ` # remove all resources in the current package from the cluster. @@ -185,6 +203,9 @@ Flags: in the package belong in the same namespace. If they do, that namespace will be used. If they do not, the namespace in the user's context will be chosen. + --quiet: + If true, do not print output message for initialization. Defaults to false. + --rg-file: The name used for the file created for the ResourceGroup CR. Defaults to 'resourcegroup.yaml'. @@ -235,6 +256,10 @@ Flags: The namespace for the ResourceGroup resource that contains the inventory for the package. If not provided, it defaults to the same namespace as the existing inventory object. + + --rg-file: + The file path to the ResourceGroup object. Defaults to + 'resourcegroup.yaml'. ` var MigrateExamples = ` # Migrate the package in the current directory. diff --git a/internal/docs/generated/pkgdocs/docs.go b/internal/docs/generated/pkgdocs/docs.go index f41f43cea0..0921f9cc82 100644 --- a/internal/docs/generated/pkgdocs/docs.go +++ b/internal/docs/generated/pkgdocs/docs.go @@ -18,6 +18,25 @@ Args: package files: KRM resources (YAML/JSON) are formatted by default, and non-KRM text files (e.g., README.md) are shown as raw content. Binary files are skipped. Defaults to the current directory. + +Flags: + + --annotate: + Annotate resources with their file origins. Defaults to false. + + --format: + Format resource config YAML before printing (reorders fields to canonical + order). Defaults to true. + + --recurse-subpackages, -R: + Print resources recursively in all the nested subpackages. Defaults to true. + + --strip-comments: + Remove comments from yaml. Defaults to false. + + --style: + yaml styles to apply. May be 'TaggedStyle', 'DoubleQuotedStyle', + 'LiteralStyle', 'FoldedStyle', 'FlowStyle'. ` var CatExamples = ` # Print all package contents from current directory. @@ -73,6 +92,10 @@ Flags: # Show changes using the diff command with recursive options. kpt pkg diff @master --diff-tool meld --diff-tool-opts "-r" + + --debug: + When true, prints additional debug information and does not delete the + staged package directories used for comparison. Defaults to false. Environment Variables: @@ -211,6 +234,13 @@ var InitExamples = ` var TreeShort = `Display resources, files and packages in a tree structure.` var TreeLong = ` kpt pkg tree [DIR] + +Args: + + DIR: + Path to a local package directory. Defaults to the current directory. + Displays KRM resources with their Kind and Name, and non-KRM text files + as plain filenames. Dotfiles and symlinks are excluded. ` var TreeExamples = ` # Show resources in the current directory. diff --git a/run/run.go b/run/run.go index 2024c227e4..04d3ed0db3 100644 --- a/run/run.go +++ b/run/run.go @@ -35,6 +35,50 @@ import ( var pgr []string +// usageTemplate is a custom Cobra usage template that suppresses the +// auto-generated local Flags section for commands whose Long description +// already documents all flags (detected by the presence of "Flags:" in the +// Long text). Commands without a "Flags:" section in their Long description +// (e.g. group commands, commands with no flags) continue to show the default +// Cobra flag table. +// +// This template is based on cobra.Command's defaultUsageTemplate from: +// https://github.com/spf13/cobra/blob/main/command.go +// +// The only difference from the Cobra default is that the local Flags section +// is conditionally rendered: it is suppressed when the Long description +// already contains a "Flags:" section, avoiding duplicate flag documentation. +const usageTemplate = `Usage:{{if .Runnable}} + {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}} + {{.CommandPath}} [command]{{end}}{{if gt (len .Aliases) 0}} + +Aliases: + {{.NameAndAliases}}{{end}}{{if .HasExample}} + +Examples: +{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}} + +Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}} + {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}} + +{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}} + {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}} + +Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}} + {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if not (contains .Long "Flags:")}}{{if .HasAvailableLocalFlags}} + +Flags: +{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{end}}{{if .HasAvailableInheritedFlags}} + +Global Flags: +{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}} + +Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}} + {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}} + +Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}} +` + func GetMain(ctx context.Context) *cobra.Command { os.Setenv(commandutil.EnableAlphaCommmandsEnvName, "true") cmd := &cobra.Command{ @@ -59,6 +103,11 @@ func GetMain(ctx context.Context) *cobra.Command { cmd.PersistentFlags().AddGoFlagSet(flag.CommandLine) + // Register a "contains" template function for use in the custom usage + // template below. + cobra.AddTemplateFunc("contains", strings.Contains) + cmd.SetUsageTemplate(usageTemplate) + cmd.PersistentFlags().BoolVar(&printer.TruncateOutput, "truncate-output", true, "Enable the truncation for output") // wire the global printer