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
-  state file.
+ This command will move an item matched by the address given to the
+ 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),
-  configuration refactors (moving items to a completely different or new
-  state file), or generally renaming of resources.
+ This can be used for simple resource renaming, moving items to and from
+ a module, moving entire modules, and more. And because this command can also
+ 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 can't be disabled. Due to the destructive nature of this command,
-  the backup is ensured by Terraform for safety reasons.
+ This command will output a backup copy of the state prior to saving any
+ changes. The backup cannot be disabled. Due to the destructive nature
+ of this command, backups are required.
 
-  If you're moving from one state file to a different state file, a backup
-  will be created for each state file.
+ If you're moving an item to a different state file, a backup will be created
+ 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
-                      up Terraform-managed resources. By default it will
-                      use the state "terraform.tfstate" if it exists.
+  -state=PATH         Path to the source state file. Defaults to the configured
+                      backend, or "terraform.tfstate"
 
-  -state-out=PATH     Path to the destination state file to move the item
-                      to. This defaults to the same statefile. This will
-                      overwrite the destination state file.
+  -state-out=PATH     Path to the destination state file to write to. If this
+                      isn't specified, the source state file will be used. This
+                      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
-                   a timestamp with the ".backup" extension.
+* `-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.
 
-* `-backup-out=path` - Path to the backup file for the output state.
-                       This is only necessary if `-state-out` is specified.
+* `-backup-out=path` - Path where Terraform should write the backup for the
+  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".
-  Ignored when [remote state](/docs/state/remote.html) is used.
+* `-state=path` - Path to the source state file to read from. Defaults to the
+  configured backend, or "terraform.tfstate".
 
-* `-state-out=path` - Path to the state file to write to. If this isn't specified
-                      the state specified by `-state` will be used. This can be
-                      a new or existing path. Ignored when
-                      [remote state](/docs/state/remote.html) is used.
+* `-state-out=path` - Path to the destination state file to write to. If this
+  isn't specified the source state file will be used. This can be a new or
+  existing path.
 
 ## 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
-                   a timestamp with the ".backup" extension.
+* `-backup=path` - Path where Terraform should write the backup state. This
+  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