What gets planned

tfv finds Terraform, OpenTofu and Terragrunt projects on its own and plans the ones a pull request affects.

Project detection

A project is planned when a PR changes:

• the project's own files;
• modules it uses, and the modules those use;
• Terragrunt includes (such as _envcommon), dependency units, read_terragrunt_config(...), file(...), and hook scripts;
• parent root.hcl, env.hcl and version pins.

Paths built with Terragrunt functions (get_repo_root(), get_terragrunt_dir(), find_in_parent_folders()) and with locals are resolved too.

Each project is planned with the exact tool version it pins. When it pins none, tfv uses TFV_DEFAULT_VERSION (latest by default).

Watch extra files: tfv:watch

For a file no config mentions, such as source code that a build step packages, add a watch. Globs work, a folder means everything inside it, and watches add to automatic detection; they never replace it.

In any .tf, .tofu or .hcl file:

# tfv:watch /lambda/orders/**/*.py scripts/build.sh

In Terragrunt, with its functions:

locals {
  tfv_watch = ["${get_repo_root()}/schemas/*.json"]
}

Or in the repo's tfv.yaml:

projects:
  - dir: stacks/orders
    watch: ["/lambda/orders/**"]

Paths are relative to the project folder; a leading / means the repo root.

Terragrunt dependencies

tfv never applies a dependency for you, and never applies a plan built on wrong outputs.

• Mock outputs. A unit planned with a dependency's mock_outputs (because the dependency isn't applied yet) is flagged in the PR and can't be applied, not even with --override. tfv tells you to apply the dependency first, for example tfv apply -p live/prod/vpc.
• Re-plans. When you apply a dependency, tfv re-plans the units that depend on it with the real outputs. That's a plan only, for you to review and apply.
• Outdated plans. A plan made before one of its dependencies was applied is refused with "re-plan first".
• Order. Several units applied in one command go in dependency order, and independent ones run in parallel.

Example

tfv plan                       # vpc and app are planned; app uses vpc's mock_outputs
tfv apply -p live/prod/app     # refused: app was planned with mock outputs
tfv apply -p live/prod/vpc     # applies vpc; tfv re-plans app with the real outputs
tfv apply -p live/prod/app     # applies app once you've reviewed the new plan