diff --git a/command/apply.go b/command/apply.go index 250884ad26..506ffce60c 100644 --- a/command/apply.go +++ b/command/apply.go @@ -370,10 +370,6 @@ Usage: terraform [global options] destroy [options] Options: - -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. - -auto-approve Skip interactive approval before destroying. -lock=true Lock the state file when locking is supported. @@ -388,13 +384,6 @@ Options: -refresh=true Update state prior to checking for differences. This has no effect if a plan file is given to apply. - -state=path Path to read and save state (unless state-out - is specified). Defaults to "terraform.tfstate". - - -state-out=path Path to write state to that is different than - "-state". This can be used to preserve the old - state. - -target=resource Resource to target. Operation will be limited to this resource and its dependencies. This flag can be used multiple times. @@ -406,7 +395,8 @@ Options: a file. If "terraform.tfvars" or any ".auto.tfvars" files are present, they will be automatically loaded. - + -state, state-out, and -backup are legacy options supported for the local + backend only. For more information, see the local backend's documentation. ` return strings.TrimSpace(helpText) } diff --git a/command/console.go b/command/console.go index ace570f2b4..fab428aa6a 100644 --- a/command/console.go +++ b/command/console.go @@ -189,16 +189,15 @@ Usage: terraform [global options] console [options] Options: - -state=path Path to read state. Defaults to "terraform.tfstate" - - -var 'foo=bar' Set a variable in the Terraform configuration. This - flag can be set multiple times. - - -var-file=foo Set variables in the Terraform configuration from - a file. If "terraform.tfvars" or any ".auto.tfvars" - files are present, they will be automatically loaded. + -state=path Legacy option for the local backend only. See the local + backend's documentation for more information. + -var 'foo=bar' Set a variable in the Terraform configuration. This + flag can be set multiple times. + -var-file=foo Set variables in the Terraform configuration from + a file. If "terraform.tfvars" or any ".auto.tfvars" + files are present, they will be automatically loaded. ` return strings.TrimSpace(helpText) } diff --git a/command/import.go b/command/import.go index c3adb52910..4067e4fcc3 100644 --- a/command/import.go +++ b/command/import.go @@ -300,10 +300,6 @@ Usage: terraform [global options] import [options] ADDR ID Options: - -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. - -config=path Path to a directory of Terraform configuration files to use to configure the provider. Defaults to pwd. If no config files are present, they must be provided @@ -319,13 +315,6 @@ Options: -no-color If specified, output won't contain any color. - -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 write to. If this - isn't specified, the source state file will be used. This - can be a new or existing path. - -var 'foo=bar' Set a variable in the Terraform configuration. This flag can be set multiple times. This is only useful with the "-config" flag. @@ -338,6 +327,9 @@ Options: are incompatible. This may result in an unusable workspace, and should be used with extreme caution. + -state, state-out, and -backup are legacy options supported for the local + backend only. For more information, see the local backend's documentation. + ` return strings.TrimSpace(helpText) } diff --git a/command/plan.go b/command/plan.go index 598fa1f835..bf43048163 100644 --- a/command/plan.go +++ b/command/plan.go @@ -221,9 +221,8 @@ Options: -refresh=true Update state prior to checking for differences. - -state=statefile 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=statefile A legacy option used for the local backend only. See the + local backend's documentation for more information. -target=resource Resource to target. Operation will be limited to this resource and its dependencies. This flag can be used diff --git a/command/refresh.go b/command/refresh.go index 7fddc13b8d..c7dbf71732 100644 --- a/command/refresh.go +++ b/command/refresh.go @@ -181,10 +181,6 @@ Usage: terraform [global options] refresh [options] Options: - -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. - -compact-warnings If Terraform produces any warnings that are not accompanied by errors, show them in a more compact form that includes only the summary messages. @@ -197,12 +193,6 @@ Options: -no-color If specified, output won't contain any color. - -state=path Path to read and save state (unless state-out - is specified). Defaults to "terraform.tfstate". - - -state-out=path Path to write updated state file. By default, the - "-state" path will be used. - -target=resource Resource to target. Operation will be limited to this resource and its dependencies. This flag can be used multiple times. @@ -214,6 +204,8 @@ Options: a file. If "terraform.tfvars" or any ".auto.tfvars" files are present, they will be automatically loaded. + -state, state-out, and -backup are legacy options supported for the local + backend only. For more information, see the local backend's documentation. ` return strings.TrimSpace(helpText) } diff --git a/website/docs/cli/commands/apply.html.md b/website/docs/cli/commands/apply.html.md index 3e1430f33c..42e9c1b417 100644 --- a/website/docs/cli/commands/apply.html.md +++ b/website/docs/cli/commands/apply.html.md @@ -30,9 +30,6 @@ output values then `terraform apply` will exit immediately, without prompting. The command-line flags are all optional. The list of available flags are: -* `-backup=path` - Path to the backup file. Defaults to `-state-out` with - the ".backup" extension. Disabled by setting to "-". - * `-compact-warnings` - If Terraform produces any warnings that are not accompanied by errors, show them in a more compact form that includes only the summary messages. @@ -55,16 +52,6 @@ The command-line flags are all optional. The list of available flags are: and applying. This has no effect if a plan file is given directly to apply. -* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. This setting - does not persist and other commands, such as init, may not be aware of the - alternate statefile. To configure an alternate statefile path which is - available to all terraform commands, use the [local backend](/docs/language/settings/backends/local.html). - -* `-state-out=path` - Path to write updated state file. By default, the - `-state` path will be used. Ignored when - [remote state](/docs/language/state/remote.html) is used. - * `-target=resource` - A [Resource Address](/docs/cli/state/resource-addressing.html) to target. For more information, see @@ -83,6 +70,11 @@ The command-line flags are all optional. The list of available flags are: specified by `-var-file` override any values set automatically from files in the working directory. This flag can be used multiple times. +For configurations using +[the `local` backend](/docs/language/settings/backends/local.html) only, +`terraform apply` also accepts the legacy options +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). + ## Passing a Different Configuration Directory Terraform v0.13 and earlier also accepted a directory path in place of the diff --git a/website/docs/cli/commands/console.html.md b/website/docs/cli/commands/console.html.md index 7d300078c5..5d888ead1d 100644 --- a/website/docs/cli/commands/console.html.md +++ b/website/docs/cli/commands/console.html.md @@ -26,15 +26,14 @@ If the current state is empty or has not yet been created, the console can be used to experiment with the expression syntax and [built-in functions](/docs/language/functions/index.html). -The supported options are: - -* `-state=path` - Path to a local state file. Expressions will be evaluated - using values from this state file. If not specified, the state associated - with the current [workspace](/docs/language/state/workspaces.html) is used. - You can close the console with the `exit` command or by pressing Control-C or Control-D. +For configurations using +[the `local` backend](/docs/language/settings/backends/local.html) only, +`terraform console` accepts the legacy command line option +[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). + ## Scripting The `terraform console` command can be used in non-interactive scripts diff --git a/website/docs/cli/commands/import.html.md b/website/docs/cli/commands/import.html.md index 1406404eb8..74b3ee9e37 100644 --- a/website/docs/cli/commands/import.html.md +++ b/website/docs/cli/commands/import.html.md @@ -41,10 +41,6 @@ behavior. For more information on this assumption, see The command-line flags are all optional. The list of available flags are: -* `-backup=path` - Path to backup the existing state file. Defaults to - the `-state-out` path with the ".backup" extension. Set to "-" to disable - backups. - * `-config=path` - Path to directory of Terraform configuration files that configure the provider for import. This defaults to your working directory. If this directory contains no Terraform configuration files, the provider @@ -66,13 +62,6 @@ The command-line flags are all optional. The list of available flags are: use when importing the object. By default, Terraform uses the provider specified in the configuration for the target resource, and that is the best behavior in most cases. -* `-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 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. - * `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag can be set multiple times. Variable values are interpreted as [literal expressions](/docs/language/expressions/types.html) in the @@ -93,6 +82,11 @@ in the configuration for the target resource, and that is the best behavior in m This may result in an unusable Terraform Cloud workspace, and should be used with extreme caution. +For configurations using +[the `local` backend](/docs/language/settings/backends/local.html) only, +`terraform import` also accepts the legacy options +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). + ## Provider Configuration Terraform will attempt to load configuration files that configure the diff --git a/website/docs/cli/commands/plan.html.md b/website/docs/cli/commands/plan.html.md index 647bedd340..516a782b87 100644 --- a/website/docs/cli/commands/plan.html.md +++ b/website/docs/cli/commands/plan.html.md @@ -69,9 +69,6 @@ The available options are: * `-refresh=true` - Update the state prior to checking for differences. -* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. - * `-target=resource` - A [Resource Address](/docs/cli/state/resource-addressing.html) to target. This flag can be used multiple times. See below for more information. @@ -89,6 +86,11 @@ The available options are: specified by `-var-file` override any values set automatically from files in the working directory. This flag can be used multiple times. +For configurations using +[the `local` backend](/docs/language/settings/backends/local.html) only, +`terraform plan` accepts the legacy command line option +[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). + ## Resource Targeting The `-target` option can be used to focus Terraform's attention on only a diff --git a/website/docs/cli/commands/refresh.html.md b/website/docs/cli/commands/refresh.html.md index 517b76f000..7aa1c9285d 100644 --- a/website/docs/cli/commands/refresh.html.md +++ b/website/docs/cli/commands/refresh.html.md @@ -23,9 +23,6 @@ Usage: `terraform refresh [options]` The `terraform refresh` command accepts the following options: -* `-backup=path` - Path to the backup file. Defaults to `-state-out` with - the ".backup" extension. Disabled by setting to "-". - * `-compact-warnings` - If Terraform produces any warnings that are not accompanied by errors, show them in a more compact form that includes only the summary messages. @@ -42,13 +39,6 @@ The `terraform refresh` command accepts the following options: [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults to 10. -* `-state=path` - Path to read and write the state file to. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. - -* `-state-out=path` - Path to write updated state file. By default, the - `-state` path will be used. Ignored when - [remote state](/docs/language/state/remote.html) is used. - * `-target=resource` - A [Resource Address](/docs/cli/state/resource-addressing.html) to target. Operation will be limited to this resource and its dependencies. This flag can be used @@ -66,3 +56,8 @@ The `terraform refresh` command accepts the following options: first and the `.auto.tfvars` files after in alphabetical order. Any files specified by `-var-file` override any values set automatically from files in the working directory. This flag can be used multiple times. + +For configurations using +[the `local` backend](/docs/language/settings/backends/local.html) only, +`terraform refresh` also accepts the legacy options +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). diff --git a/website/docs/language/settings/backends/local.html.md b/website/docs/language/settings/backends/local.html.md index 225e6ac278..f2829d3a42 100644 --- a/website/docs/language/settings/backends/local.html.md +++ b/website/docs/language/settings/backends/local.html.md @@ -42,3 +42,55 @@ The following configuration options are supported: * `path` - (Optional) The path to the `tfstate` file. This defaults to "terraform.tfstate" relative to the root module by default. * `workspace_dir` - (Optional) The path to non-default workspaces. + +## Command Line Arguments + +~> This section describes legacy features that we've preserved for backward +compatibility but that we no longer recommend. See below for more details. + +For configurations that include a `backend "local"` block or that default to +the local backend by not specifying a backend at all, most commands that either +read or write state snapshots from the backend accept the following +additional arguments: + +* `-state=FILENAME` - overrides the state filename when _reading_ the prior + state snapshot. +* `-state-out=FILENAME` - overrides the state filename when _writing_ new state + snapshots. + + If you use `-state` without also using `-state-out` then Terraform will + use the `-state` filename for both `-state` and `-state-out`, which means + Terraform will overwrite the input file if it creates a new state snapshot. +* `-backup=FILENAME` - overrides the default filename that the local backend + would normally choose dynamically to create backup files when it writes new + state. + + If you use `-state` without also using `-backup` then Terraform will use + the `-state` filename as a filename prefix for generating a backup filename. + You can use `-backup=-` (that is, set the filename to just the ASCII + dash character) to disable the creation of backup files altogether. + +These three options are preserved for backward-compatibility with earlier +workflows that predated the introduction of built-in remote state, where +users would write wrapper scripts that fetch prior state before running +Terraform and then save the new state after Terraform exits, in which case +the three arguments would typically all be paths within a temporary +directory used just for one operation. + +Because these old workflows predate the introduction of the possibility of +[multiple workspaces](/docs/language/state/workspaces.html), setting them +overrides Terraform's usual behavior of selecting a different state filename +based on the selected workspace. If you use all three of these options then +the selected workspace has no effect on which filenames Terraform will select +for state files, and so you'll need to select different filenames yourself if +you wish to keep workspace state files distinct from one another. + +These three options have no effect for configurations that have a different +backend type selected. + +We do not recommend using these options in new systems, even if you are running +Terraform in automation. Instead, +[select a different backend which supports remote state](./) and configure it +within your root module, which ensures that everyone working on your +configuration will automatically retrieve and store state in the correct shared +location without any special command line options.