# Terraform: treat .terraform.lock.hcl as a first-class artifact
## Why
`.terraform.lock.hcl` records the exact provider versions selected and their hashes. Without it in version control, every `terraform init` on a fresh machine can pick different provider builds. With it, installs are reproducible and tamper-evident.
## How
The lock file is created and updated by `terraform init`. Key operations:
1. Commit it. It belongs in git next to your config. Do not gitignore it in root modules.
2. `terraform init -upgrade` re-resolves and rewrites the lock file with the newest versions allowed by your constraints. Use it deliberately, never as a reflex.
3. `terraform providers lock` regenerates lock entries for multiple platforms at once. Run it when your team mixes macOS and Linux, or when CI runs on a different OS than your laptop, so all platforms have recorded hashes.
4. Never hand-edit the hashes. If a hash looks wrong, delete the lock file and re-init, then review what changed with `git diff`.
## Rules for agents
1. If the lock file is missing from a repo that should have one, say so. Do not silently re-init and move on.
2. After any provider constraint change, expect the lock file to change. Review the diff: version bumps you did not intend are a signal to stop.
3. A lock file that suddenly changes with no config change means someone ran `-upgrade` or the file was regenerated. Ask why before applying.
4. In CI, a fresh `terraform init` that rewrites the lock file means the committed file was stale. Fail loudly or commit the update, do not silently proceed.