Limit Terraform Plan/Apply to Changed Stacks with Terramate

The Problem: Unbounded Infrastructure Changes

When managing multiple Terraform or OpenTofu environments in a monorepo, running terraform plan or apply across all stacks wastes time and increases the risk of unintended changes. Terramate solves this with terramate run --only-changed, which limits execution to stacks containing files modified since a base branch.

How Terramate Detects Changed Stacks

Terramate uses git diff to compare your current branch against a configured base branch (default: main). It maps changed files to stacks based on directory structure, then filters execution accordingly.

Step 1: Define Stacks in terramate.tm.hcl

Create a root terramate.tm.hcl file that tells Terramate where your stacks live:

stacks {
  paths = ["environments/*"]
}

This discovers all directories under environments/ as individual stacks.

Step 2: Verify Discovered Stacks

Run this in your project root:

terramate list

Expected output shows each stack with its path and generated variables like tm_stack_name.

Step 3: Run Commands Only in Changed Stacks

After making changes in one stack, execute:

terramate run --only-changed -- terraform plan -out=tfplan

Terramate will only run terraform plan in stacks containing modified files. Check the output for which stacks were processed.

Step 4: Apply with Confidence

Once a plan is approved, apply only to affected stacks:

terramate run --only-changed -- terraform apply -auto-approve tfplan

Configuration Options

Terramate respects these environment variables and flags:

Option	Description
--only-changed	Limit execution to stacks with changes
--base-branch	Override base branch (default: main)
TG_TF_WORKING_DIR	Override stack working directory

Common Mistakes and Fixes

• Missing changes in untracked files: Terramate only detects tracked git changes. Use git add . before running.
• Running on detached HEAD: Git operations may fail. Ensure you're on a branch.
• Shared state conflicts: Terramate doesn't serialize applies. Stacks using the same backend need external locking.
• Wrong base branch: Use --base-branch develop if comparing against develop instead of main.

Verification Checklist

1. Confirm version: terramate --version
2. Run terramate list to see all stacks
3. Make a change in one stack directory
4. Run terramate run --only-changed -- echo {tm_stack_name}
5. Only the modified stack should print its name

Limitations to Know

• Change detection requires a git repository with proper branching.
• Terramate doesn't manage Terraform versions or providers; those remain in your stack configuration.
• Concurrent applies to stacks sharing state can corrupt state—use external locking mechanisms.