From 42e09858391e71c185b971260b2fc3cc55cbacf8 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Wed, 12 May 2021 09:05:03 -0700 Subject: [PATCH] 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. --- command/apply.go | 4 +++- command/import.go | 4 +++- command/plan.go | 4 +++- command/refresh.go | 4 +++- command/state_mv.go | 4 +++- command/state_push.go | 4 +++- command/state_replace_provider.go | 4 +++- command/state_rm.go | 4 +++- command/taint.go | 4 +++- command/untaint.go | 4 +++- command/workspace_delete.go | 8 +++++--- command/workspace_new.go | 7 ++++--- website/docs/cli/commands/apply.html.md | 5 +++-- website/docs/cli/commands/import.html.md | 4 +++- website/docs/cli/commands/plan.html.md | 5 +++-- website/docs/cli/commands/state/mv.html.md | 11 ++++++++++- .../docs/cli/commands/state/replace-provider.html.md | 4 +++- website/docs/cli/commands/state/rm.html.md | 11 ++++++++++- website/docs/cli/commands/untaint.html.md | 5 +++-- website/docs/cli/commands/workspace/delete.html.md | 6 ++++-- website/docs/cli/commands/workspace/new.html.md | 6 ++++-- 21 files changed, 82 insertions(+), 30 deletions(-) diff --git a/command/apply.go b/command/apply.go index cca550011..e7587e40c 100644 --- a/command/apply.go +++ b/command/apply.go @@ -343,7 +343,9 @@ Options: accompanied by errors, show them in a more compact 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. diff --git a/command/import.go b/command/import.go index 3834e5e67..219b14578 100644 --- a/command/import.go +++ b/command/import.go @@ -309,7 +309,9 @@ Options: -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. diff --git a/command/plan.go b/command/plan.go index 8f3d1195b..e33473104 100644 --- a/command/plan.go +++ b/command/plan.go @@ -242,7 +242,9 @@ Other Options: -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. diff --git a/command/refresh.go b/command/refresh.go index 77942fd67..fc077ad69 100644 --- a/command/refresh.go +++ b/command/refresh.go @@ -187,7 +187,9 @@ Options: -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. diff --git a/command/state_mv.go b/command/state_mv.go index 9be27c15d..2ecf8349a 100644 --- a/command/state_mv.go +++ b/command/state_mv.go @@ -477,7 +477,9 @@ Options: -dry-run If set, prints out what would've been moved but doesn't 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. diff --git a/command/state_push.go b/command/state_push.go index dcffa092e..8d5f86bcd 100644 --- a/command/state_push.go +++ b/command/state_push.go @@ -156,7 +156,9 @@ Options: -force Write the state even if lineages don't match or the 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. diff --git a/command/state_replace_provider.go b/command/state_replace_provider.go index 6f894fb7a..c7ea71d66 100644 --- a/command/state_replace_provider.go +++ b/command/state_replace_provider.go @@ -179,7 +179,9 @@ Options: -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. diff --git a/command/state_rm.go b/command/state_rm.go index 8c236a74e..70d47f835 100644 --- a/command/state_rm.go +++ b/command/state_rm.go @@ -157,7 +157,9 @@ Options: -backup=PATH Path where Terraform should write the backup 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. diff --git a/command/taint.go b/command/taint.go index e68f27b8f..f83db6afa 100644 --- a/command/taint.go +++ b/command/taint.go @@ -235,7 +235,9 @@ Options: -allow-missing If specified, the command will succeed (exit code 0) 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. diff --git a/command/untaint.go b/command/untaint.go index 5df6d2c17..33c3f6756 100644 --- a/command/untaint.go +++ b/command/untaint.go @@ -200,7 +200,9 @@ Options: -allow-missing If specified, the command will succeed (exit code 0) 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. diff --git a/command/workspace_delete.go b/command/workspace_delete.go index 0fb90c429..9418e2449 100644 --- a/command/workspace_delete.go +++ b/command/workspace_delete.go @@ -190,11 +190,13 @@ Usage: terraform [global options] workspace delete [OPTIONS] NAME 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. ` return strings.TrimSpace(helpText) diff --git a/command/workspace_new.go b/command/workspace_new.go index ce074d662..055680af8 100644 --- a/command/workspace_new.go +++ b/command/workspace_new.go @@ -185,14 +185,15 @@ Usage: terraform [global options] workspace new [OPTIONS] NAME Create a new Terraform workspace. - 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. - -state=path Copy an existing state file into the new workspace. + -state=path Copy an existing state file into the new workspace. ` return strings.TrimSpace(helpText) diff --git a/website/docs/cli/commands/apply.html.md b/website/docs/cli/commands/apply.html.md index f5454bb71..0c270d027 100644 --- a/website/docs/cli/commands/apply.html.md +++ b/website/docs/cli/commands/apply.html.md @@ -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 different approaches. -* `-lock=false` - Disables Terraform's default behavior of attempting to take - a read/write lock on the state for the duration of the operation. +* `-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 diff --git a/website/docs/cli/commands/import.html.md b/website/docs/cli/commands/import.html.md index 0f03cd957..8d5c2dbd4 100644 --- a/website/docs/cli/commands/import.html.md +++ b/website/docs/cli/commands/import.html.md @@ -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. -* `-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. diff --git a/website/docs/cli/commands/plan.html.md b/website/docs/cli/commands/plan.html.md index 5a87d728f..fd68a98f6 100644 --- a/website/docs/cli/commands/plan.html.md +++ b/website/docs/cli/commands/plan.html.md @@ -246,8 +246,9 @@ The available options are: a value. This option is particular useful when running Terraform in non-interactive automation systems. -* `-lock=false` - Disables Terraform's default behavior of attempting to take - a read/write lock on the state for the duration of the operation. +* `-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 diff --git a/website/docs/cli/commands/state/mv.html.md b/website/docs/cli/commands/state/mv.html.md index bdb25a3cd..7670ae7a4 100644 --- a/website/docs/cli/commands/state/mv.html.md +++ b/website/docs/cli/commands/state/mv.html.md @@ -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 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 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 [the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform state mv` diff --git a/website/docs/cli/commands/state/replace-provider.html.md b/website/docs/cli/commands/state/replace-provider.html.md index 8fb847c01..21befd99e 100644 --- a/website/docs/cli/commands/state/replace-provider.html.md +++ b/website/docs/cli/commands/state/replace-provider.html.md @@ -27,7 +27,9 @@ This command also accepts the following options: * `-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. diff --git a/website/docs/cli/commands/state/rm.html.md b/website/docs/cli/commands/state/rm.html.md index 1dac9be70..3cc9f297e 100644 --- a/website/docs/cli/commands/state/rm.html.md +++ b/website/docs/cli/commands/state/rm.html.md @@ -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 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 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 [the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform state rm` diff --git a/website/docs/cli/commands/untaint.html.md b/website/docs/cli/commands/untaint.html.md index 6d1f0fac2..12793958b 100644 --- a/website/docs/cli/commands/untaint.html.md +++ b/website/docs/cli/commands/untaint.html.md @@ -50,8 +50,9 @@ This command also accepts the following options: for other situations, such as if there is a problem reading or writing the state. -* `-lock=false` - Disables Terraform's default behavior of attempting to take - a read/write lock on the state for the duration of the operation. +* `-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 diff --git a/website/docs/cli/commands/workspace/delete.html.md b/website/docs/cli/commands/workspace/delete.html.md index 3c99cf857..3fd077631 100644 --- a/website/docs/cli/commands/workspace/delete.html.md +++ b/website/docs/cli/commands/workspace/delete.html.md @@ -30,8 +30,10 @@ from getting into this situation. 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. -* `-lock` - Lock the state file when locking is supported. Defaults to true. -* `-lock-timeout` - Duration to retry a state lock. Default 0s. +* `-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` - Duration to retry a state lock. Default 0s. ## Example diff --git a/website/docs/cli/commands/workspace/new.html.md b/website/docs/cli/commands/workspace/new.html.md index 0caac8b08..ef2e73ecf 100644 --- a/website/docs/cli/commands/workspace/new.html.md +++ b/website/docs/cli/commands/workspace/new.html.md @@ -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: -* `-lock` - Lock the state file when locking is supported. Defaults to true. -* `-lock-timeout` - Duration to retry a state lock. Default 0s. +* `-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` - Duration to retry a state lock. Default 0s. * `-state=path` - Path to an existing state file to initialize the state of this environment. ## Example: Create