From c94a6102df62017766f4cc2c2a04c930c0a2c465 Mon Sep 17 00:00:00 2001
From: Martin Atkins <mart@degeneration.co.uk>
Date: Fri, 23 Oct 2020 16:55:32 -0700
Subject: [PATCH] command: Improve consistency of the command short
 descriptions

The short description of our commands (as shown in the main help output
from "terraform") was previously very inconsistent, using different
tense/mood for different commands. Some of the commands were also using
some terminology choices inconsistent with how we currently talk about
the related ideas in our documentation.

Here I've tried to add some consistency by first rewriting them all in
the imperative mood (except the ones that just are just subcommand
groupings), and tweaking some of the terminology to hopefully gel better
with how we present similar ideas in our recently-updated docs.

While working on this I inevitably spotted some similar inconsistencies
in the longer-form help output of some of the commands. I've not reviewed
all of these for consistency, but I did update some where the wording
was either left inconsstent with the short form changes I'd made or
where the prose stood out to me as particularly inconsistent with our
current usual documentation language style.

All of this is subjective, so I expect we'll continue to tweak these over
time as we continue to develop our documentation writing style based on
user questions and feedback.
---
 command/apply.go            | 19 ++++++++++---------
 command/console.go          |  2 +-
 command/fmt.go              |  2 +-
 command/get.go              |  6 +++++-
 command/graph.go            |  2 +-
 command/import.go           |  2 +-
 command/init.go             |  2 +-
 command/output.go           |  2 +-
 command/plan.go             | 12 ++++++------
 command/providers.go        |  2 +-
 command/providers_lock.go   |  2 +-
 command/providers_mirror.go |  2 +-
 command/providers_schema.go |  2 +-
 command/refresh.go          |  2 +-
 command/show.go             |  2 +-
 command/taint.go            | 26 ++++++++++++++++----------
 command/unlock.go           |  4 ++--
 command/untaint.go          | 19 +++++++++++--------
 command/validate.go         |  2 +-
 command/version.go          |  2 +-
 20 files changed, 64 insertions(+), 50 deletions(-)

diff --git a/command/apply.go b/command/apply.go
index eb2740e79..36b66f677 100644
--- a/command/apply.go
+++ b/command/apply.go
@@ -196,23 +196,24 @@ func (c *ApplyCommand) Help() string {
 
 func (c *ApplyCommand) Synopsis() string {
 	if c.Destroy {
-		return "Destroy Terraform-managed infrastructure"
+		return "Destroy previously-created infrastructure"
 	}
 
-	return "Builds or changes infrastructure"
+	return "Create or update infrastructure"
 }
 
 func (c *ApplyCommand) helpApply() string {
 	helpText := `
-Usage: terraform apply [options] [DIR-OR-PLAN]
+Usage: terraform apply [options] [PLAN]
 
-  Builds or changes infrastructure according to Terraform configuration
-  files in DIR.
+  Creates or updates infrastructure according to Terraform configuration
+  files in the current directory.
 
-  By default, apply scans the current directory for the configuration
-  and applies the changes appropriately. However, a path to another
-  configuration or an execution plan can be provided. Execution plans can be
-  used to only execute a pre-determined set of actions.
+  By default, Terraform will generate a new plan and present it for your
+  approval before taking any action. You can optionally provide a plan
+  file created by a previous call to "terraform plan", in which case
+  Terraform will take the actions described in that plan without any
+  confirmation prompt.
 
 Options:
 
diff --git a/command/console.go b/command/console.go
index 359d9dca0..c6f872b90 100644
--- a/command/console.go
+++ b/command/console.go
@@ -203,5 +203,5 @@ Options:
 }
 
 func (c *ConsoleCommand) Synopsis() string {
-	return "Interactive console for Terraform interpolations"
+	return "Try Terraform expressions at an interactive command prompt"
 }
diff --git a/command/fmt.go b/command/fmt.go
index 13e84a218..ff59d2b9d 100644
--- a/command/fmt.go
+++ b/command/fmt.go
@@ -526,7 +526,7 @@ Options:
 }
 
 func (c *FmtCommand) Synopsis() string {
-	return "Rewrites config files to canonical format"
+	return "Reformat your configuration in the standard style"
 }
 
 func bytesDiff(b1, b2 []byte, path string) (data []byte, err error) {
diff --git a/command/get.go b/command/get.go
index 238020a94..49cb207c3 100644
--- a/command/get.go
+++ b/command/get.go
@@ -54,6 +54,10 @@ Usage: terraform get [options] PATH
   already downloaded, it will not be redownloaded or checked for updates
   unless the -update flag is specified.
 
+  Module installation also happens automatically by default as part of
+  the "terraform init" command, so you should rarely need to run this
+  command separately.
+
 Options:
 
   -update             Check already-downloaded modules for available updates
@@ -66,7 +70,7 @@ Options:
 }
 
 func (c *GetCommand) Synopsis() string {
-	return "Download and install modules for the configuration"
+	return "Install or upgrade remote Terraform modules"
 }
 
 func getModules(m *Meta, path string, upgrade bool) tfdiags.Diagnostics {
diff --git a/command/graph.go b/command/graph.go
index cdfaaa2e7..fba33c6f8 100644
--- a/command/graph.go
+++ b/command/graph.go
@@ -190,5 +190,5 @@ Options:
 }
 
 func (c *GraphCommand) Synopsis() string {
-	return "Create a visual graph of Terraform resources"
+	return "Generate a Graphviz graph of the steps in an operation"
 }
diff --git a/command/import.go b/command/import.go
index f5891ed6d..cf22946c5 100644
--- a/command/import.go
+++ b/command/import.go
@@ -327,7 +327,7 @@ Options:
 }
 
 func (c *ImportCommand) Synopsis() string {
-	return "Import existing infrastructure into Terraform"
+	return "Associate existing infrastructure with a Terraform resource"
 }
 
 const importCommandInvalidAddressReference = `For information on valid syntax, see:
diff --git a/command/init.go b/command/init.go
index 6cd9a27bf..e90449ca5 100644
--- a/command/init.go
+++ b/command/init.go
@@ -1052,7 +1052,7 @@ Options:
 }
 
 func (c *InitCommand) Synopsis() string {
-	return "Initialize a Terraform working directory"
+	return "Prepare your working directory for other commands"
 }
 
 const errInitConfigError = `
diff --git a/command/output.go b/command/output.go
index e389c458c..3f5cc2bea 100644
--- a/command/output.go
+++ b/command/output.go
@@ -223,5 +223,5 @@ Options:
 }
 
 func (c *OutputCommand) Synopsis() string {
-	return "Read an output from a state file"
+	return "Show output values from your root module"
 }
diff --git a/command/plan.go b/command/plan.go
index 8064cad57..dc578f42e 100644
--- a/command/plan.go
+++ b/command/plan.go
@@ -193,12 +193,12 @@ func (c *PlanCommand) Help() string {
 	helpText := `
 Usage: terraform plan [options] [DIR]
 
-  Generates an execution plan for Terraform.
+  Generates a speculative execution plan, showing what actions Terraform
+  would take to apply the current configuration. This command will not
+  actually perform the planned actions.
 
-  This execution plan can be reviewed prior to running apply to get a
-  sense for what Terraform will do. Optionally, the plan can be saved to
-  a Terraform plan file, and apply can take this plan file to execute
-  this plan exactly.
+  You can optionally save the plan to a file, which you can then pass to
+  the "apply" command to perform exactly the actions described in the plan.
 
 Options:
 
@@ -249,5 +249,5 @@ Options:
 }
 
 func (c *PlanCommand) Synopsis() string {
-	return "Generate and show an execution plan"
+	return "Show changes required by the current configuration"
 }
diff --git a/command/providers.go b/command/providers.go
index 918fd841e..d2042d122 100644
--- a/command/providers.go
+++ b/command/providers.go
@@ -21,7 +21,7 @@ func (c *ProvidersCommand) Help() string {
 }
 
 func (c *ProvidersCommand) Synopsis() string {
-	return "Prints a tree of the providers used in the configuration"
+	return "Show the providers required for this configuration"
 }
 
 func (c *ProvidersCommand) Run(args []string) int {
diff --git a/command/providers_lock.go b/command/providers_lock.go
index 38bf2184a..74f23cef0 100644
--- a/command/providers_lock.go
+++ b/command/providers_lock.go
@@ -23,7 +23,7 @@ type ProvidersLockCommand struct {
 }
 
 func (c *ProvidersLockCommand) Synopsis() string {
-	return "Creates or updates dependency locks for providers in the configuration"
+	return "Write out dependency locks for the configured providers"
 }
 
 func (c *ProvidersLockCommand) Run(args []string) int {
diff --git a/command/providers_mirror.go b/command/providers_mirror.go
index 029b08630..a2367707a 100644
--- a/command/providers_mirror.go
+++ b/command/providers_mirror.go
@@ -24,7 +24,7 @@ type ProvidersMirrorCommand struct {
 }
 
 func (c *ProvidersMirrorCommand) Synopsis() string {
-	return "Mirrors the provider plugins needed for the current configuration"
+	return "Save local copies of all required provider plugins"
 }
 
 func (c *ProvidersMirrorCommand) Run(args []string) int {
diff --git a/command/providers_schema.go b/command/providers_schema.go
index 60e4c4c39..00634cf2f 100644
--- a/command/providers_schema.go
+++ b/command/providers_schema.go
@@ -20,7 +20,7 @@ func (c *ProvidersSchemaCommand) Help() string {
 }
 
 func (c *ProvidersSchemaCommand) Synopsis() string {
-	return "Prints the schemas of the providers used in the configuration"
+	return "Show schemas for the providers used in the configuration"
 }
 
 func (c *ProvidersSchemaCommand) Run(args []string) int {
diff --git a/command/refresh.go b/command/refresh.go
index 4ab3932f4..36c40633f 100644
--- a/command/refresh.go
+++ b/command/refresh.go
@@ -154,5 +154,5 @@ Options:
 }
 
 func (c *RefreshCommand) Synopsis() string {
-	return "Update local state file against real resources"
+	return "Update the state to match remote systems"
 }
diff --git a/command/show.go b/command/show.go
index 3bf034c9e..56d0e34b9 100644
--- a/command/show.go
+++ b/command/show.go
@@ -209,7 +209,7 @@ Options:
 }
 
 func (c *ShowCommand) Synopsis() string {
-	return "Inspect Terraform state or plan"
+	return "Show the current state or a saved plan"
 }
 
 // getPlanFromPath returns a plan and statefile if the user-supplied path points
diff --git a/command/taint.go b/command/taint.go
index 04a5bf1f1..ad4f10f06 100644
--- a/command/taint.go
+++ b/command/taint.go
@@ -201,21 +201,27 @@ func (c *TaintCommand) Help() string {
 	helpText := `
 Usage: terraform taint [options] <address>
 
-  Manually mark a resource as tainted, forcing a destroy and recreate
-  on the next plan/apply.
+  Terraform uses the term "tainted" to describe a resource instance
+  which may not be fully functional, either because its creation
+  partially failed or because you've manually marked it as such using
+  this command.
 
-  This will not modify your infrastructure. This command changes your
-  state to mark a resource as tainted so that during the next plan or
-  apply that resource will be destroyed and recreated. This command on
-  its own will not modify infrastructure. This command can be undone
-  using the "terraform untaint" command with the same address.
+  This will not modify your infrastructure directly, but subsequent
+  Terraform plans will include actions to destroy the remote object
+  and create a new object to replace it.
 
-  The address is in the usual resource address syntax, as shown in
-  the output from other commands, such as:
+  You can remove the "taint" state from a resource instance using
+  the "terraform untaint" command.
+
+  The address is in the usual resource address syntax, such as:
     aws_instance.foo
     aws_instance.bar[1]
     module.foo.module.bar.aws_instance.baz
 
+  Use your shell's quoting or escaping syntax to ensure that the
+  address will reach Terraform correctly, without any special
+  interpretation.
+
 Options:
 
   -allow-missing      If specified, the command will succeed (exit code 0)
@@ -240,7 +246,7 @@ Options:
 }
 
 func (c *TaintCommand) Synopsis() string {
-	return "Manually mark a resource for recreation"
+	return "Mark a resource instance as not fully functional"
 }
 
 func (c *TaintCommand) allowMissingExit(name addrs.AbsResourceInstance) int {
diff --git a/command/unlock.go b/command/unlock.go
index 94b2f7d8f..6376fd0f6 100644
--- a/command/unlock.go
+++ b/command/unlock.go
@@ -121,7 +121,7 @@ Usage: terraform force-unlock LOCK_ID [DIR]
   Manually unlock the state for the defined configuration.
 
   This will not modify your infrastructure. This command removes the lock on the
-  state for the current configuration. The behavior of this lock is dependent
+  state for the current workspace. The behavior of this lock is dependent
   on the backend being used. Local state files cannot be unlocked by another
   process.
 
@@ -133,7 +133,7 @@ Options:
 }
 
 func (c *UnlockCommand) Synopsis() string {
-	return "Manually unlock the terraform state"
+	return "Release a stuck lock on the current workspace"
 }
 
 const outputUnlockSuccess = `
diff --git a/command/untaint.go b/command/untaint.go
index 2f91d4482..96493bcb0 100644
--- a/command/untaint.go
+++ b/command/untaint.go
@@ -175,14 +175,17 @@ func (c *UntaintCommand) Help() string {
 	helpText := `
 Usage: terraform untaint [options] name
 
-  Manually unmark a resource as tainted, restoring it as the primary
-  instance in the state.  This reverses either a manual 'terraform taint'
-  or the result of provisioners failing on a resource.
+  Terraform uses the term "tainted" to describe a resource instance
+  which may not be fully functional, either because its creation
+  partially failed or because you've manually marked it as such using
+  the "terraform taint" command.
 
-  This will not modify your infrastructure. This command changes your
-  state to unmark a resource as tainted.  This command can be undone by
-  reverting the state backup file that is created, or by running
-  'terraform taint' on the resource.
+  This command removes that state from a resource instance, causing
+  Terraform to see it as fully-functional and not in need of
+  replacement.
+
+  This will not modify your infrastructure directly. It only avoids
+  Terraform planning to replace a tainted instance in a future operation.
 
 Options:
 
@@ -212,7 +215,7 @@ Options:
 }
 
 func (c *UntaintCommand) Synopsis() string {
-	return "Manually unmark a resource as tainted"
+	return "Remove the 'tainted' state from a resource instance"
 }
 
 func (c *UntaintCommand) allowMissingExit(name addrs.AbsResourceInstance) int {
diff --git a/command/validate.go b/command/validate.go
index e9c8914de..6519a5db9 100644
--- a/command/validate.go
+++ b/command/validate.go
@@ -235,7 +235,7 @@ func (c *ValidateCommand) showResults(diags tfdiags.Diagnostics, jsonOutput bool
 }
 
 func (c *ValidateCommand) Synopsis() string {
-	return "Validates the Terraform files"
+	return "Check whether the configuration is valid"
 }
 
 func (c *ValidateCommand) Help() string {
diff --git a/command/version.go b/command/version.go
index b20cc4c6a..cbece20ac 100644
--- a/command/version.go
+++ b/command/version.go
@@ -169,5 +169,5 @@ func (c *VersionCommand) Run(args []string) int {
 }
 
 func (c *VersionCommand) Synopsis() string {
-	return "Prints the Terraform version"
+	return "Show the current Terraform version"
 }