command: Change module-depth default to -1

This means that terraform commands like `plan`, `apply`, `show`, and
`graph` will expand all modules by default.

While modules-as-black-boxes is still very true in the conceptual design
of modules, feedback on this behavior has consistently suggested that
users would prefer to see more verbose output by default.

The `-module-depth` flag and env var are retained to allow output to be
optionally limited / summarized by these commands.

command/graph.go

@@ -99,7 +99,7 @@ Options:
                        This helps when diagnosing cycle errors.
 
   -module-depth=n      The maximum depth to expand modules. By default this is
-                       zero, which will not expand modules at all.
+                       -1, which will expand resources within all modules.
 
   -verbose             Generate a verbose, "worst-case" graph, with all nodes
                        for potential operations in place.

command/meta.go

@@ -407,12 +407,17 @@ func (m *Meta) uiHook() *UiHook {
 }
 
 const (
-	// The name of the environment variable that can be used to set module depth.
+	// ModuleDepthDefault is the default value for
+	// module depth, which can be overridden by flag
+	// or env var
+	ModuleDepthDefault = -1
+
+	// ModuleDepthEnvVar is the name of the environment variable that can be used to set module depth.
 	ModuleDepthEnvVar = "TF_MODULE_DEPTH"
 )
 
 func (m *Meta) addModuleDepthFlag(flags *flag.FlagSet, moduleDepth *int) {
-	flags.IntVar(moduleDepth, "module-depth", 0, "module-depth")
+	flags.IntVar(moduleDepth, "module-depth", ModuleDepthDefault, "module-depth")
 	if envVar := os.Getenv(ModuleDepthEnvVar); envVar != "" {
 		if md, err := strconv.Atoi(envVar); err == nil {
 			*moduleDepth = md

command/meta_test.go

@@ -244,12 +244,12 @@ func TestMeta_addModuleDepthFlag(t *testing.T) {
 		"invalid envvar is ignored": {
 			EnvVar:   "-#",
 			Args:     []string{},
-			Expected: 0,
+			Expected: ModuleDepthDefault,
 		},
 		"empty envvar is okay too": {
 			EnvVar:   "",
 			Args:     []string{},
-			Expected: 0,
+			Expected: ModuleDepthDefault,
 		},
 	}
 

command/plan.go

@@ -181,7 +181,7 @@ Options:
 
   -module-depth=n     Specifies the depth of modules to show in the output.
                       This does not affect the plan itself, only the output
-                      shown. By default, this is zero. -1 will expand all.
+                      shown. By default, this is -1, which will expand all.
 
   -no-color           If specified, output won't contain any color.
 

command/show.go

@@ -118,7 +118,7 @@ Usage: terraform show [options] [path]
 Options:
 
   -module-depth=n     Specifies the depth of modules to show in the output.
-                      By default this is zero. -1 will expand all.
+                      By default this is -1, which will expand all.
 
   -no-color           If specified, output won't contain any color.
 

contrib/zsh-completion/_terraform

@@ -49,7 +49,7 @@ __get() {
 
 __graph() {
     _arguments \
-        '-module-depth=[(n) The maximum depth to expand modules. By default this is zero, which will not expand modules at all.]'
+        '-module-depth=[(n) The maximum depth to expand modules. By default this is -1, which will expand all modules.]'
 }
 
 __init() {
@@ -71,7 +71,7 @@ __plan() {
         '-backup=[(path) Path to backup the existing state file before modifying. Defaults to the "-state-out" path with" .backup" extension. Set to "-" to disable backup.]' \
         '-destroy[If set, a plan will be generated to destroy all resources managed by the given configuration and state.]' \
         '-input=[(true) Ask for input for variables if not directly set.]' \
-        '-module-depth=[(n) Specifies the depth of modules to show in the output. This does not affect the plan itself, only the output shown. By default, this is zero. -1 will expand all.]' \
+        '-module-depth=[(n) Specifies the depth of modules to show in the output. This does not affect the plan itself, only the output shown. By default, this is -1, which will expand all.]' \
         '-no-color[If specified, output will not contain any color.]' \
         '-out=[(path) Write a plan file to the given path. This can be used as input to the "apply" command.]' \
         '-refresh=[(true) Update state prior to checking for differences.]' \
@@ -121,7 +121,7 @@ __remote() {
 
 __show() {
     _arguments \
-        '-module-depth=[(n) The maximum depth to expand modules. By default this is zero, which will not expand modules at all.]' \
+        '-module-depth=[(n) The maximum depth to expand modules. By default this is -1, which will expand all modules.]' \
         '-no-color[If specified, output will not contain any color.]'
 }
 

website/source/docs/commands/graph.html.markdown

@@ -31,7 +31,7 @@ Options:
                       This helps when diagnosing cycle errors.
 
 * `-module-depth=n` - The maximum depth to expand modules. By default this is
-                      zero, which will not expand modules at all.
+                      -1, which will expand all modules.
 
 * `-verbose`        - Generate a verbose, "worst-case" graph, with all nodes
                       for potential operations in place.

website/source/docs/commands/plan.html.markdown

@@ -39,7 +39,7 @@ The command-line flags are all optional. The list of available flags are:
 
 * `-module-depth=n` - Specifies the depth of modules to show in the output.
   This does not affect the plan itself, only the output shown. By default,
-  this is zero. -1 will expand all.
+  this is -1, which will expand all.
 
 * `-no-color` - Disables output with coloring.
 

website/source/docs/commands/show.html.markdown

@@ -23,7 +23,7 @@ file. If no path is specified, the current state will be shown.
 The command-line flags are all optional. The list of available flags are:
 
 * `-module-depth=n` - Specifies the depth of modules to show in the output.
-  By default this is zero. -1 will expand all.
+  By default this is -1, which will expand all.
 
 * `-no-color` - Disables output with coloring
 

website/source/docs/configuration/environment-variables.html.md

@@ -44,10 +44,10 @@ export TF_INPUT=0
 
 ## TF_MODULE_DEPTH
 
-When given a value, causes terraform commands to behave as if the `-module=depth=VALUE` flag was specified. Modules are treated like a black box and terraform commands do not show what resources within the module will be created. By setting this to -1, for example, you enable commands such as [plan](/docs/commands/plan.html) and [graph](/docs/commands/graph.html) to display more detailed information.
+When given a value, causes terraform commands to behave as if the `-module=depth=VALUE` flag was specified. By setting this to 0, for example, you enable commands such as [plan](/docs/commands/plan.html) and [graph](/docs/commands/graph.html) to display more compressed information.
 
 ```
-export TF_MODULE_DEPTH=-1
+export TF_MODULE_DEPTH=0
 ```
 
 For more information regarding modules, check out the section on [Using Modules](/docs/modules/usage.html).

website/source/docs/modules/usage.html.markdown

@@ -104,28 +104,26 @@ resource to the module, so the module will be built first.
 
 With modules, commands such as the [plan command](/docs/commands/plan.html)
 and
-[graph command](/docs/commands/graph.html) will show the module as a single
-unit by default. You can use the `-module-depth` parameter to expand this
-graph further.
+[graph command](/docs/commands/graph.html) will expand modules by default. You
+can use the `-module-depth` parameter to limit the graph.
 
 For example, with a configuration similar to what we've built above, here
 is what the graph output looks like by default:
 
 <div class="center">
-![Terraform Module Graph](docs/module_graph.png)
+![Terraform Expanded Module Graph](docs/module_graph_expand.png)
 </div>
 
-But if we set `-module-depth=-1`, the graph will look like this:
+But if we set `-module-depth=0`, the graph will look like this:
 
 <div class="center">
-![Terraform Expanded Module Graph](docs/module_graph_expand.png)
+![Terraform Module Graph](docs/module_graph.png)
 </div>
 
 Other commands work similarly with modules. Note that the `-module-depth`
 flag is purely a formatting flag; it doesn't affect what modules are created
 or not.
 
-
 ## Tainting resources within a module
 
 The [taint command](/docs/commands/taint.html) can be used to _taint_

website/source/intro/getting-started/modules.html.md

@@ -50,7 +50,7 @@ module "consul" {
 
 	key_name = "AWS SSH KEY NAME"
 	key_path = "PATH TO ABOVE PRIVATE KEY"
-	region = "AWS REGION"
+	region = "us-east-1"
 	servers = "3"
 }
 ```
@@ -94,14 +94,22 @@ With the modules downloaded, we can now plan and apply it. If you run
 ```
 $ terraform plan
 ...
-+ module.consul
-    4 resource(s)
++ module.consul.aws_instance.server.0
+...
++ module.consul.aws_instance.server.1
+...
++ module.consul.aws_instance.server.2
+...
++ module.consul.aws_security_group.consul
+...
+Plan: 4 to add, 0 to change, 0 to destroy.
 ```
 
-As you can see, the module is treated like a black box. In the plan, Terraform
-shows the module managed as a whole. It does not show what resources within
-the module will be created. If you care, you can see that by specifying
-a `-module-depth=-1` flag.
+Conceptually, the module is treated like a black box. In the plan, however
+Terraform shows each resource the module manages so you can see each detail
+about what the plan will do. If you'd like compressed plan output, you can
+specify the `-module-depth=` flag to get Terraform to output summaries by
+module.
 
 Next, run `terraform apply` to create the module. Note that as we warned above,
 the resources this module creates are outside of the AWS free tier, so this