What to Include in a Gitignore File for Terraform: Essential Patterns Explained

A .gitignore file for Terraform must exclude state files (*.tfstate), local working directories (.terraform/), plan outputs (*.tfplan), and user-specific CLI configurations to prevent leaking sensitive infrastructure data and committing generated artifacts.

Keeping sensitive credentials and machine-generated files out of version control is fundamental to Terraform security. According to the hashicorp/terraform repository, the project maintains specific ignore patterns that reflect which files contain resource IDs, secrets, and environment-specific data versus actual source code. Understanding these distinctions ensures your repository remains clean, portable, and secure across development teams.

Critical Patterns for a Terraform Gitignore File

State Files and Backups

Terraform state files contain the complete mapping between your configuration and real infrastructure, including resource IDs and potentially sensitive values. As documented in docs/language/state.md, these files must never be committed to version control.

# Terraform state files (contain sensitive data)

*.tfstate
*.tfstate.backup

The *.tfstate.backup files are automatic snapshots created during state operations and carry the same sensitivity as the primary state file. These patterns are explicitly excluded in the canonical hashicorp/terraform/.gitignore to prevent accidental exposure of infrastructure credentials.

Local Working Directory and Provider Caches

The .terraform/ directory serves as the local working directory that caches provider plugins and downloaded modules. As detailed in docs/language/files/workspace.md, this directory contains machine-specific binaries and temporary files that vary by platform and architecture.

# Local Terraform working directory

.terraform/

This directory also houses experimental temporary state files created during terraform test operations, as noted in the repository's CHANGELOG.md. Including this pattern prevents committing large binary provider plugins that can exceed hundreds of megabytes.

Plan Files and Execution Outputs

Binary plan files generated via terraform plan -out=… are architecture-specific outputs that should remain local. These *.tfplan files (or custom-named plan outputs) are not source code and often contain sensitive resource arguments.

# Ignore binary plan outputs

*.tfplan

Additionally, crash logs generated when Terraform panics should be excluded:

crash.log
*.log

User-Specific CLI Configuration

CLI configuration files contain personal credentials, plugin mirrors, and provider authentication settings specific to individual developers. According to docs/cli/config/file.md, these files are referenced by the Terraform binary during initialization but must never be shared.

# User-specific CLI configuration (never commit)

.terraformrc
terraform.rc

These files typically reside in your home directory, but explicit exclusion prevents accidents when developers mistakenly place them in project roots.

Special Considerations for Terraform Lock Files

The .terraform.lock.hcl file presents a unique case. While this dependency lock file resides inside the .terraform/ directory (which is ignored), the file itself should typically be committed to ensure reproducible provider versions across all environments. However, if your workflow involves experimental forks or you specifically require flexible provider versions, you may choose to exclude it:

# Optional: lock file - commit if you want reproducible builds

# .terraform.lock.hcl

As implemented in the hashicorp/terraform source, this file captures the exact cryptographic checksums of provider dependencies, making it valuable for stability but optional for rapid prototyping environments.

Complete Terraform Gitignore Templates

Basic Module Repository

For reusable module repositories that do not maintain their own state, exclude generated artifacts and local caches:

# Ignore any generated Terraform state or plan files

*.tfstate
*.tfstate.backup
*.tfplan

# Ignore local plugin cache and module downloads

.terraform/

Full-Stack Project with CI/CD

Production repositories running automated pipelines require comprehensive exclusion of credentials and diagnostic files:

# Core Terraform artifacts

*.tfstate
*.tfstate.backup
*.tfplan

# Local working directory

.terraform/

# CLI config (personal credentials)

.terraformrc
terraform.rc

# Logs and crash diagnostics

crash.log
*.log

Repository with Terraform Test

Projects utilizing the experimental terraform test command must account for additional temporary state directories:

# State & plan artifacts

*.tfstate
*.tfstate.backup
*.tfplan

# Test-related temporary state directories

.terraform/
.crash/
crash.log

Summary

• *.tfstate and *.tfstate.backup contain sensitive infrastructure mappings and must be excluded from version control according to docs/language/state.md.
• .terraform/ caches provider binaries and module downloads that are specific to local environments and documented in docs/language/files/workspace.md.
• .terraformrc and terraform.rc store user-specific credentials and CLI settings that should never be committed, as outlined in docs/cli/config/file.md.
• .terraform.lock.hcl should generally be committed for reproducible builds, though it resides within the ignored .terraform/ directory.
• crash.log and other diagnostic outputs are generated automatically during panics and should remain local.

Frequently Asked Questions

Should I commit the .terraform.lock.hcl file to git?

Generally yes, you should commit the .terraform.lock.hcl file to ensure all team members and CI pipelines use identical provider versions with verified checksums. Only exclude it if you specifically need flexibility for experimental forks or rapid prototyping where provider version drift is acceptable.

Why does Terraform generate backup state files?

Terraform creates *.tfstate.backup files automatically before modifying state to provide a recovery point if operations fail. These files contain identical sensitive data to the primary state file, which is why the canonical hashicorp/terraform/.gitignore excludes both patterns simultaneously.

What happens if I accidentally commit a state file?

If a state file reaches your remote repository, immediately rotate any credentials stored within it, remove the file from git history using tools like git filter-repo or BFG Repo-Cleaner, and update your .gitignore to prevent recurrence. Treat committed state files as security incidents requiring credential rotation.

Can I store plan files (*.tfplan) in version control?

No, plan files are binary artifacts specific to your local Terraform version and provider architecture. They often contain sensitive values and will fail when applied by other team members. Store plans temporarily for CI/CD pipelines but never commit them to source control.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}