terraform init docs still include removed option -lock-timeout, without mentioning that it's been removed

[thameezb]

https://www.terraform.io/docs/cli/commands/init.html#lock-timeout-lt-duration-gt- refers to the flag -lock-timeout=<duration> being available for terraform init command

In reality this throws an error

terraform init -lock-timeout=10s                                                                                                                                   
Usage: terraform [global options] init [options]

  Initialize a new or existing Terraform working directory by creating
  initial files, loading any remote state, downloading modules, etc.

  This is the first command that should be run for any new or existing
  Terraform configuration per machine. This sets up all the local data
  necessary to run Terraform that is typically not committed to version
  control.

  This command is always safe to run multiple times. Though subsequent runs
  may give errors, this command will never delete your configuration or
  state. Even so, if you have important information, please back it up prior
  to running this command, just in case.

Options:

  -backend=true        Configure the backend for this configuration.

  -backend-config=path This can be either a path to an HCL file with key/value
                       assignments (same format as terraform.tfvars) or a
                       'key=value' format. This is merged with what is in the
                       configuration file. This can be specified multiple
                       times. The backend type must be in the configuration
                       itself.

  -force-copy          Suppress prompts about copying state data. This is
                       equivalent to providing a "yes" to all confirmation
                       prompts.

  -from-module=SOURCE  Copy the contents of the given module into the target
                       directory before initialization.

  -get=true            Download any modules for this configuration.

  -input=true          Ask for input if necessary. If false, will error if
                       input was required.

  -no-color            If specified, output won't contain any color.

  -plugin-dir          Directory containing plugin binaries. This overrides all
                       default search paths for plugins, and prevents the
                       automatic installation of plugins. This flag can be used
                       multiple times.

  -reconfigure         Reconfigure the backend, ignoring any saved
                       configuration.

  -migrate-state       Reconfigure the backend, and attempt to migrate any
                       existing state.

  -upgrade=false       If installing modules (-get) or plugins, ignore
                       previously-downloaded objects and install the
                       latest version allowed within configured constraints.

  -lockfile=MODE       Set a dependency lockfile mode.
                       Currently only "readonly" is valid.

Attempting it as a global command fails (as expected)

terraform -lock-timeout=10s init                                                                                                                                    
Invalid flags before the subcommand. If these flags are for
the subcommand, please put them after the subcommand.

Usage: terraform [global options] init [options]

  Initialize a new or existing Terraform working directory by creating
  initial files, loading any remote state, downloading modules, etc.

  This is the first command that should be run for any new or existing
  Terraform configuration per machine. This sets up all the local data
  necessary to run Terraform that is typically not committed to version
  control.

  This command is always safe to run multiple times. Though subsequent runs
  may give errors, this command will never delete your configuration or
  state. Even so, if you have important information, please back it up prior
  to running this command, just in case.

Options:

  -backend=true        Configure the backend for this configuration.

  -backend-config=path This can be either a path to an HCL file with key/value
                       assignments (same format as terraform.tfvars) or a
                       'key=value' format. This is merged with what is in the
                       configuration file. This can be specified multiple
                       times. The backend type must be in the configuration
                       itself.

  -force-copy          Suppress prompts about copying state data. This is
                       equivalent to providing a "yes" to all confirmation
                       prompts.

  -from-module=SOURCE  Copy the contents of the given module into the target
                       directory before initialization.

  -get=true            Download any modules for this configuration.

  -input=true          Ask for input if necessary. If false, will error if
                       input was required.

  -no-color            If specified, output won't contain any color.

  -plugin-dir          Directory containing plugin binaries. This overrides all
                       default search paths for plugins, and prevents the
                       automatic installation of plugins. This flag can be used
                       multiple times.

  -reconfigure         Reconfigure the backend, ignoring any saved
                       configuration.

  -migrate-state       Reconfigure the backend, and attempt to migrate any
                       existing state.

  -upgrade=false       If installing modules (-get) or plugins, ignore
                       previously-downloaded objects and install the
                       latest version allowed within configured constraints.

  -lockfile=MODE       Set a dependency lockfile mode.
                       Currently only "readonly" is valid.

TF version:

Terraform v0.15.4
on linux_amd64

[apparentlymart]

Thanks for reporting this, @thameezb.

Indeed, we removed that option from terraform init in a recent version because it historically did nothing. It looks like we removed it from the -help output but neglected to note in the documentation which version we removed it in.

We'll get that updated. Thanks again!

[apparentlymart]

The -lock-timeout option was restored in #29773 after finding that it was useful for the state migration functionality, and so that change made the documentation correct again! 😥