Should .terraform.lock.hcl be included in the .gitignore file?

Per the Terraform documentation on the Dependency Lock File:

Terraform automatically creates or updates the dependency lock file
each time you run the terraform init command. You should include this
file in your version control repository so that you can discuss
potential changes to your external dependencies via code review, just
as you would discuss potential changes to your configuration itself.

The key to understanding why you should commit that file is found in the following section on Dependency Installation Behavior:

When terraform init is working on installing all of the providers
needed for a configuration, Terraform considers both the version
constraints in the configuration and the version selections recorded
in the lock file
.

If a particular provider has no existing recorded selection, Terraform
will select the newest available version that matches the given
version constraint, and then update the lock file to include that
selection.

If a particular provider already has a selection recorded in the lock
file, Terraform will always re-select that version for installation,
even if a newer version has become available
. You can override that
behavior by adding the -upgrade option when you run terraform init, in
which case Terraform will disregard the existing selections and once
again select the newest available version matching the version
constraint.

Essentially this is intended to have Terraform continue to use the version of the provider selected when you added it. If you do not checkin the lock file, you will always be automatically upgraded to the latest version that obeys the constraint in code, which could lead to unintended consequences.

Note: You can force Terraform to upgrade when doing the init call by passing the -upgrade flag.

terraform init -upgrade

Update for Cross-Platform Development

From the Terraform documentation on the providers lock command:

Specifying Target Platforms In your environment you may, for example,
have both developers who work with your Terraform configuration on
their Windows or macOS workstations and automated systems that apply
the configuration while running on Linux.

In that situation, you could choose to verify that all of your
providers support all of those platforms, and to pre-populate the lock
file with the necessary checksums, by running terraform providers lock
and specifying those three platforms:

terraform providers lock \
    -platform=windows_amd64 \
    -platform=darwin_amd64 \
    -platform=linux_amd64 \
    -platform=darwin_arm64 \
    -platform=linux_arm64

The above example uses Unix-style shell wrapping syntax for readability. If you are running
the command on Windows then you will need to replace the backslashes with carets (for cmd) or backticks (for PowerShell).

So you should still check the lock file into version control, but you should ensure the lock file contains the checksums for providers on all platforms.

Leave a Comment