How to Create & Use Gitignore File With Terraform

A .gitignore file tells Git which files to leave untracked. In a Terraform project, getting this right matters: state files change on every run, variable files often contain secrets, and local provider cache directories have no business in a shared repository.

In this article, we cover exactly what to ignore in a Terraform project and why, along with a complete .gitignore file you can drop straight into your project.

1. What is .gitignore?
2. How to use the .gitignore file
3. Full .gitignore file example
4. Should I add .terraform.lock.hcl to .gitignore?

A .gitignore file is a text file used by Git to specify files and directories that should be ignored and not tracked by the version control system (VCS). Git itself is a distributed version control system (VCS) that helps developers track changes, collaborate on projects, and manage source code efficiently and has become the standard for version control.

When you create a .gitignore file and add patterns to it, Git will disregard those files and directories when you perform operations like staging, committing, and pushing changes to a repository.

Note that .gitignore files are not specific to Terraform projects, they can be used wherever Git is used with your VCS.

To use a .gitignore file with Terraform, simply create a new text file and name it .gitignore — place this file in the root directory of your project.

Step 1 – Go to bash terminal

To do this on the command line, go to bash terminal and create a new file using touch .gitignore .

Step 2 – Run git init and terraform init

You should also run the git init and terraform init commands to initialize your project.

Step 3 – Create the .gitignore file

You can add the sections of code as shown below as needed to form your .gitignore file. Once the file is pushed to your repository, from that point on the files and paths listed in your .gitignore file will be ignored.

Step 4 – Ignore local Terraform directories and files

Local Terraform directories and environment-specific files contain runtime information from execution done on the local machine and, therefore, do not need to be committed to source control.

# Local .terraform directories
**/.terraform/*

# Ignore all variable definition files 
*.tfvars 
*.tfvars.json

# Ignore override files
*.tfoverride

# Ignore environment-specific files
.envrc

# Ignore CLI configuration files
.terraformrc
terraform.rc

Step 5 – Ignore Terraform state files

Terraform state files will constantly be updated on each terrafom plan and terraform apply and so should be excluded from the VCS.

# .tfstate files
*.tfstate
*.tfstate.*

Step 6 – Ignore log files

Crash logs generated from local executions don’t need to live in the VCS.

# Crash log files
crash.log
crash.*.log

Step 7 – Ignore sensitive data

Sensitive files like encryption keys should never be committed to source control!

# Ignore sensitive files
*.pem
*.key
*.pub

Read more about Terraform secrets.

This example is based on the code from the GitHub link here.

# Local .terraform directories
**/.terraform/*

# .tfstate files
*.tfstate
*.tfstate.*

# Crash log files
crash.log
crash.*.log

# Exclude all .tfvars files, which are likely to contain sensitive data, such as
# password, private keys, and other secrets. These should not be part of version 
# control as they are data points which are potentially sensitive and subject 
# to change depending on the environment.
*.tfvars
*.tfvars.json

# Ignore override files as they are usually used to override resources locally and so
# are not checked in
override.tf
override.tf.json
*_override.tf
*_override.tf.json

# Include override files you do wish to add to version control using negated pattern
# !example_override.tf

# Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan
# example: *tfplan*

# Ignore CLI configuration files
.terraformrc
terraform.rc

The .terraform.lock.hcl file should be committed to version control, not ignored. It is the dependency lock file created by terraform init, and it records the exact provider versions and checksums selected for your project.

Committing it ensures that all team members and CI/CD pipelines use the same provider versions, preventing unexpected behavior caused by automatic provider upgrades. The principle is the same as committing package-lock.json in a Node.js project.

The official GitHub Terraform .gitignore template deliberately excludes it from the ignore list for this reason.

If you want to allow provider version upgrades, run terraform init -upgrade explicitly rather than relying on an untracked lock file.

You can use a .gitignore file in any Git-controlled repository to exclude files and folders that you don’t want to commit to source control. These might include sensitive files, files that apply to local usage only, or files that are necessary to commit to the repository. The example above can be used to form the basis of your .gitignore file for your Terraform projects.

Terraform is really powerful, but managing imports, state, and configuration at scale requires more than the CLI alone. Spacelift takes Terraform management to the next level by giving you access to a powerful CI/CD workflow and features such as:

• Policy as code (based on Open Policy Agent) to enforce guardrails on every plan and apply
• Drift detection to catch resources that have changed outside of Terraform
• Multi-IaC workflows across Terraform, OpenTofu, CloudFormation, Pulumi, and Kubernetes
• Self-service infrastructure through Blueprints and Templates
• Full audit trails so you always know what changed, when, and who approved it

If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.