command: use -lock=false consistently in -help output

Previously the docs for this were rather confusing because they showed an
option to turn _on_ state locking, even though it's on by default.

Instead, we'll now show -lock=false in all cases and document it as
_disabling_ the default locking.

While working on this I also noticed that the equivalent docs on the
website were differently inconsistent. I've not made them fully consistent
here but at least moreso than they were before.
This commit is contained in:
Martin Atkins 2021-05-12 09:05:03 -07:00
parent ed121321c6
commit 42e0985839
21 changed files with 82 additions and 30 deletions

View File

@ -343,7 +343,9 @@ Options:
accompanied by errors, show them in a more compact accompanied by errors, show them in a more compact
form that includes only the summary messages. form that includes only the summary messages.
-lock=true Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -309,7 +309,9 @@ Options:
-input=false Disable interactive input prompts. -input=false Disable interactive input prompts.
-lock Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -242,7 +242,9 @@ Other Options:
-input=true Ask for input for variables if not directly set. -input=true Ask for input for variables if not directly set.
-lock=true Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -187,7 +187,9 @@ Options:
-input=true Ask for input for variables if not directly set. -input=true Ask for input for variables if not directly set.
-lock=true Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -477,7 +477,9 @@ Options:
-dry-run If set, prints out what would've been moved but doesn't -dry-run If set, prints out what would've been moved but doesn't
actually move anything. actually move anything.
-lock Lock the state files when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -156,7 +156,9 @@ Options:
-force Write the state even if lineages don't match or the -force Write the state even if lineages don't match or the
remote serial is higher. remote serial is higher.
-lock=true Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -179,7 +179,9 @@ Options:
-auto-approve Skip interactive approval. -auto-approve Skip interactive approval.
-lock Lock the state files when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -157,7 +157,9 @@ Options:
-backup=PATH Path where Terraform should write the backup -backup=PATH Path where Terraform should write the backup
state. state.
-lock=true Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -235,7 +235,9 @@ Options:
-allow-missing If specified, the command will succeed (exit code 0) -allow-missing If specified, the command will succeed (exit code 0)
even if the resource is missing. even if the resource is missing.
-lock Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -200,7 +200,9 @@ Options:
-allow-missing If specified, the command will succeed (exit code 0) -allow-missing If specified, the command will succeed (exit code 0)
even if the resource is missing. even if the resource is missing.
-lock Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -190,9 +190,11 @@ Usage: terraform [global options] workspace delete [OPTIONS] NAME
Options: Options:
-force remove a non-empty workspace. -force Remove even a non-empty workspace.
-lock=true Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -185,10 +185,11 @@ Usage: terraform [global options] workspace new [OPTIONS] NAME
Create a new Terraform workspace. Create a new Terraform workspace.
Options: Options:
-lock=true Lock the state file when locking is supported. -lock=false Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands
against the same workspace.
-lock-timeout=0s Duration to retry a state lock. -lock-timeout=0s Duration to retry a state lock.

View File

@ -69,8 +69,9 @@ _in addition to_ the planning modes and planning options described for
[Running Terraform in Automation](https://learn.hashicorp.com/tutorials/terraform/automate-terraform?in=terraform/automation&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) for some [Running Terraform in Automation](https://learn.hashicorp.com/tutorials/terraform/automate-terraform?in=terraform/automation&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) for some
different approaches. different approaches.
* `-lock=false` - Disables Terraform's default behavior of attempting to take * `-lock=false` - Don't hold a state lock during the operation. This is
a read/write lock on the state for the duration of the operation. dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before

View File

@ -48,7 +48,9 @@ The command-line flags are all optional. The list of available flags are:
* `-input=true` - Whether to ask for input for provider configuration. * `-input=true` - Whether to ask for input for provider configuration.
* `-lock=true` - Lock the state file when locking is supported. * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=0s` - Duration to retry a state lock. * `-lock-timeout=0s` - Duration to retry a state lock.

View File

@ -246,8 +246,9 @@ The available options are:
a value. This option is particular useful when running Terraform in a value. This option is particular useful when running Terraform in
non-interactive automation systems. non-interactive automation systems.
* `-lock=false` - Disables Terraform's default behavior of attempting to take * `-lock=false` - Don't hold a state lock during the operation. This is
a read/write lock on the state for the duration of the operation. dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before

View File

@ -53,11 +53,20 @@ makes any other changes between your configuration change and your
a plan that will destroy the old object and create a new object at the new a plan that will destroy the old object and create a new object at the new
address. address.
This command also accepts the following option: This command also accepts the following options:
* `-dry-run` - Report all of the resource instances that match the given * `-dry-run` - Report all of the resource instances that match the given
address without actually "forgetting" any of them. address without actually "forgetting" any of them.
* `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before
returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/docs/language/settings/backends/remote.html)
only, `terraform state mv` only, `terraform state mv`

View File

@ -27,7 +27,9 @@ This command also accepts the following options:
* `-auto-approve` - Skip interactive approval. * `-auto-approve` - Skip interactive approval.
* `-lock=true`- Lock the state files when locking is supported. * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=0s` - Duration to retry a state lock. * `-lock-timeout=0s` - Duration to retry a state lock.

View File

@ -36,11 +36,20 @@ instances. Depending on the constraints imposed by the remote system, creating
those objects might fail if their names or other identifiers conflict with those objects might fail if their names or other identifiers conflict with
the old objects still present. the old objects still present.
This command also accepts the following option: This command also accepts the following options:
* `-dry-run` - Report all of the resource instances that match the given * `-dry-run` - Report all of the resource instances that match the given
address without actually "forgetting" any of them. address without actually "forgetting" any of them.
* `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before
returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/docs/language/settings/backends/remote.html)
only, `terraform state rm` only, `terraform state rm`

View File

@ -50,8 +50,9 @@ This command also accepts the following options:
for other situations, such as if there is a problem reading or writing for other situations, such as if there is a problem reading or writing
the state. the state.
* `-lock=false` - Disables Terraform's default behavior of attempting to take * `-lock=false` - Don't hold a state lock during the operation. This is
a read/write lock on the state for the duration of the operation. dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before

View File

@ -30,8 +30,10 @@ from getting into this situation.
The command-line flags are all optional. The only supported flag is: The command-line flags are all optional. The only supported flag is:
* `-force` - Delete the workspace even if its state is not empty. Defaults to false. * `-force` - Delete the workspace even if its state is not empty. Defaults to false.
* `-lock` - Lock the state file when locking is supported. Defaults to true. * `-lock=false` - Don't hold a state lock during the operation. This is
* `-lock-timeout` - Duration to retry a state lock. Default 0s. dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s.
## Example ## Example

View File

@ -22,8 +22,10 @@ will be copied to initialize the state for this new workspace.
The command-line flags are all optional. The supported flags are: The command-line flags are all optional. The supported flags are:
* `-lock` - Lock the state file when locking is supported. Defaults to true. * `-lock=false` - Don't hold a state lock during the operation. This is
* `-lock-timeout` - Duration to retry a state lock. Default 0s. dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s.
* `-state=path` - Path to an existing state file to initialize the state of this environment. * `-state=path` - Path to an existing state file to initialize the state of this environment.
## Example: Create ## Example: Create