diff --git a/docs/man/man1/kubectl-replace.1 b/docs/man/man1/kubectl-replace.1
index 51dfb25fcff..88e893c9d0d 100644
--- a/docs/man/man1/kubectl-replace.1
+++ b/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
 
diff --git a/docs/user-guide/kubectl/kubectl_replace.md b/docs/user-guide/kubectl/kubectl_replace.md
index b48b704e1cf..badb4a8d6d3 100644
--- a/docs/user-guide/kubectl/kubectl_replace.md
+++ b/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)]()
diff --git a/pkg/kubectl/cmd/replace.go b/pkg/kubectl/cmd/replace.go
index e9cf2a1b8ce..922ae9fbfe9 100644
--- a/pkg/kubectl/cmd/replace.go
+++ b/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`
 )