Completed Experiments

These experiments have been completed and their features are now available by default. The experiment flags are no longer needed.

`auto-provider-cache-dir`

Enable native OpenTofu provider caching by setting TF_PLUGIN_CACHE_DIR instead of using Terragrunt’s internal provider cache server.

`auto-provider-cache-dir` - What it does

This experiment automatically configures OpenTofu to use its built-in provider caching mechanism by setting the TF_PLUGIN_CACHE_DIR environment variable. This approach leverages OpenTofu’s native provider caching capabilities, which are more robust for concurrent operations in OpenTofu 1.10+.

This experiment flag is no longer needed, as the auto-provider-cache-dir feature is now enabled by default when using OpenTofu >= 1.10.

Requirements:

OpenTofu version >= 1.10 is required
Only works when using OpenTofu (not Terraform)

Disabling the feature:

You can disable the auto-provider-cache-dir feature using the --no-auto-provider-cache-dir flag:

terragrunt run --all apply --no-auto-provider-cache-dir

`auto-provider-cache-dir` - How to provide feedback

Now that the auto-provider-cache-dir experiment is complete, please provide feedback in the form of standard GitHub issues.

`auto-provider-cache-dir` - Criteria for stabilization

To transition the auto-provider-cache-dir feature to stable, the following have been completed:

Comprehensive testing to confirm the safety of concurrent runs using the same provider cache directory.
Performance comparison with the existing provider cache server approach.
Documentation and examples of best practices for usage.
Community feedback on real-world usage and any edge cases discovered.

`cas`

Support for Terragrunt Content Addressable Storage (CAS).

`cas` - What it does

Allow Terragrunt to store and retrieve Git repositories from a Content Addressable Storage (CAS) system.

The CAS is used to speed up catalog cloning, OpenTofu/Terraform source cloning, and stack generation by avoiding redundant downloads of Git repositories. When used with stacks, it also allows catalog authors to use relative paths in source attributes via the update_source_with_cas attribute.

This experiment flag is no longer needed, as the CAS is now enabled by default. Disable it with the --no-cas flag.

`cas` - How to provide feedback

Now that the cas experiment is complete, please provide feedback in the form of standard GitHub issues.

`cas` - Criteria for stabilization

To transition the cas feature to a stable release, the following were completed:

Add support for storing and retrieving catalog repositories from the CAS.
Add support for storing and retrieving OpenTofu/Terraform modules from the CAS.
Add support for storing and retrieving Unit/Stack configurations from the CAS.

`catalog-redesign`

Redesigned terragrunt catalog TUI with whole-repository discovery, tabbed browsing, and an interactive scaffolding form.

`catalog-redesign` - What it does

Replaces the existing terragrunt catalog experience with a redesigned TUI that removes the need for manual configuration. The new catalog discovers modules and templates across the whole repository, lets you browse them in tabbed views, and scaffolds a selected component through an interactive form.

This experiment flag is no longer needed, as the redesigned TUI is now the default terragrunt catalog experience.

Discovery walks the entire repository instead of only a modules/ directory, so modules and templates can live anywhere. Boilerplate templates are discovered as a distinct component kind alongside OpenTofu/Terraform modules and labeled as templates in the UI. Catalog authors can commit a .terragrunt-catalog-ignore file at the repo root to exclude directories such as examples/ or test/ from discovery. See Excluding paths from discovery for the supported pattern syntax.

The list view is split into All, Modules, and Templates tabs with All selected by default. Press tab and shift+tab to cycle between them; each tab keeps its own cursor and search filter.

Each list entry shows a metadata row with a component-type pill (module, template), the source URL it was discovered from, and a version pill when a release tag is available, so it is clear which repository or path a component came from.

Pressing s on a selected component opens an in-TUI form that prompts for every variable the component exposes (.tf variable blocks for modules and templates, values.* references for units and stacks). The form is modal: j/k (or arrows) navigate between fields, enter enters edit mode on a text field or toggles a boolean checkbox in place, esc returns from edit to navigate, x marks an optional field “use default” so it’s left out of the generated file, ctrl+d finishes, and esc from navigate cancels back to the catalog. Only fields the user explicitly sets are written to the generated terragrunt.hcl or terragrunt.values.hcl; required fields the user never set still produce # TODO: fill in value placeholders. Pressing S (capital) keeps the original placeholder-only flow for users who want to populate values by editing the generated file.

`catalog-redesign` - How to provide feedback

Now that the catalog-redesign experiment is complete, please provide feedback in the form of standard GitHub issues.

`catalog-redesign` - Criteria for stabilization

To transition the catalog-redesign feature to a stable release, the following were completed:

Multiple catalog browse views (All, Modules, Templates tabs) are implemented and functional.
Catalog launches without requiring manual configuration (no pre-existing catalog block needed).
Discovery walks the entire repository, surfacing modules and boilerplate templates wherever they live.
Authors can exclude paths from discovery with a .terragrunt-catalog-ignore file.
Component source is visible in the UI for each catalog entry.
Component type (module, unit, stack, template) is clearly indicated in the UI.
An interactive scaffold form prompts for each variable a component exposes and generates terragrunt.hcl/terragrunt.values.hcl.
Integration tests cover the core catalog workflows.
Positive feedback from users using the redesigned catalog in production environments.

`cli-redesign`

Support for the new Terragrunt CLI design.

`cli-redesign` - What it does

Enabled features from the CLI Redesign RFC.

This experiment flag is no longer needed, as the CLI Redesign is now the default.

`cli-redesign` - How to provide feedback

Now that the CLI Redesign experiment is complete, please provide feedback in the form of standard GitHub issues.

`cli-redesign` - Criteria for stabilization

To transition cli-redesign features to a stable the following have been completed:

`dag-queue-display`

Display the run queue as a DAG tree showing dependency hierarchy.

`dag-queue-display` - What it does

The run queue is rendered as a tree that visualizes dependency relationships between units, instead of the flat list Terragrunt displayed previously. Independent units appear as siblings at the root, while dependent units are nested under their dependencies. This experiment flag is no longer needed, as the tree display is now the default.

The tree also changes its header message based on execution direction:

Apply/Plan: “starting with dependencies and then their dependents”
Destroy: “starting with dependents and then their dependencies”

terragrunt run --all -- plan

Example output:

The following units will be run, starting with dependencies and then their dependents:
.
├── monitoring
╰── vpc
    ╰── database
        ╰── backend-app
            ╰── frontend-app

`dag-queue-display` - How to provide feedback

Now that the dag-queue-display experiment is complete, please provide feedback in the form of standard GitHub issues.

`dag-queue-display` - Criteria for stabilization

To transition the dag-queue-display feature to a stable release, the following were completed:

Community feedback on the tree visualization format
Confirm readability with large dependency graphs
Confirm compatibility with CI/CD log viewers (color and Unicode handling)

`filter-flag`

Support for sophisticated unit and stack filtering using the --filter flag.

`filter-flag` - What it does

The --filter flag provides a sophisticated querying syntax for targeting units and stacks in Terragrunt commands. This unified approach replaces the need for multiple queue control flags and offers powerful filtering capabilities.

This experiment flag is no longer needed, as the --filter flag is now available by default in the find, list, and run commands.

Supported Filtering Types:

Name-based filtering: Target units/stacks by their directory name (exact match or glob patterns)
Path-based filtering: Target units/stacks by their file system path (relative, absolute, or glob patterns)
Attribute-based filtering: Target units by configuration attributes:
- type=unit or type=stack - Filter by component type
- external=true or external=false - Filter by whether the unit/stack is an external dependency (outside the current working directory)
- name=pattern - Filter by name using glob patterns
Negation filters: Exclude units using the ! prefix
Filter intersection: Combine filters using the | operator for results pruning
Multiple filters: Specify multiple --filter flags to union results
Git-based filtering: Target units/stacks changed between Git references using the [ref...ref] syntax
Dependency/dependent traversal: Expand results to dependencies and dependents using the ... syntax

The legacy queue control flags (--queue-exclude-dir, --queue-excludes-file, --queue-exclude-external, --queue-include-dir, --queue-include-external, --queue-include-units-including, --queue-strict-include) remain supported alongside --filter.

`filter-flag` - How to provide feedback

Now that the filter-flag experiment is complete, please provide feedback in the form of standard GitHub issues.

`filter-flag` - Criteria for stabilization

To transition the filter-flag feature to a stable release, the following were completed:

`mark-many-as-read`

Mark many files as read in one step, so reading-based filter expressions cascade changes from shared files to the units that consume them.

`mark-many-as-read` - What it does

This experiment flag is no longer needed; the two behaviors it gated are now enabled by default:

When a unit’s terraform block points at a local module source, Terragrunt walks that directory and records every *.tf, *.tf.json, *.hcl, *.tofu, and *.tofu.json file as read for the unit. Non-source files such as README.md are skipped. Remote sources (Git, registry, S3, etc.) are not walked.
The mark_glob_as_read(pattern) HCL function. It expands a glob using gobwas/glob syntax and marks every matching file as read, returning the list of absolute paths that matched. See the HCL reference for pattern syntax and examples.

Both behaviors feed the same reading tracker that powers the reading= filter attribute, so a change to a local module file or a globbed configuration file is picked up by --filter 'reading=<path>' and matches every unit that reads it.

`mark-many-as-read` - How to provide feedback

Now that the mark-many-as-read experiment is complete, please provide feedback in the form of standard GitHub issues.

`mark-many-as-read` - Criteria for stabilization

To transition the mark-many-as-read feature to a stable release, the following were completed:

Confirm local module walking handles nested modules sensibly across macOS, Linux, and Windows.
Confirm glob semantics match user expectations for common patterns, especially ** with a wildcard trailing segment.
Positive feedback from users relying on reading-based filters in production pipelines.
Integration tests covering the interaction between module walking, mark_glob_as_read, and --filter 'reading=...'.

`opt-out-auth`

Opt out of running --auth-provider-cmd during the discovery phase.

`opt-out-auth` - What it does

By default, Terragrunt runs --auth-provider-cmd once per parsed component during the discovery phase, so configuration parsing can reliably resolve HCL functions such as get_aws_account_id and run_cmd. On large repositories, this dominates wall-clock time because the auth command runs for every discovered unit rather than only the subset that will actually run.

The --no-discovery-auth-provider-cmd flag (env: TG_NO_DISCOVERY_AUTH_PROVIDER_CMD) skips those discovery-time auth invocations. The auth provider command still runs normally for the units that actually execute. This experiment flag is no longer needed, as --no-discovery-auth-provider-cmd is now available by default.

Units whose discovery-relevant blocks depend on credentials produced by --auth-provider-cmd will fail to parse with the flag set. Use it when you know parsing will resolve successfully without any prior authentication.

terragrunt run --all \
  --no-discovery-auth-provider-cmd \
  --queue-include-units-reading=./changed-file.txt \
  plan

`opt-out-auth` - How to provide feedback

Now that the opt-out-auth experiment is complete, please provide feedback in the form of standard GitHub issues.

`opt-out-auth` - Criteria for stabilization

To transition the opt-out-auth feature to a stable release, the following were completed:

Confirm the discovery-phase opt-out covers the auth scenarios users rely on without surprising parse failures.
Measure the wall-clock improvement on large run --all invocations with reading-based filters.
Decide whether additional phases warrant their own opt-out flags.
Community feedback on real-world usage.

`report`

Support for Terragrunt Run Reports and Summaries.

`report` - What it does

Allows generation of run reports and summary displays. This experiment flag is no longer needed, as the report feature is now stable and available by default.

`report` - How to provide feedback

Now that the report experiment is complete, please provide feedback in the form of standard GitHub issues.

`report` - Criteria for stabilization

To transition the report feature to stable, the following have been completed:

Add support for generating reports (in CSV format by default).
Add support for displaying summaries of runs.
Add ability to disable summary display.
Add support for generating reports in JSON format.
Add comprehensive integration tests for the report experiment.
Finalize the design of run summaries and reports.

`runner-pool`

Proposes replacing Terragrunt’s group-based execution with a dynamic runner pool that schedules Units as soon as dependencies are resolved. This improves efficiency, reduces bottlenecks, and limits the impact of individual failures.

`runner-pool` - What it does

Allow usage of experimental runner pool implementation for units execution.

`runner-pool` - How to provide feedback

Provide your feedback on the Runner Pool.

`runner-pool` - Criteria for stabilization

To transition the runner-pool feature to a stable release, the following must be addressed:

Use new discovery and queue packages to discover units.
Add support for including/excluding external units in the discovery process.
Add runner pool implementation to execute discovered units.
Add integration tests to track that the runner pool works in the same way as the current implementation.
Add performance tests to track that the runner pool implementation is faster than the current implementation.
Add support for fail fast behavior in the runner pool.
Improve the UI to queue to apply.
Add OpenTelemetry support to the runner pool.

`stack-dependencies`

Support for the autoinclude block in terragrunt.stack.hcl files, enabling dependency relationships and configuration overrides during stack generation.

`stack-dependencies` - What it does

This experiment flag is no longer needed, as the autoinclude block is now available by default. The block nests inside unit and stack blocks in terragrunt.stack.hcl files.

The autoinclude block allows users to define dependency blocks and arbitrary configuration that gets generated into an autoinclude file during stack generation. This file is automatically merged into the unit/stack configuration when parsed.

The generated filename depends on the component kind:

Unit autoincludes are written as terragrunt.autoinclude.hcl next to the unit’s terragrunt.hcl.
Stack autoincludes are written as terragrunt.autoinclude.stack.hcl next to the nested stack’s terragrunt.stack.hcl. The .stack.hcl suffix mirrors terragrunt.stack.hcl so tooling (LSP, read_terragrunt_config(), indexers) can identify the file’s purpose from its name alone.

The feature also includes:

unit.<name>.path and stack.<name>.path variables for referencing sibling component paths, both inside autoinclude blocks and in a unit or stack block’s values (so a parent stack can pass a component path down to a child stack)
dependency blocks targeting stack directories: aggregated outputs from all units in the stack (dependency.stack_name.outputs.unit_name.output_key)
Automatic shallow merge of terragrunt.autoinclude.hcl into unit configurations, using the same default merge strategy as a regular include (on conflicting top-level keys, the autoinclude wins and replaces the unit’s value)
Stack dependency expansion in the run queue: depending on a stack waits until all its units complete

Unit-to-unit dependencies within a stack

unit "vpc" {
  source = "../catalog/units/vpc"
  path   = "vpc"
}

unit "app" {
  source = "../catalog/units/app"
  path   = "app"

  autoinclude {
    dependency "vpc" {
      config_path = unit.vpc.path
    }

    inputs = {
      vpc_id = dependency.vpc.outputs.vpc_id
    }
  }
}

Dependencies on entire stacks

stack "infra" {
  source = "../catalog/stacks/infra"
  path   = "infra"
}

unit "app" {
  source = "../catalog/units/app"
  path   = "app"

  autoinclude {
    dependency "infra" {
      config_path = stack.infra.path
    }

    inputs = {
      vpc_id = dependency.infra.outputs.vpc.vpc_id
    }
  }
}

`stack-dependencies` - How to provide feedback

Now that the stack-dependencies experiment is complete, please provide feedback in the form of standard GitHub issues.

`stack-dependencies` - Implementation roadmap

Phased parser for terragrunt.stack.hcl: parse the file body, evaluate locals and values, apply include merges, then decode unit/stack blocks and resolve autoinclude. This lets unit/stack blocks use local.*, values.*, and Terragrunt functions.
terragrunt run --all discovery can scan generated nested stack files without evaluating the unit source.
Unify strict and permissive parser into a single code path
Add integration tests and test fixtures for end-to-end validation
Add E2E validation with stack run apply and stack run destroy

Catalog source preservation across stack copy: nested stack files copied into .terragrunt-stack/<name>/ get a .terragrunt-stack-origin marker file, so bare relative ../../units/... paths resolve against the original catalog, not the copy. Only applies to local stack sources; remote and CAS-fetched stacks are unchanged.
PartialEval depth guard (maxPartialEvalDepth = 10000) and IsWhollyKnown / IsNull checks on the fast path and traversal/template/conditional/parens branches, preventing crashes on unknown values or pathological nesting.
Typed errors with Unwrap() across the package (FileParseError, FileDecodeError, IncludeValidationError, LocalEvalError, MalformedDependencyError, AutoIncludeParserStageError) preserving hcl.Diagnostics for source positions.
Deterministic cycle reports in LocalsCycleError.Names (DFS dep iteration sorted).
resolveStackFilePath returns (string, bool): callers branch on isStackCandidate instead of a sentinel empty string. Backed by a two-arg fuzz that exercises raw/target independently.
Removed Unicode from internal/hclparse source files (ASCII-only); intentional Unicode test fixtures remain.

The .terragrunt-stack-origin marker file is no longer written when nested stack files are copied into .terragrunt-stack/<name>/. Use update_source_with_cas = true on unit and stack blocks to keep relative source paths working in catalog stack files; relative attributes are rewritten to cas:: references at generation time so the generated tree is self-contained.
Community feedback on autoinclude syntax and merge behavior
Validate performance at scale

`stacks`

Support for Terragrunt stacks.

`stacks` - What it does

Enable stack command to manage Terragrunt stacks.

`stacks` - Criteria for stabilization

To transition the stacks feature to a stable release, the following must be addressed:

Add support for stack run * command
Add support for stack output commands to extend stack-level operations.
Integration testing for recursive stack handling across typical workflows, ensuring smooth transitions during plan, apply, and destroy operations.
Confirm compatibility with parallelism flags (e.g., --parallel), especially for stacks with dependencies.
Ensure that error handling and failure recovery strategies work as intended across large and nested stacks.

Completed Experiments

auto-provider-cache-dir

auto-provider-cache-dir - What it does

auto-provider-cache-dir - How to provide feedback

auto-provider-cache-dir - Criteria for stabilization

cas

cas - What it does

cas - How to provide feedback

cas - Criteria for stabilization

catalog-redesign

catalog-redesign - What it does

catalog-redesign - How to provide feedback

catalog-redesign - Criteria for stabilization

cli-redesign

cli-redesign - What it does

cli-redesign - How to provide feedback

cli-redesign - Criteria for stabilization

dag-queue-display

dag-queue-display - What it does

dag-queue-display - How to provide feedback

dag-queue-display - Criteria for stabilization

filter-flag

filter-flag - What it does

filter-flag - How to provide feedback

filter-flag - Criteria for stabilization

mark-many-as-read

mark-many-as-read - What it does

mark-many-as-read - How to provide feedback

mark-many-as-read - Criteria for stabilization

opt-out-auth

opt-out-auth - What it does

opt-out-auth - How to provide feedback

opt-out-auth - Criteria for stabilization

report

report - What it does

report - How to provide feedback

report - Criteria for stabilization

runner-pool

runner-pool - What it does

runner-pool - How to provide feedback

runner-pool - Criteria for stabilization

stack-dependencies

stack-dependencies - What it does