update state rm amd mv docs

Update the documentation to match the current behavior, and make the
usage output and website docs match.

command/state_mv.go

@@ -183,28 +183,30 @@ func (c *StateMvCommand) addableResult(results []*terraform.StateFilterResult) i
 
 func (c *StateMvCommand) Help() string {
 	helpText := `
-Usage: terraform state mv [options] ADDRESS ADDRESS
+Usage: terraform state mv [options] SOURCE DESTINATION
 
-  Move an item in the state to another location or to a completely different
+ This command will move an item matched by the address given to the
-  state file.
+ destination address. This command can also move to a destination address
+ in a completely different state file.
 
-  This command is useful for module refactors (moving items into a module),
+ This can be used for simple resource renaming, moving items to and from
-  configuration refactors (moving items to a completely different or new
+ a module, moving entire modules, and more. And because this command can also
-  state file), or generally renaming of resources.
+ move data to a completely new state, it can also be used for refactoring
+ one configuration into multiple separately managed Terraform configurations.
 
-  This command creates a timestamped backup of the state on every invocation.
+ This command will output a backup copy of the state prior to saving any
-  This can't be disabled. Due to the destructive nature of this command,
+ changes. The backup cannot be disabled. Due to the destructive nature
-  the backup is ensured by Terraform for safety reasons.
+ of this command, backups are required.
 
-  If you're moving from one state file to a different state file, a backup
+ If you're moving an item to a different state file, a backup will be created
-  will be created for each state file.
+ for each state file.
 
 Options:
 
   -backup=PATH        Path where Terraform should write the backup for the original
                       state. This can't be disabled. If not set, Terraform
                       will write it to the same path as the statefile with
-                      a backup extension.
+                      a ".backup" extension.
 
   -backup-out=PATH    Path where Terraform should write the backup for the destination
                       state. This can't be disabled. If not set, Terraform
@@ -213,13 +215,12 @@ Options:
                       to be specified if -state-out is set to a different path
                       than -state.
 
-  -state=PATH         Path to a Terraform state file to use to look
+  -state=PATH         Path to the source state file. Defaults to the configured
-                      up Terraform-managed resources. By default it will
+                      backend, or "terraform.tfstate"
-                      use the state "terraform.tfstate" if it exists.
 
-  -state-out=PATH     Path to the destination state file to move the item
+  -state-out=PATH     Path to the destination state file to write to. If this
-                      to. This defaults to the same statefile. This will
+                      isn't specified, the source state file will be used. This
-                      overwrite the destination state file.
+                      can be a new or existing path.
 
 `
 	return strings.TrimSpace(helpText)

website/docs/commands/state/mv.html.md

@@ -40,19 +40,22 @@ in [resource addressing format](/docs/commands/state/addressing.html).
 
 The command-line flags are all optional. The list of available flags are:
 
-* `-backup=path` - Path to a backup file Defaults to the state path plus
+* `-backup=path` - Path where Terraform should write the backup for the
-                   a timestamp with the ".backup" extension.
+  original state. This can't be disabled. If not set, Terraform will write it
+  to the same path as the statefile with a ".backup" extension.
 
-* `-backup-out=path` - Path to the backup file for the output state.
+* `-backup-out=path` - Path where Terraform should write the backup for the
-                       This is only necessary if `-state-out` is specified.
+  destination state. This can't be disabled. If not set, Terraform will write
+  it to the same path as the destination state file with a backup extension.
+  This only needs to be specified if -state-out is set to a different path than
+  -state.
 
-* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
+* `-state=path` - Path to the source state file to read from. Defaults to the
-  Ignored when [remote state](/docs/state/remote.html) is used.
+  configured backend, or "terraform.tfstate".
 
-* `-state-out=path` - Path to the state file to write to. If this isn't specified
+* `-state-out=path` - Path to the destination state file to write to. If this
-                      the state specified by `-state` will be used. This can be
+  isn't specified the source state file will be used. This can be a new or
-                      a new or existing path. Ignored when
+  existing path.
-                      [remote state](/docs/state/remote.html) is used.
 
 ## Example: Rename a Resource
 

website/docs/commands/state/rm.html.md

@@ -17,7 +17,7 @@ and more.
 
 Usage: `terraform state rm [options] ADDRESS...`
 
-The command will remove all the items matched by the addresses given.
+Remove one or more items from the Terraform state.
 
 Items removed from the Terraform state are _not physically destroyed_.
 Items removed from the Terraform state are only no longer managed by
@@ -43,10 +43,13 @@ in [resource addressing format](/docs/commands/state/addressing.html).
 
 The command-line flags are all optional. The list of available flags are:
 
-* `-backup=path` - Path to a backup file Defaults to the state path plus
+* `-backup=path` - Path where Terraform should write the backup state. This
-                   a timestamp with the ".backup" extension.
+  can't be disabled. If not set, Terraform will write it to the same path as
+  the statefile with a backup extension.
 
-* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
+* `-state=path` - Path to a Terraform state file to use to look up
+  Terraform-managed resources. By default it will use the configured backend,
+  or the default "terraform.tfstate" if it exists.
 
 ## Example: Remove a Resource