github
/
k3s
mirror of https://github.com/k3s-io/k3s
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Make kubectl help strings consistent

pull/6/head
joe2far 2016-06-07 18:38:04 +01:00
parent 302eae213d
commit 25b4341dc7
26 changed files with 50 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/devel/kubectl-conventions.md
View File

@ -125,6 +125,9 @@ flags and separate help that is tailored for the particular usage.
* Flag names and single-character aliases should have the same meaning across
all commands
* Flag descriptions should start with an uppercase letter and not have a
period at the end of a sentence
* Command-line flags corresponding to API fields should accept API enums
exactly (e.g., `--restart=Always`)
@ -233,9 +236,16 @@ resources in other commands
an exhaustive specification
* Short should contain a one-line explanation of what the command does
* Short descriptions should start with an uppercase case letter and not
have a period at the end of a sentence
* Short descriptions should (if possible) start with a first person
(singular present tense) verb
* Long may contain multiple lines, including additional information about
input, output, commonly used flags, etc.
* Long descriptions should use proper grammar, start with an uppercase
letter and have a period at the end of a sentence
* Example should contain examples
* Start commands with `$`

18
pkg/client/unversioned/clientcmd/overrides.go
View File

@ -124,12 +124,12 @@ const (
// RecommendedAuthOverrideFlags is a convenience method to return recommended flag names prefixed with a string of your choosing
func RecommendedAuthOverrideFlags(prefix string) AuthOverrideFlags {
return AuthOverrideFlags{
ClientCertificate: FlagInfo{prefix + FlagCertFile, "", "", "Path to a client certificate file for TLS."},
ClientKey: FlagInfo{prefix + FlagKeyFile, "", "", "Path to a client key file for TLS."},
Token: FlagInfo{prefix + FlagBearerToken, "", "", "Bearer token for authentication to the API server."},
Impersonate: FlagInfo{prefix + FlagImpersonate, "", "", "Username to impersonate for the operation."},
Username: FlagInfo{prefix + FlagUsername, "", "", "Username for basic authentication to the API server."},
Password: FlagInfo{prefix + FlagPassword, "", "", "Password for basic authentication to the API server."},
ClientCertificate: FlagInfo{prefix + FlagCertFile, "", "", "Path to a client certificate file for TLS"},
ClientKey: FlagInfo{prefix + FlagKeyFile, "", "", "Path to a client key file for TLS"},
Token: FlagInfo{prefix + FlagBearerToken, "", "", "Bearer token for authentication to the API server"},
Impersonate: FlagInfo{prefix + FlagImpersonate, "", "", "Username to impersonate for the operation"},
Username: FlagInfo{prefix + FlagUsername, "", "", "Username for basic authentication to the API server"},
Password: FlagInfo{prefix + FlagPassword, "", "", "Password for basic authentication to the API server"},
}
}
@ -138,8 +138,8 @@ func RecommendedClusterOverrideFlags(prefix string) ClusterOverrideFlags {
return ClusterOverrideFlags{
APIServer: FlagInfo{prefix + FlagAPIServer, "", "", "The address and port of the Kubernetes API server"},
APIVersion: FlagInfo{prefix + FlagAPIVersion, "", "", "DEPRECATED: The API version to use when talking to the server"},
CertificateAuthority: FlagInfo{prefix + FlagCAFile, "", "", "Path to a cert. file for the certificate authority."},
InsecureSkipTLSVerify: FlagInfo{prefix + FlagInsecure, "", "false", "If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure."},
CertificateAuthority: FlagInfo{prefix + FlagCAFile, "", "", "Path to a cert. file for the certificate authority"},
InsecureSkipTLSVerify: FlagInfo{prefix + FlagInsecure, "", "false", "If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure"},
}
}
@ -158,7 +158,7 @@ func RecommendedContextOverrideFlags(prefix string) ContextOverrideFlags {
return ContextOverrideFlags{
ClusterName: FlagInfo{prefix + FlagClusterName, "", "", "The name of the kubeconfig cluster to use"},
AuthInfoName: FlagInfo{prefix + FlagAuthInfoName, "", "", "The name of the kubeconfig user to use"},
Namespace: FlagInfo{prefix + FlagNamespace, "", "", "If present, the namespace scope for this CLI request."},
Namespace: FlagInfo{prefix + FlagNamespace, "", "", "If present, the namespace scope for this CLI request"},
}
}

2
pkg/kubectl/cmd/apiversions.go
View File

@ -33,7 +33,7 @@ func NewCmdApiVersions(f *cmdutil.Factory, out io.Writer) *cobra.Command {
Use: "api-versions",
// apiversions is deprecated.
Aliases: []string{"apiversions"},
Short: "Print the supported API versions on the server, in the form of \"group/version\".",
Short: "Print the supported API versions on the server, in the form of \"group/version\"",
Run: func(cmd *cobra.Command, args []string) {
err := RunApiVersions(f, out)
cmdutil.CheckErr(err)

2
pkg/kubectl/cmd/attach.go
View File

@ -59,7 +59,7 @@ func NewCmdAttach(f *cmdutil.Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer)
}
cmd := &cobra.Command{
Use: "attach POD -c CONTAINER",
Short: "Attach to a running container.",
Short: "Attach to a running container",
Long: "Attach to a process that is already running inside an existing container.",
Example: attach_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/clusterinfo_dump.go
View File

@ -34,7 +34,7 @@ import (
func NewCmdClusterInfoDump(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "dump",
Short: "Dump lots of relevant info for debugging and diagnosis.",
Short: "Dump lots of relevant info for debugging and diagnosis",
Long: dumpLong,
Example: dumpExample,
Run: func(cmd *cobra.Command, args []string) {

4
pkg/kubectl/cmd/config/config.go
View File

@ -33,8 +33,8 @@ func NewCmdConfig(pathOptions *clientcmd.PathOptions, out io.Writer) *cobra.Comm
cmd := &cobra.Command{
Use: "config SUBCOMMAND",
Short: "config modifies kubeconfig files",
Long: `config modifies kubeconfig files using subcommands like "kubectl config set current-context my-context"
Short: "Modify kubeconfig files",
Long: `Modify kubeconfig files using subcommands like "kubectl config set current-context my-context"
The loading order follows these rules:
1. If the --` + pathOptions.ExplicitFileFlag + ` flag is set, then only that file is loaded. The flag may only be set once and no merging takes place.

4
pkg/kubectl/cmd/config/view.go
View File

@ -42,7 +42,7 @@ type ViewOptions struct {
var (
view_long = dedent.Dedent(`
Displays merged kubeconfig settings or a specified kubeconfig file.
Display merged kubeconfig settings or a specified kubeconfig file.
You can use --output jsonpath={...} to extract specific values using a jsonpath expression.`)
view_example = dedent.Dedent(`
@ -60,7 +60,7 @@ func NewCmdConfigView(out io.Writer, ConfigAccess clientcmd.ConfigAccess) *cobra
cmd := &cobra.Command{
Use: "view",
Short: "Displays merged kubeconfig settings or a specified kubeconfig file.",
Short: "Display merged kubeconfig settings or a specified kubeconfig file",
Long: view_long,
Example: view_example,
Run: func(cmd *cobra.Command, args []string) {

4
pkg/kubectl/cmd/create_configmap.go
View File

@ -48,7 +48,7 @@ var (
# Create a new configmap named my-config with specified keys instead of names on disk
kubectl create configmap my-config --from-file=key1=/path/to/bar/file1.txt --from-file=key2=/path/to/bar/file2.txt
# Create a new configMap named my-config with key1=config1 and key2=config2
# Create a new configmap named my-config with key1=config1 and key2=config2
kubectl create configmap my-config --from-literal=key1=config1 --from-literal=key2=config2`)
)
@ -56,7 +56,7 @@ var (
func NewCmdCreateConfigMap(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "configmap NAME [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run]",
Short: "Create a configMap from a local file, directory or literal value.",
Short: "Create a configmap from a local file, directory or literal value",
Long: configMapLong,
Example: configMapExample,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/create_namespace.go
View File

@ -41,7 +41,7 @@ func NewCmdCreateNamespace(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command
cmd := &cobra.Command{
Use: "namespace NAME [--dry-run]",
Aliases: []string{"ns"},
Short: "Create a namespace with the specified name.",
Short: "Create a namespace with the specified name",
Long: namespaceLong,
Example: namespaceExample,
Run: func(cmd *cobra.Command, args []string) {

8
pkg/kubectl/cmd/create_secret.go
View File

@ -31,7 +31,7 @@ import (
func NewCmdCreateSecret(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "secret",
Short: "Create a secret using specified subcommand.",
Short: "Create a secret using specified subcommand",
Long: "Create a secret using specified subcommand.",
Run: func(cmd *cobra.Command, args []string) {
cmd.Help()
@ -73,7 +73,7 @@ var (
func NewCmdCreateSecretGeneric(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "generic NAME [--type=string] [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run]",
Short: "Create a secret from a local file, directory or literal value.",
Short: "Create a secret from a local file, directory or literal value",
Long: secretLong,
Example: secretExample,
Run: func(cmd *cobra.Command, args []string) {
@ -141,7 +141,7 @@ var (
func NewCmdCreateSecretDockerRegistry(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "docker-registry NAME --docker-username=user --docker-password=password --docker-email=email [--docker-server=string] [--from-literal=key1=value1] [--dry-run]",
Short: "Create a secret for use with a Docker registry.",
Short: "Create a secret for use with a Docker registry",
Long: secretForDockerRegistryLong,
Example: secretForDockerRegistryExample,
Run: func(cmd *cobra.Command, args []string) {
@ -212,7 +212,7 @@ var (
func NewCmdCreateSecretTLS(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "tls NAME --cert=path/to/cert/file --key=path/to/key/file [--dry-run]",
Short: "Create a TLS secret.",
Short: "Create a TLS secret",
Long: secretForTLSLong,
Example: secretForTLSExample,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/create_serviceaccount.go
View File

@ -41,7 +41,7 @@ func NewCmdCreateServiceAccount(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Com
cmd := &cobra.Command{
Use: "serviceaccount NAME [--dry-run]",
Aliases: []string{"sa"},
Short: "Create a service account with the specified name.",
Short: "Create a service account with the specified name",
Long: serviceAccountLong,
Example: serviceAccountExample,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/delete.go
View File

@ -87,7 +87,7 @@ func NewCmdDelete(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "delete ([-f FILENAME] | TYPE [(NAME | -l label | --all)])",
Short: "Delete resources by filenames, stdin, resources and names, or by resources and label selector.",
Short: "Delete resources by filenames, stdin, resources and names, or by resources and label selector",
Long: delete_long,
Example: delete_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/exec.go
View File

@ -59,7 +59,7 @@ func NewCmdExec(f *cmdutil.Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer) *
}
cmd := &cobra.Command{
Use: "exec POD [-c CONTAINER] -- COMMAND [args...]",
Short: "Execute a command in a container.",
Short: "Execute a command in a container",
Long: "Execute a command in a container.",
Example: exec_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/explain.go
View File

@ -46,7 +46,7 @@ var (
func NewCmdExplain(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "explain RESOURCE",
Short: "Documentation of resources.",
Short: "Documentation of resources",
Long: explainLong,
Example: explainExamples,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/logs.go
View File

@ -74,7 +74,7 @@ func NewCmdLogs(f *cmdutil.Factory, out io.Writer) *cobra.Command {
o := &LogsOptions{}
cmd := &cobra.Command{
Use: "logs [-f] [-p] POD [-c CONTAINER]",
Short: "Print the logs for a container in a pod.",
Short: "Print the logs for a container in a pod",
Long: "Print the logs for a container in a pod. If the pod has only one container, the container name is optional.",
Example: logs_example,
PreRun: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/patch.go
View File

@ -83,7 +83,7 @@ func NewCmdPatch(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "patch (-f FILENAME | TYPE NAME) -p PATCH",
Short: "Update field(s) of a resource using strategic merge patch.",
Short: "Update field(s) of a resource using strategic merge patch",
Long: patch_long,
Example: patch_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/portforward.go
View File

@ -50,7 +50,7 @@ var (
func NewCmdPortForward(f *cmdutil.Factory, cmdOut, cmdErr io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]",
Short: "Forward one or more local ports to a pod.",
Short: "Forward one or more local ports to a pod",
Long: "Forward one or more local ports to a pod.",
Example: portforward_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/replace.go
View File

@ -69,7 +69,7 @@ func NewCmdReplace(f *cmdutil.Factory, out io.Writer) *cobra.Command {
Use: "replace -f FILENAME",
// update is deprecated.
Aliases: []string{"update"},
Short: "Replace a resource by filename or stdin.",
Short: "Replace a resource by filename or stdin",
Long: replace_long,
Example: replace_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/rollingupdate.go
View File

@ -82,7 +82,7 @@ func NewCmdRollingUpdate(f *cmdutil.Factory, out io.Writer) *cobra.Command {
Use: "rolling-update OLD_CONTROLLER_NAME ([NEW_CONTROLLER_NAME] --image=NEW_CONTAINER_IMAGE | -f NEW_CONTROLLER_SPEC)",
// rollingupdate is deprecated.
Aliases: []string{"rollingupdate"},
Short: "Perform a rolling update of the given ReplicationController.",
Short: "Perform a rolling update of the given ReplicationController",
Long: rollingUpdate_long,
Example: rollingUpdate_example,
Run: func(cmd *cobra.Command, args []string) {

4
pkg/kubectl/cmd/rollout/rollout.go
View File

@ -26,7 +26,7 @@ import (
var (
rollout_long = dedent.Dedent(`
Manages a deployment using subcommands like "kubectl rollout undo deployment/abc"`)
Manage a deployment using subcommands like "kubectl rollout undo deployment/abc"`)
rollout_example = dedent.Dedent(`
# Rollback to the previous deployment
kubectl rollout undo deployment/abc`)
@ -40,7 +40,7 @@ func NewCmdRollout(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "rollout SUBCOMMAND",
Short: "rollout manages a deployment",
Short: "Manage a deployment rollout",
Long: rollout_long,
Example: rollout_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/rollout/rollout_history.go
View File

@ -51,7 +51,7 @@ func NewCmdRolloutHistory(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "history (TYPE NAME | TYPE/NAME) [flags]",
Short: "view rollout history",
Short: "View rollout history",
Long: history_long,
Example: history_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/rollout/rollout_undo.go
View File

@ -60,7 +60,7 @@ func NewCmdRolloutUndo(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "undo (TYPE NAME | TYPE/NAME) [flags]",
Short: "undoes a previous rollout",
Short: "Undo a previous rollout",
Long: undo_long,
Example: undo_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/run.go
View File

@ -77,7 +77,7 @@ func NewCmdRun(f *cmdutil.Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer) *c
Use: "run NAME --image=image [--env=\"key=value\"] [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json] [--command] -- [COMMAND] [args...]",
// run-container is deprecated
Aliases: []string{"run-container"},
Short: "Run a particular image on the cluster.",
Short: "Run a particular image on the cluster",
Long: run_long,
Example: run_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/scale.go
View File

@ -70,7 +70,7 @@ func NewCmdScale(f *cmdutil.Factory, out io.Writer) *cobra.Command {
Use: "scale [--resource-version=version] [--current-replicas=count] --replicas=COUNT (-f FILENAME | TYPE NAME)",
// resize is deprecated
Aliases: []string{"resize"},
Short: "Set a new size for a Deployment, ReplicaSet, Replication Controller, or Job.",
Short: "Set a new size for a Deployment, ReplicaSet, Replication Controller, or Job",
Long: scale_long,
Example: scale_example,
Run: func(cmd *cobra.Command, args []string) {

2
pkg/kubectl/cmd/stop.go
View File

@ -62,7 +62,7 @@ func NewCmdStop(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "stop (-f FILENAME | TYPE (NAME | -l label | --all))",
Short: "Deprecated: Gracefully shut down a resource by name or filename.",
Short: "Deprecated: Gracefully shut down a resource by name or filename",
Long: stop_long,
Example: stop_example,
Deprecated: fmt.Sprintf("use %q instead.", "delete"),

2
pkg/kubectl/cmd/version.go
View File

@ -28,7 +28,7 @@ import (
func NewCmdVersion(f *cmdutil.Factory, out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "version",
Short: "Print the client and server version information.",
Short: "Print the client and server version information",
Run: func(cmd *cobra.Command, args []string) {
err := RunVersion(f, out, cmd)
cmdutil.CheckErr(err)