Merge pull request #12813 from JanetKuo/kubectl-deprecate-t

Deprecated -t for --template to make it --tty

Godeps/Godeps.json

@@ -520,7 +520,7 @@
 		},
 		{
 			"ImportPath": "github.com/spf13/pflag",
-			"Rev": "112aaa578dfdd0e913663b05153be974bd72497a"
+			"Rev": "8e7dc108ab3a1ab6ce6d922bbaff5657b88e8e49"
 		},
 		{
 			"ImportPath": "github.com/stretchr/objx",

Godeps/_workspace/src/github.com/spf13/pflag/README.md

@@ -216,6 +216,25 @@ func aliasNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
 myFlagSet.SetNormalizeFunc(aliasNormalizeFunc)
 ```
 
+## Deprecating a flag or its shorthand 
+It is possible to deprecate a flag, or just its shorthand. Deprecating a flag/shorthand hides it from help text and prints a usage message when the deprecated flag/shorthand is used. 
+
+**Example #1**: You want to deprecate a flag named "badflag" as well as inform the users what flag they should use instead. 
+```go
+// deprecate a flag by specifying its name and a usage message 
+flags.MarkDeprecated("badflag", "please use --good-flag instead")
+```
+This hides "badflag" from help text, and prints `Flag --badflag has been deprecated, please use --good-flag instead` when "badflag" is used. 
+
+**Example #2**: You want to keep a flag name "noshorthandflag" but deprecate its shortname "n". 
+```go
+// deprecate a flag shorthand by specifying its flag name and a usage message 
+flags.MarkShorthandDeprecated("noshorthandflag", "please use --noshorthandflag only")
+```
+This hides the shortname "n" from help text, and prints `Flag shorthand -n has been deprecated, please use --noshorthandflag only` when the shorthand "n" is used. 
+
+Note that usage message is essential here, and it should not be empty. 
+
 ## More info
 
 You can see the full reference documentation of the pflag package

Godeps/_workspace/src/github.com/spf13/pflag/flag.go

@@ -149,15 +149,16 @@ type FlagSet struct {
 
 // A Flag represents the state of a flag.
 type Flag struct {
-	Name        string              // name as it appears on command line
+	Name                string              // name as it appears on command line
-	Shorthand   string              // one-letter abbreviated flag
+	Shorthand           string              // one-letter abbreviated flag
-	Usage       string              // help message
+	Usage               string              // help message
-	Value       Value               // value as set
+	Value               Value               // value as set
-	DefValue    string              // default value (as text); for usage message
+	DefValue            string              // default value (as text); for usage message
-	Changed     bool                // If the user set the value (or if left to default)
+	Changed             bool                // If the user set the value (or if left to default)
-	NoOptDefVal string              //default value (as text); if the flag is on the command line without any options
+	NoOptDefVal         string              //default value (as text); if the flag is on the command line without any options
-	Deprecated  string              // If this flag is deprecated, this string is the new or now thing to use
+	Deprecated          string              // If this flag is deprecated, this string is the new or now thing to use
-	Annotations map[string][]string // used by cobra.Command  bash autocomple code
+	ShorthandDeprecated string              // If the shorthand of this flag is deprecated, this string is the new or now thing to use
+	Annotations         map[string][]string // used by cobra.Command  bash autocomple code
 }
 
 // Value is the interface to the dynamic value stored in a flag.
@@ -298,10 +299,28 @@ func (f *FlagSet) MarkDeprecated(name string, usageMessage string) error {
 	if flag == nil {
 		return fmt.Errorf("flag %q does not exist", name)
 	}
+	if len(usageMessage) == 0 {
+		return fmt.Errorf("deprecated message for flag %q must be set", name)
+	}
 	flag.Deprecated = usageMessage
 	return nil
 }
 
+// Mark the shorthand of a flag deprecated in your program. It will
+// continue to function but will not show up in help or usage messages. Using
+// this flag will also print the given usageMessage.
+func (f *FlagSet) MarkShorthandDeprecated(name string, usageMessage string) error {
+	flag := f.Lookup(name)
+	if flag == nil {
+		return fmt.Errorf("flag %q does not exist", name)
+	}
+	if len(usageMessage) == 0 {
+		return fmt.Errorf("deprecated message for flag %q must be set", name)
+	}
+	flag.ShorthandDeprecated = usageMessage
+	return nil
+}
+
 // Lookup returns the Flag structure of the named command-line flag,
 // returning nil if none exists.
 func Lookup(name string) *Flag {
@@ -379,7 +398,7 @@ func (f *FlagSet) FlagUsages() string {
 			return
 		}
 		format := ""
-		if len(flag.Shorthand) > 0 {
+		if len(flag.Shorthand) > 0 && len(flag.ShorthandDeprecated) == 0 {
 			format = "  -%s, --%s"
 		} else {
 			format = "   %s   --%s"
@@ -397,7 +416,11 @@ func (f *FlagSet) FlagUsages() string {
 			format = format + "]"
 		}
 		format = format + ": %s\n"
-		fmt.Fprintf(x, format, flag.Shorthand, flag.Name, flag.DefValue, flag.Usage)
+		shorthand := flag.Shorthand
+		if len(flag.ShorthandDeprecated) > 0 {
+			shorthand = ""
+		}
+		fmt.Fprintf(x, format, shorthand, flag.Name, flag.DefValue, flag.Usage)
 	})
 
 	return x.String()
@@ -586,9 +609,21 @@ func (f *FlagSet) setFlag(flag *Flag, value string, origArg string) error {
 	if len(flag.Deprecated) > 0 {
 		fmt.Fprintf(os.Stderr, "Flag --%s has been deprecated, %s\n", flag.Name, flag.Deprecated)
 	}
+	if len(flag.ShorthandDeprecated) > 0 && containsShorthand(origArg, flag.Shorthand) {
+		fmt.Fprintf(os.Stderr, "Flag shorthand -%s has been deprecated, %s\n", flag.Shorthand, flag.ShorthandDeprecated)
+	}
 	return nil
 }
 
+func containsShorthand(arg, shorthand string) bool {
+	// filter out flags --<flag_name>
+	if strings.HasPrefix(arg, "-") {
+		return false
+	}
+	arg = strings.SplitN(arg, "=", 2)[0]
+	return strings.Contains(arg, shorthand)
+}
+
 func (f *FlagSet) parseLongArg(s string, args []string) (a []string, err error) {
 	a = args
 	name := s[2:]

Godeps/_workspace/src/github.com/spf13/pflag/flag_test.go

@@ -729,6 +729,21 @@ func TestDeprecatedFlagInDocs(t *testing.T) {
 	}
 }
 
+func TestDeprecatedFlagShorthandInDocs(t *testing.T) {
+	f := NewFlagSet("bob", ContinueOnError)
+	name := "noshorthandflag"
+	f.BoolP(name, "n", true, "always true")
+	f.MarkShorthandDeprecated("noshorthandflag", fmt.Sprintf("use --%s instead", name))
+
+	out := new(bytes.Buffer)
+	f.SetOutput(out)
+	f.PrintDefaults()
+
+	if strings.Contains(out.String(), "-n,") {
+		t.Errorf("found deprecated flag shorthand in usage!")
+	}
+}
+
 func parseReturnStderr(t *testing.T, f *FlagSet, args []string) (string, error) {
 	oldStderr := os.Stderr
 	r, w, _ := os.Pipe()
@@ -768,6 +783,24 @@ func TestDeprecatedFlagUsage(t *testing.T) {
 	}
 }
 
+func TestDeprecatedFlagShorthandUsage(t *testing.T) {
+	f := NewFlagSet("bob", ContinueOnError)
+	name := "noshorthandflag"
+	f.BoolP(name, "n", true, "always true")
+	usageMsg := fmt.Sprintf("use --%s instead", name)
+	f.MarkShorthandDeprecated(name, usageMsg)
+
+	args := []string{"-n"}
+	out, err := parseReturnStderr(t, f, args)
+	if err != nil {
+		t.Fatal("expected no error; got ", err)
+	}
+
+	if !strings.Contains(out, usageMsg) {
+		t.Errorf("usageMsg not printed when using a deprecated flag!")
+	}
+}
+
 func TestDeprecatedFlagUsageNormalized(t *testing.T) {
 	f := NewFlagSet("bob", ContinueOnError)
 	f.Bool("bad-double_flag", true, "always true")

docs/man/man1/kubectl-get.1

@@ -201,7 +201,7 @@ $ kubectl get \-o json pod web\-pod\-13je7
 $ kubectl get \-f pod.yaml \-o json
 
 # Return only the phase value of the specified pod.
-$ kubectl get \-o template web\-pod\-13je7 \-\-template={{.status.phase}} \-\-api\-version=v1
+$ kubectl get \-o template pod/web\-pod\-13je7 \-\-template={{.status.phase}} \-\-api\-version=v1
 
 # List all replication controllers and services together in ps output format.
 $ kubectl get rc,services

docs/user-guide/kubectl/kubectl_annotate.md

@@ -91,7 +91,7 @@ $ kubectl annotate pods foo description-
       --resource-version="": If non-empty, the annotation update will only succeed if this is the current resource-version for the object. Only valid when specifying a single resource.
   -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.)
       --sort-by="": If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.
-  -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
+      --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
 ```
 
 ### Options inherited from parent commands

docs/user-guide/kubectl/kubectl_config_view.md

@@ -69,7 +69,7 @@ $ kubectl config view -o template --template='{{range .users}}{{ if eq .name "e2
       --raw[=false]: display raw byte data
   -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.)
       --sort-by="": If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.
-  -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
+      --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
 ```
 
 ### Options inherited from parent commands
@@ -105,7 +105,7 @@ $ kubectl config view -o template --template='{{range .users}}{{ if eq .name "e2
 
 * [kubectl config](kubectl_config.md)	 - config modifies kubeconfig files
 
-###### Auto generated by spf13/cobra at 2015-08-20 22:01:12.479773286 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-08-21 17:04:52.393094162 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_config_view.md?pixel)]()

docs/user-guide/kubectl/kubectl_expose.md

@@ -87,7 +87,7 @@ $ kubectl expose rc streamer --port=4100 --protocol=udp --name=video-stream
   -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.)
       --sort-by="": If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.
       --target-port="": Name or number for the port on the container that the service should direct traffic to. Optional.
-  -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
+      --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
       --type="": Type for this service: ClusterIP, NodePort, or LoadBalancer. Default is 'ClusterIP' unless --create-external-load-balancer is specified.
 ```
 
@@ -124,7 +124,7 @@ $ kubectl expose rc streamer --port=4100 --protocol=udp --name=video-stream
 
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-08-20 23:09:42.260392956 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-08-21 17:04:52.392625597 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_expose.md?pixel)]()

docs/user-guide/kubectl/kubectl_get.md

@@ -71,7 +71,7 @@ $ kubectl get -o json pod web-pod-13je7
 $ kubectl get -f pod.yaml -o json
 
 # Return only the phase value of the specified pod.
-$ kubectl get -o template web-pod-13je7 --template={{.status.phase}} --api-version=v1
+$ kubectl get -o template pod/web-pod-13je7 --template={{.status.phase}} --api-version=v1
 
 # List all replication controllers and services together in ps output format.
 $ kubectl get rc,services
@@ -93,7 +93,7 @@ $ kubectl get rc/web service/frontend pods/web-pod-13je7
   -l, --selector="": Selector (label query) to filter on
   -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.)
       --sort-by="": If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.
-  -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
+      --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
   -w, --watch[=false]: After listing/getting the requested object, watch for changes.
       --watch-only[=false]: Watch for changes to the requested object(s), without listing/getting first.
 ```
@@ -131,7 +131,7 @@ $ kubectl get rc/web service/frontend pods/web-pod-13je7
 
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-08-20 22:01:12.475080519 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-08-21 17:04:52.389792296 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_get.md?pixel)]()

docs/user-guide/kubectl/kubectl_label.md

@@ -85,7 +85,7 @@ $ kubectl label pods foo bar-
   -l, --selector="": Selector (label query) to filter on
   -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.)
       --sort-by="": If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.
-  -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
+      --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
 ```
 
 ### Options inherited from parent commands
@@ -121,7 +121,7 @@ $ kubectl label pods foo bar-
 
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-08-20 22:01:12.478848071 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-08-21 17:04:52.392784742 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_label.md?pixel)]()

docs/user-guide/kubectl/kubectl_rolling-update.md

@@ -81,7 +81,7 @@ $ kubectl rolling-update frontend --image=image:v2
       --rollback[=false]: If true, this is a request to abort an existing rollout that is partially rolled out. It effectively reverses current and next and runs a rollout
   -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.)
       --sort-by="": If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.
-  -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
+      --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
       --timeout=5m0s: Max time to wait for a replication controller to update before giving up. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
       --update-period=1m0s: Time to wait between updating pods. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
 ```
@@ -119,7 +119,7 @@ $ kubectl rolling-update frontend --image=image:v2
 
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-08-20 22:01:12.477073189 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-08-21 17:04:52.390982319 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_rolling-update.md?pixel)]()

docs/user-guide/kubectl/kubectl_run.md

@@ -91,7 +91,7 @@ $ kubectl run nginx --image=nginx --command -- <cmd> <arg1> ... <argN>
   -a, --show-all[=false]: When printing, show all resources (default hide terminated pods.)
       --sort-by="": If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.
   -i, --stdin[=false]: Keep stdin open on the container(s) in the pod, even if nothing is attached.
-  -t, --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
+      --template="": Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]
       --tty[=false]: Allocated a TTY for each container in the pod.  Because -t is currently shorthand for --template, -t is not supported for --tty. This shorthand is deprecated and we expect to adopt -t for --tty soon.
 ```
 
@@ -128,7 +128,7 @@ $ kubectl run nginx --image=nginx --command -- <cmd> <arg1> ... <argN>
 
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-08-20 22:01:12.478226341 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-08-21 17:04:52.392255386 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_run.md?pixel)]()

pkg/kubectl/cmd/get.go

@@ -53,7 +53,7 @@ $ kubectl get -o json pod web-pod-13je7
 $ kubectl get -f pod.yaml -o json
 
 # Return only the phase value of the specified pod.
-$ kubectl get -o template web-pod-13je7 --template={{.status.phase}} --api-version=v1
+$ kubectl get -o template pod/web-pod-13je7 --template={{.status.phase}} --api-version=v1
 
 # List all replication controllers and services together in ps output format.
 $ kubectl get rc,services

pkg/kubectl/cmd/util/printing.go

@@ -31,7 +31,10 @@ func AddPrinterFlags(cmd *cobra.Command) {
 	cmd.Flags().StringP("output", "o", "", "Output format. One of: json|yaml|template|templatefile|wide|jsonpath.")
 	cmd.Flags().String("output-version", "", "Output the formatted object with the given version (default api-version).")
 	cmd.Flags().Bool("no-headers", false, "When using the default output, don't print headers.")
+	// template shorthand -t is deprecated to support -t for --tty
+	// TODO: remove template flag shorthand -t
 	cmd.Flags().StringP("template", "t", "", "Template string or path to template file to use when -o=template, -o=templatefile or -o=jsonpath.  The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. The jsonpath template is composed of jsonpath expressions enclosed by {} [http://releases.k8s.io/HEAD/docs/user-guide/jsonpath.md]")
+	cmd.Flags().MarkShorthandDeprecated("template", "please use --template instead")
 	cmd.Flags().String("sort-by", "", "If non-empty, sort list types using this field specification.  The field specification is expressed as a JSONPath expression (e.g. 'ObjectMeta.Name'). The field in the API resource specified by this JSONPath expression must be an integer or a string.")
 	cmd.Flags().BoolP("show-all", "a", false, "When printing, show all resources (default hide terminated pods.)")
 }