From 29c7a010252c347fee62f2ef90c01ea47ff1ed19 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Thu, 16 Mar 2017 23:32:45 -0700
Subject: [PATCH] website: clarify docs with partial config and k/v pairs

---
 website/source/docs/backends/config.html.md   | 18 ++++++++++++-
 .../source/docs/commands/init.html.markdown   | 25 ++++++-------------
 2 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/website/source/docs/backends/config.html.md b/website/source/docs/backends/config.html.md
index 47053e9529..36ae09cb1b 100644
--- a/website/source/docs/backends/config.html.md
+++ b/website/source/docs/backends/config.html.md
@@ -64,7 +64,9 @@ a few ways to supply the remaining configuration:
     [Vault](https://www.vaultproject.io)).
 
   * **Command-line key/value pairs**: Key/value pairs in the format of
-    `key=value` can be specified as part of the init command.
+    `key=value` can be specified as part of the init command. Note that
+    many shells retain command-line flags in a history file, so this isn't
+    recommended for secrets.
 
 In all cases, the final configuration is stored on disk in the
 ".terraform" directory, which should be ignored from version control.
@@ -73,6 +75,20 @@ This means that sensitive information can be omitted from version control
 but it ultimately still lives on disk. In the future, Terraform may provide
 basic encryption on disk so that values are at least not plaintext.
 
+When using partial configuration, Terraform requires at a minimum that
+an empty backend configuration is in the Terraform files. For example:
+
+```
+terraform {
+  backend "consul" {}
+}
+```
+
+This minimal requirement allows Terraform to detect _unsetting_ backends.
+We cannot accept the backend type on the command-line because while it is
+technically possible, Terraform would then be unable to detect if you
+want to unset your backend (and move back to local state).
+
 ## Changing Configuration
 
 You can change your backend configuration at any time. You can change
diff --git a/website/source/docs/commands/init.html.markdown b/website/source/docs/commands/init.html.markdown
index 6ec816fe4c..a9c0863fe1 100644
--- a/website/source/docs/commands/init.html.markdown
+++ b/website/source/docs/commands/init.html.markdown
@@ -54,9 +54,9 @@ The command-line flags are all optional. The list of available flags are:
 * `-input=true` - Ask for input interactively if necessary. If this is false
   and input is required, `init` will error.
 
-## Backend Config File
+## Backend Config
 
-The `-backend-config` can take a path to specify additional
+The `-backend-config` can take a path or `key=value` pair to specify additional
 backend configuration when [initialize a backend](/docs/backends/init.html).
 
 This is particularly useful for
@@ -64,7 +64,7 @@ This is particularly useful for
 configuration lets you keep sensitive information out of your Terraform
 configuration.
 
-The backend configuration file is a basic HCL file with key/value pairs.
+For path values, the backend configuration file is a basic HCL file with key/value pairs.
 The keys are configuration keys for your backend. You do not need to wrap it
 in a `terraform` block. For example, the following file is a valid backend
 configuration file for the Consul backend type:
@@ -74,19 +74,7 @@ address = "demo.consul.io"
 path    = "newpath"
 ```
 
-This format can be mixed with the key/value format documented below. In this
-case, the values will be merged by key.
-
-## Backend Config Key/Value
-
-The `-backend-config` will also accept `key=value` pairs to specify configuration
-directly on the command line.
-
-This is particularly useful for
-[partial configuration of backends](/docs/backends/config.html). Partial
-configuration lets you keep sensitive information out of your Terraform
-configuration.
-
+If the value contains an equal sign (`=`), it is parsed as a `key=value` pair.
 The format of this flag is identical to the `-var` flag for plan, apply,
 etc. but applies to configuration keys for backends. For example:
 
@@ -96,5 +84,6 @@ $ terraform init \
   -backend-config 'path=newpath'
 ```
 
-This format can be mixed with the file format documented above. In this
-case, the values will be merged by key.
+These two formats can be mixed. In this case, the values will be merged by
+key with keys specified later in the command-line overriding conflicting
+keys specified earlier.