Terraform Plan File Management#

Atlantis produces .tfplan binary files during the plan phase and must carefully track their lifecycle to prevent stale plans from being applied. Because .tfplan files are untracked by git (and commonly listed in .gitignore), they survive git reset --hard operations — requiring explicit cleanup logic whenever the working directory is updated to a new commit.

File Naming and Path Conventions#

Plan file paths are assembled by helpers in server/core/runtime/runtime.go:

When LocalSharePlanDir is not set (default), plan files live alongside source code inside the per-PR clone directory. When a separate plan store is configured, files are stored under {LocalSharePlanDir}/repos/{repo}/{pull_num}/{workspace}/{rel_dir}/.

Stale Plan Cleanup on Working Directory Update#

When a new commit is pushed to a PR, Atlantis updates the existing clone via updateToRef rather than recloning from scratch (a performance optimization introduced in a prior refactor). Since git reset --hard does not remove untracked files, plan files from earlier commits would persist and could be picked up by a subsequent bare atlantis apply. 1

The fix (merged in PR #6358) added cleanStalePlanFiles, called at the end of updateToRef:

• Co-located plans (default): runs git clean -f -x -e .terragrunt-cache -- ':(glob)**/*.tfplan' 2. The -x flag is required because plan files are typically git-ignored. .terragrunt-cache is explicitly excluded from cleanup to preserve cached provider downloads.
• Separate plan store (LocalSharePlanDir ≠ DataDir): calls removeTfPlanFiles(planWorkspaceDir) to walk and delete .tfplan files from the plan store directory for the PR workspace, skipping .terragrunt-cache 3.

A full reclone (triggered by a base-branch change under merge strategy, or on git errors) also implicitly removes all plan files by wiping the entire working directory, as verified in TestClone_ReCloneOnBaseChangeForMergeStrategy.

Note: MergeAgain (re-merge on a diverged base without a new head commit) intentionally does not purge plan files — the head commit has not changed, so existing plans remain valid. 4

Git-Ignore Behavior for .tfplan Files#

Atlantis does not write a repository .gitignore; instead, plan files in user repos are often already covered by the repo's own .gitignore. The test harness models this precisely using .git/info/exclude:

// ignorePlanFiles simulates a repo that git-ignores *.tfplan
func ignorePlanFiles(t *testing.T, cloneDir string) {
    os.WriteFile(filepath.Join(cloneDir, ".git/info/exclude"), []byte("*.tfplan\n"), 0600)
}

This is why git clean -x (include ignored files) is necessary — a plain git clean would leave ignored plan files in place. 2

Cleanup in the Apply Validation Path#

Stale plan removal also happens outside the working directory layer. rejectProjectPlan deletes the plan file on any validation failure (e.g. status check failure, hash mismatch), ensuring that an invalid plan does not linger on disk for a future apply attempt. 5

Test Helpers#

Tests in server/events/working_dir_test.go verify end-to-end plan cleanup behavior with two small helpers:

• createPlanFile(t, path) — creates a dummy .tfplan file at an arbitrary (potentially nested) path.
• ignorePlanFiles(t, cloneDir) — writes to .git/info/exclude to simulate a repo whose .gitignore excludes plan files.

Key test scenarios:

• TestClone_ResetOnWrongCommit — verifies root and nested .tfplan files are deleted after a branch-strategy reset; asserts .terragrunt-cache plan files are preserved.
• TestClone_ResetOnWrongCommitWithMergeStrategy — same assertions under the merge strategy path.
• TestClone_MasterHasDiverged — asserts plan files are not deleted by MergeAgain (re-merge on diverged base), only by ref updates that change the PR head commit.
• TestClone_DoNotReCloneOnBaseChangeForBranchStrategy — asserts plan files are cleaned even in the branch (non-merge) strategy when the head commit changes.