Every OpenTofu project creates files that should never go into Git: downloaded providers, state files and saved plans. This guide gives you the OpenTofu .gitignore to use, shows what each line keeps out, and names the one OpenTofu file you should commit.
It’s a companion to Part 2 of the OpenTofu Tutorial, which adds a first .gitignore to the Bookshop project.
Cost: free. Everything here runs on your own computer.
Every command and output on this page is real, run on OpenTofu 1.13 and Git on macOS. The commands are the same in Windows PowerShell and on Linux.
Prerequisites
- OpenTofu installed: How to Install OpenTofu on macOS.
- Git installed, from git-scm.com.
git --versionshould print a version number. - An OpenTofu project folder where you’ve run
tofu initandtofu apply, such as the Bookshop project from Part 2. This one also has a saved plan,bookshop.tfplan.
Step 1: See What Git Would Pick Up
If the folder isn’t a Git repository yet, run git init in it first. Then ask Git what it sees:
git status
On branch master
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
.terraform.lock.hcl
.terraform/
bookshop.tfplan
index.html
main.tf
terraform.tfstate
nothing added to commit but untracked files present (use "git add" to track)
Your branch may be called main instead of master; that depends on your Git settings. Three of these files must not be committed:
.terraform/holds the providerstofu initdownloaded. It’s large, built for your own operating system, andtofu initcan always download it again.terraform.tfstateis OpenTofu’s state. OpenTofu’s documentation warns that state can contain sensitive data, such as passwords.bookshop.tfplanis a saved plan. The documentation warns that a plan file can hold sensitive values in plain text.
Step 2: Add a .gitignore
In your editor, create a file named .gitignore in the project folder with these four lines:
.terraform/
*.tfstate
*.tfstate.*
*.tfplan
| Line | Keeps out |
|---|---|
.terraform/ | The downloaded providers and modules |
*.tfstate | terraform.tfstate |
*.tfstate.* | terraform.tfstate.backup, the copy of the previous state that OpenTofu keeps |
*.tfplan | Saved plans with a .tfplan ending |
Step 3: Check Again
git status
On branch master
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
.gitignore
.terraform.lock.hcl
index.html
main.tf
nothing added to commit but untracked files present (use "git add" to track)
The providers, the state and the plan are gone from the list. What’s left is safe to commit: your configuration, the .gitignore itself, the lock file, and index.html, the page this project builds.
Keep the Lock File
Don’t ignore .terraform.lock.hcl. It records the exact provider versions, and both tofu init and OpenTofu’s documentation ask you to commit it, so everyone who uses the project gets the same versions.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Writing .terraform* as a shortcut | It also matches .terraform.lock.hcl, so the lock file never reaches Git. | Write .terraform/ with the slash, as above. |
Adding the .gitignore after committing the state | Git keeps tracking the state file, because .gitignore doesn’t affect files Git already tracks. | Stop tracking it with git rm --cached terraform.tfstate. The file stays on your disk. |
Naming plan files without .tfplan | A plan saved as tfplan isn’t matched by *.tfplan. | End plan file names with .tfplan, or add their names to the .gitignore. |
FAQ
I already pushed a state file. What now?
Stop tracking it with git rm --cached terraform.tfstate, add the .gitignore, and commit. Older commits still contain the file, so change any password or key that was in it.
Where does the state go if it isn’t in Git?
For a project on your own computer, it stays in the folder. Teams keep state in a shared, locked backend instead, which later parts of the OpenTofu Tutorial set up.
Conclusion
Four lines keep an OpenTofu project’s private files out of Git: .terraform/, *.tfstate, *.tfstate.* and *.tfplan. Commit your .tf files, the .gitignore and .terraform.lock.hcl, and check git status before your first commit.
Related
- OpenTofu Tutorial — Part 2: Your First OpenTofu Project: init, plan, apply and destroy
- What Does tofu init Do in OpenTofu?
- How to Save an OpenTofu Plan and Apply It
Additional Resources
- Sensitive Data in State (OpenTofu docs)
- Dependency Lock File (OpenTofu docs)
- gitignore and git rm (Git documentation)
OpenTofu® is a registered trademark of LF Projects, LLC. Other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by the OpenTofu project.
Leave a Reply