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.
This commit is contained in:
parent
9665901e8e
commit
c94a6102df
|
@ -196,23 +196,24 @@ func (c *ApplyCommand) Help() string {
|
||||||
|
|
||||||
func (c *ApplyCommand) Synopsis() string {
|
func (c *ApplyCommand) Synopsis() string {
|
||||||
if c.Destroy {
|
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 {
|
func (c *ApplyCommand) helpApply() string {
|
||||||
helpText := `
|
helpText := `
|
||||||
Usage: terraform apply [options] [DIR-OR-PLAN]
|
Usage: terraform apply [options] [PLAN]
|
||||||
|
|
||||||
Builds or changes infrastructure according to Terraform configuration
|
Creates or updates infrastructure according to Terraform configuration
|
||||||
files in DIR.
|
files in the current directory.
|
||||||
|
|
||||||
By default, apply scans the current directory for the configuration
|
By default, Terraform will generate a new plan and present it for your
|
||||||
and applies the changes appropriately. However, a path to another
|
approval before taking any action. You can optionally provide a plan
|
||||||
configuration or an execution plan can be provided. Execution plans can be
|
file created by a previous call to "terraform plan", in which case
|
||||||
used to only execute a pre-determined set of actions.
|
Terraform will take the actions described in that plan without any
|
||||||
|
confirmation prompt.
|
||||||
|
|
||||||
Options:
|
Options:
|
||||||
|
|
||||||
|
|
|
@ -203,5 +203,5 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ConsoleCommand) Synopsis() string {
|
func (c *ConsoleCommand) Synopsis() string {
|
||||||
return "Interactive console for Terraform interpolations"
|
return "Try Terraform expressions at an interactive command prompt"
|
||||||
}
|
}
|
||||||
|
|
|
@ -526,7 +526,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *FmtCommand) Synopsis() string {
|
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) {
|
func bytesDiff(b1, b2 []byte, path string) (data []byte, err error) {
|
||||||
|
|
|
@ -54,6 +54,10 @@ Usage: terraform get [options] PATH
|
||||||
already downloaded, it will not be redownloaded or checked for updates
|
already downloaded, it will not be redownloaded or checked for updates
|
||||||
unless the -update flag is specified.
|
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:
|
Options:
|
||||||
|
|
||||||
-update Check already-downloaded modules for available updates
|
-update Check already-downloaded modules for available updates
|
||||||
|
@ -66,7 +70,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *GetCommand) Synopsis() string {
|
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 {
|
func getModules(m *Meta, path string, upgrade bool) tfdiags.Diagnostics {
|
||||||
|
|
|
@ -190,5 +190,5 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *GraphCommand) Synopsis() string {
|
func (c *GraphCommand) Synopsis() string {
|
||||||
return "Create a visual graph of Terraform resources"
|
return "Generate a Graphviz graph of the steps in an operation"
|
||||||
}
|
}
|
||||||
|
|
|
@ -327,7 +327,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ImportCommand) Synopsis() string {
|
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:
|
const importCommandInvalidAddressReference = `For information on valid syntax, see:
|
||||||
|
|
|
@ -1052,7 +1052,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *InitCommand) Synopsis() string {
|
func (c *InitCommand) Synopsis() string {
|
||||||
return "Initialize a Terraform working directory"
|
return "Prepare your working directory for other commands"
|
||||||
}
|
}
|
||||||
|
|
||||||
const errInitConfigError = `
|
const errInitConfigError = `
|
||||||
|
|
|
@ -223,5 +223,5 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *OutputCommand) Synopsis() string {
|
func (c *OutputCommand) Synopsis() string {
|
||||||
return "Read an output from a state file"
|
return "Show output values from your root module"
|
||||||
}
|
}
|
||||||
|
|
|
@ -193,12 +193,12 @@ func (c *PlanCommand) Help() string {
|
||||||
helpText := `
|
helpText := `
|
||||||
Usage: terraform plan [options] [DIR]
|
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
|
You can optionally save the plan to a file, which you can then pass to
|
||||||
sense for what Terraform will do. Optionally, the plan can be saved to
|
the "apply" command to perform exactly the actions described in the plan.
|
||||||
a Terraform plan file, and apply can take this plan file to execute
|
|
||||||
this plan exactly.
|
|
||||||
|
|
||||||
Options:
|
Options:
|
||||||
|
|
||||||
|
@ -249,5 +249,5 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *PlanCommand) Synopsis() string {
|
func (c *PlanCommand) Synopsis() string {
|
||||||
return "Generate and show an execution plan"
|
return "Show changes required by the current configuration"
|
||||||
}
|
}
|
||||||
|
|
|
@ -21,7 +21,7 @@ func (c *ProvidersCommand) Help() string {
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ProvidersCommand) Synopsis() 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 {
|
func (c *ProvidersCommand) Run(args []string) int {
|
||||||
|
|
|
@ -23,7 +23,7 @@ type ProvidersLockCommand struct {
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ProvidersLockCommand) Synopsis() string {
|
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 {
|
func (c *ProvidersLockCommand) Run(args []string) int {
|
||||||
|
|
|
@ -24,7 +24,7 @@ type ProvidersMirrorCommand struct {
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ProvidersMirrorCommand) Synopsis() string {
|
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 {
|
func (c *ProvidersMirrorCommand) Run(args []string) int {
|
||||||
|
|
|
@ -20,7 +20,7 @@ func (c *ProvidersSchemaCommand) Help() string {
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ProvidersSchemaCommand) Synopsis() 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 {
|
func (c *ProvidersSchemaCommand) Run(args []string) int {
|
||||||
|
|
|
@ -154,5 +154,5 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *RefreshCommand) Synopsis() string {
|
func (c *RefreshCommand) Synopsis() string {
|
||||||
return "Update local state file against real resources"
|
return "Update the state to match remote systems"
|
||||||
}
|
}
|
||||||
|
|
|
@ -209,7 +209,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ShowCommand) Synopsis() string {
|
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
|
// getPlanFromPath returns a plan and statefile if the user-supplied path points
|
||||||
|
|
|
@ -201,21 +201,27 @@ func (c *TaintCommand) Help() string {
|
||||||
helpText := `
|
helpText := `
|
||||||
Usage: terraform taint [options] <address>
|
Usage: terraform taint [options] <address>
|
||||||
|
|
||||||
Manually mark a resource as tainted, forcing a destroy and recreate
|
Terraform uses the term "tainted" to describe a resource instance
|
||||||
on the next plan/apply.
|
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
|
This will not modify your infrastructure directly, but subsequent
|
||||||
state to mark a resource as tainted so that during the next plan or
|
Terraform plans will include actions to destroy the remote object
|
||||||
apply that resource will be destroyed and recreated. This command on
|
and create a new object to replace it.
|
||||||
its own will not modify infrastructure. This command can be undone
|
|
||||||
using the "terraform untaint" command with the same address.
|
|
||||||
|
|
||||||
The address is in the usual resource address syntax, as shown in
|
You can remove the "taint" state from a resource instance using
|
||||||
the output from other commands, such as:
|
the "terraform untaint" command.
|
||||||
|
|
||||||
|
The address is in the usual resource address syntax, such as:
|
||||||
aws_instance.foo
|
aws_instance.foo
|
||||||
aws_instance.bar[1]
|
aws_instance.bar[1]
|
||||||
module.foo.module.bar.aws_instance.baz
|
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:
|
Options:
|
||||||
|
|
||||||
-allow-missing If specified, the command will succeed (exit code 0)
|
-allow-missing If specified, the command will succeed (exit code 0)
|
||||||
|
@ -240,7 +246,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *TaintCommand) Synopsis() string {
|
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 {
|
func (c *TaintCommand) allowMissingExit(name addrs.AbsResourceInstance) int {
|
||||||
|
|
|
@ -121,7 +121,7 @@ Usage: terraform force-unlock LOCK_ID [DIR]
|
||||||
Manually unlock the state for the defined configuration.
|
Manually unlock the state for the defined configuration.
|
||||||
|
|
||||||
This will not modify your infrastructure. This command removes the lock on the
|
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
|
on the backend being used. Local state files cannot be unlocked by another
|
||||||
process.
|
process.
|
||||||
|
|
||||||
|
@ -133,7 +133,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *UnlockCommand) Synopsis() string {
|
func (c *UnlockCommand) Synopsis() string {
|
||||||
return "Manually unlock the terraform state"
|
return "Release a stuck lock on the current workspace"
|
||||||
}
|
}
|
||||||
|
|
||||||
const outputUnlockSuccess = `
|
const outputUnlockSuccess = `
|
||||||
|
|
|
@ -175,14 +175,17 @@ func (c *UntaintCommand) Help() string {
|
||||||
helpText := `
|
helpText := `
|
||||||
Usage: terraform untaint [options] name
|
Usage: terraform untaint [options] name
|
||||||
|
|
||||||
Manually unmark a resource as tainted, restoring it as the primary
|
Terraform uses the term "tainted" to describe a resource instance
|
||||||
instance in the state. This reverses either a manual 'terraform taint'
|
which may not be fully functional, either because its creation
|
||||||
or the result of provisioners failing on a resource.
|
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
|
This command removes that state from a resource instance, causing
|
||||||
state to unmark a resource as tainted. This command can be undone by
|
Terraform to see it as fully-functional and not in need of
|
||||||
reverting the state backup file that is created, or by running
|
replacement.
|
||||||
'terraform taint' on the resource.
|
|
||||||
|
This will not modify your infrastructure directly. It only avoids
|
||||||
|
Terraform planning to replace a tainted instance in a future operation.
|
||||||
|
|
||||||
Options:
|
Options:
|
||||||
|
|
||||||
|
@ -212,7 +215,7 @@ Options:
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *UntaintCommand) Synopsis() string {
|
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 {
|
func (c *UntaintCommand) allowMissingExit(name addrs.AbsResourceInstance) int {
|
||||||
|
|
|
@ -235,7 +235,7 @@ func (c *ValidateCommand) showResults(diags tfdiags.Diagnostics, jsonOutput bool
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ValidateCommand) Synopsis() string {
|
func (c *ValidateCommand) Synopsis() string {
|
||||||
return "Validates the Terraform files"
|
return "Check whether the configuration is valid"
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *ValidateCommand) Help() string {
|
func (c *ValidateCommand) Help() string {
|
||||||
|
|
|
@ -169,5 +169,5 @@ func (c *VersionCommand) Run(args []string) int {
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c *VersionCommand) Synopsis() string {
|
func (c *VersionCommand) Synopsis() string {
|
||||||
return "Prints the Terraform version"
|
return "Show the current Terraform version"
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue