Clarify help text of kubectl replace

docs/man/man1/kubectl-replace.1

@@ -16,7 +16,9 @@ kubectl replace \- Replace a resource by filename or stdin.
 Replace a resource by filename or stdin.
 
 .PP
-JSON and YAML formats are accepted.
+JSON and YAML formats are accepted. If replacing an existing resource, the
+complete resource spec must be provided. This can be obtained by
+$ kubectl get TYPE NAME \-o yaml
 
 .PP
 Please refer to the models in 
@@ -162,6 +164,9 @@ $ kubectl replace \-f ./pod.json
 // Replace a pod based on the JSON passed into stdin.
 $ cat pod.json | kubectl replace \-f \-
 
+// Update a single\-container pod's image version (tag) to v4
+kubectl get pod mypod \-o yaml | sed 's/\\(image: myimage\\):.*$/\\1:v4/' | kubectl replace \-f \-
+
 // Force replace, delete and then re\-create the resource
 kubectl replace \-\-force \-f ./pod.json
 

docs/user-guide/kubectl/kubectl_replace.md

@@ -40,7 +40,9 @@ Replace a resource by filename or stdin.
 
 Replace a resource by filename or stdin.
 
-JSON and YAML formats are accepted.
+JSON and YAML formats are accepted. If replacing an existing resource, the
+complete resource spec must be provided. This can be obtained by
+$ kubectl get TYPE NAME -o yaml
 
 Please refer to the models in https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html to find if a field is mutable.
 
@@ -57,6 +59,9 @@ $ kubectl replace -f ./pod.json
 // Replace a pod based on the JSON passed into stdin.
 $ cat pod.json | kubectl replace -f -
 
+// Update a single-container pod's image version (tag) to v4
+kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -
+
 // Force replace, delete and then re-create the resource
 kubectl replace --force -f ./pod.json
 ```
@@ -106,7 +111,7 @@ kubectl replace --force -f ./pod.json
 
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-08-05 14:22:30.872347131 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-08-09 17:46:44.43991637 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_replace.md?pixel)]()

pkg/kubectl/cmd/replace.go

@@ -34,7 +34,9 @@ import (
 const (
 	replace_long = `Replace a resource by filename or stdin.
 
-JSON and YAML formats are accepted.
+JSON and YAML formats are accepted. If replacing an existing resource, the
+complete resource spec must be provided. This can be obtained by
+$ kubectl get TYPE NAME -o yaml
 
 Please refer to the models in https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html to find if a field is mutable.`
 	replace_example = `// Replace a pod using the data in pod.json.
@@ -43,6 +45,9 @@ $ kubectl replace -f ./pod.json
 // Replace a pod based on the JSON passed into stdin.
 $ cat pod.json | kubectl replace -f -
 
+// Update a single-container pod's image version (tag) to v4
+kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -
+
 // Force replace, delete and then re-create the resource
 kubectl replace --force -f ./pod.json`
 )