🏎️ Performance Improvements

Partial parse used for get_working_dir()
To assess where Terragrunt is going to run OpenTofu, it needs partially parsed information from the relevant terragrunt.hcl file of the unit running the HCL get_working_dir() function. The function was performing a full parse of the terragrunt.hcl file, which can be slow for users with large HCL configurations.
Given that the parse only requires access to the value of source in the terraform block, a partial parse is now performed by the function, only looking at the contents of the terraform block, improving performance significantly.

🐛 Bug Fixes

False positive parsing errors suppressed
When parsing an include that defined dependencies, the HCL parser used by Terragrunt would emit spurious errors that are internally ignored. Those messages are now suppressed.

Signal propagation for interrupts fixed
A bug in how Terragrunt forwarded signals to processes it spawned (like running tofu) resulted in underlying processes receiving SIGKILL signals rather than the original signal (e.g. SIGINT) sent to the Terragrunt process. That has been fixed.

🧹 Chores

Avoiding contextcheck suppression
While not changing much functionally in Terragrunt, this release did involve quite a lot of changes to Terragrunt internals. The majority of these changes related to better propagation of the Golang context object to better obey Golang best practices. These issues were reported by the contextcheck linter in the codebase, but the findings were suppressed due to the scope of work required to address them.

These changes should make it so that context is propagated correctly more reliably in the codebase, increasing the usefulness of things like OpenTelemetry tracing and reduced resource usage.

Note that some public function signatures have changed in the Terragrunt codebase, which may be a breaking change to users consuming Terragrunt as a library. Given that we do not offer any stability guarantees for usage of Terragrunt as a library, these changes are still to be included in a patch release.

What's Changed

• perf: Using a partial parse for get_working_dir() by @yhakbar in #5318
• fix: false positive parsing errors by @denis256 in #5258
• fix: Fixing signal propagation issues by @yhakbar in #5326
• fix: Locking during run ensure calls by @yhakbar in #5312
• chore: Avoiding contextcheck suppression by @yhakbar in #5320
• chore: Fixing flaky tests by @yhakbar in #5316
• chore: Adding flake utility by @yhakbar in #5311
• chore: Cleaning up HCL fn spans by @yhakbar in #5315
• build(deps): bump github.com/cloudflare/circl from 1.3.3 to 1.6.1 in /test/flake by @dependabot[bot] in #5324
• build(deps): bump golang.org/x/oauth2 from 0.25.0 to 0.27.0 in /test/flake by @dependabot[bot] in #5323
• build(deps): bump golang.org/x/crypto from 0.7.0 to 0.45.0 in /test/flake by @dependabot[bot] in #5322

Full Changelog: v0.97.1...v0.97.2

Original source Report a problem

✨ New Features

All HCL functions instrumented with OpenTelemetry
All Terragrunt HCL functions are now instrumented to emit telemetry when they run, giving more insight into HCL function performance, and usage.
HCL parsing telemetry improved
Additional fidelity has been added to traces emitted during parsing to give insight as to why configuration parsing is being performed, and how.

🐛 Bug Fixes

plan -destroy called correctly for --filter-affected
A bug in the logic for --filter-affected resulted in removed units getting planned/applied instead of being destroyed when users supplied --filter-allow-destroy. That bug has been fixed.
Nested spans in track parents appropriately even when the TRACEPARENT environment variable is used.
A bug in the logic for propagating TRACEPARENT as the ultimate parent of traces started in Terragrunt prevented child traces from properly tracking parent spans. That bug has been fixed.
Reports on runs in worktrees now use relative directories to worktree root
Instead of displaying runs of units in Git worktrees during Git-based filter expression runs with the absolute path of their directories in a temporary directory, they now display with the path to the unit relative to the root of the worktree.
Unnecessary relationship discovery prevented
Discovery of relationships between units has been made opt-in in the discovery process. This will result in no changes to usage of commands like run --all, but will significantly improve the performance of commands like list and stack generate.

What's Changed

• feat: Adding spans for HCL functions by @yhakbar in #5306
• feat: Increasing volume and fidelity of config parse telemetry by @yhakbar in #5309
• fix: Fixing nested spans by @yhakbar in #5305
• fix: Fixing plan -destroy for --filter-affected by @yhakbar in #5295
• fix: Fixing worktree reports by @yhakbar in #5308
• fix: Avoiding unnecessary relationship discovery by @yhakbar in #5313
• chore: Dropping usage of MapToSlice and StringListInsert by @yhakbar in #5297
• docs: Adding ambassadors by @karlcarstensen in #5296
• docs: Ambassador Lorelei by @karlcarstensen in #5302

Full Changelog: v0.97.0...v0.97.1

Original source Report a problem

⚒️ Breaking Changes

The --queue-strict-include flag is deprecated

Terragrunt no longer automatically includes dependencies of included units. As such the --queue-strict-include flag is no longer useful in the Terragrunt CLI.
The flag has been deprecated, and no longer does anything. This flag will not be removed before 2.0.

Run report no longer reports --queue-exclude-dir as a reason for exclusion

Run reports no longer report on units excluded from runs as a consequence of the --queue-exclude-dir flag.

The --units-that-include flag is deprecated

The --units-that-include flag is now an alias for the reading= attribute filter, just like the --queue-include-units-reading flag.
Given that the two flags no longer differ in functionality, and that the functionality of the --units-that-include is no longer strictly including units that are included, the flag has been deprecated.

The double-star strict control is complete

The globbing behavior of Terragrunt in CLI flags has been updated to match all paths when ending with a trailing ** .

🧪 Experiments Completed

The filter-flag experiment is completed

The filter-flag experiment is completed, and the --filter flag is now generally available.
You can use filter expressions as a single unified API for controlling the Run Queue, replacing the need to use the following CLI flags:
Legacy —queue flag
Equivalent —filter expression
—-queue-include-dir=path
—-filter='{./path}'
—-queue-exclude-dir=path
—-filter='!{./path}'
--queue-include-units-reading=root.hcl
--filter='reading=root.hcl'
--units-that-include=root.hcl
--filter='reading=root.hcl'
--queue-include-external-dependencies
--filter='{./**}...'
--queue-excludes-file=excludes.txt
--filters-file='filters.txt' *
--graph
--filter='...{.}'
Note that the file used for the --queue-excludes-file does not directly translate to the kind of file you can use for a --filters-file. To learn more, see the documentation.
The table above also explains the aliasing that has been done internally to replace queue flags with their filter equivalents. The aliasing for these queue flags is present purely for backwards compatibility purposes, but they are not going to emit deprecation warnings, and will not be removed before the Terragrunt 1.0 release.
You are heavily encouraged to adopt the new --filter flag for your infrastructure targeting needs as soon as feasible in your workflows. It will offer a significantly more flexible and powerful experience.
To learn more see the Filters feature documentation.
🐛 Bug Fixes

The get_original_terragrunt_dir() function is now supported in terragrunt.stack.hcl files

When authoring explicit stacks, using the get_original_terragrunt_dir() HCL function in terragrunt.stack.hcl files will now return the directory where the terragrunt.stack.hcl file lives, even when the configuration is read from another stack/unit using read_terragrunt_config().

Using Git-based expressions with the --out-dir flag is fixed

When using Git-based expressions using the --filter flag, the relative path of units relative to their respective Git worktree roots is used for determining where the plan file will be saved, rather than a path in the relevant Git worktree.

Color for output fetching is suppressed more reliably

Terragrunt will use tofu output -json / terraform output -json more reliably when users expect a lack of colors (like when colors are suppressed for Terragrunt).

What's Changed

fix: Using testing/synctest to make TestWriteUnitLevelSummary more reliable by @yhakbar in #5253

fix: Fixing report run duplication error by @yhakbar in #5252

fix: improved log error messages by @denis256 in #5256

fix: get_original_terragrunt_dir during stack generate by @philipmckenna-symphony in #5176

fix: saving of plan in git based filtering by @denis256 in #5288

fix: add no color for dependency fetching by @denis256 in #5285

fix: added git worktree cleanup on errors by @denis256 in #5254

docs: Adding ambassador by @karlcarstensen in #5261

docs: Adding ambassador by @karlcarstensen in #5259

docs: Adding announcement banner by @karlcarstensen in #5260

docs: Documenting backport of queue flags into filter flags by @yhakbar in #5263

docs: Adding ambassador by @karlcarstensen in #5266

chore: Cleaning up test symlinks resolution by @yhakbar in #5251

chore: Dropping ListContains and ListEquals and using standard library instead by @yhakbar in #5221

chore: Adding debug log for assume already applied by @yhakbar in #5198

chore: Removing latest Terraform OSS workflows by @yhakbar in #5262

chore: Backporting queue flags into filter flags by @yhakbar in #5241

chore: on demand no proxy build execution by @denis256 in #5277

chore: opentelemetry and aws dependencies update by @denis256 in #5279

New Contributors

@philipmckenna-symphony made their first contribution in #5176

Full Changelog: https://github.com/gruntwork-io/terragrunt/compare/v0.96.1..v.0.97.0

Original source Report a problem

⚒️ Breaking Changes

The --queue-strict-include flag is deprecated

Terragrunt no longer automatically includes dependencies of included units. As such the --queue-strict-include flag is no longer useful in the Terragrunt CLI.

The flag has been deprecated, and no longer does anything. This flag will not be removed before 2.0.

Run report no longer reports --queue-exclude-dir as a reason for exclusion

Run reports no longer report on units excluded from runs as a consequence of the --queue-exclude-dir flag.

The --units-that-include flag is deprecated

The --units_that-include flag is now an alias for the reading= attribute filter, just like the --queue-include-units-reading flag.

Given that the two flags no longer differ in functionality, and that the functionality of the --units-that-include is no longer strictly including units that are included, the flag has been deprecated.

The double-star strict control is complete

The globbing behavior of Terragrunt in CLI flags has been updated to match all paths when ending with a trailing ** .

🧪 Experiments Completed

• The filter-flag experiment is completed

• The filter-flag experiment is completed, and the --filter flag is now generally available.
  You can use filter expressions as a single unified API for controlling the Run Queue, replacing the need to use the following CLI flags:

  Legacy —queue flag
  Equivalent —filter expression
  —-queue-include-dir=path
  —-filter='{./path}'
  —-queue-exclude-dir=path
  —-filter='!{./path}'
  --queue-include-units-reading=root.hcl
  --filter='reading=root.hcl'
  --units-that-include=root.hcl
  --filter='reading=root.hcl'
  --queue-include-external-dependencies
  --filter='{./**}...'
  --queue-excludes-file=excludes.txt
  --filters-file='filters.txt' *
  --graph
  --filter='...{.}'
  Note that the file used for the --queue-excludes-file does not directly translate to the kind of file you can use for a --filters-file. To learn more, see the documentation.
  The table above also explains the aliasing that has been done internally to replace queue flags with their filter equivalents. The aliasing for these queue flags is present purely for backwards compatibility purposes, but they are not going to emit deprecation warnings, and will not be removed before the Terragrunt 1.0 release.
  You are heavily encouraged to adopt the new --filter flag for your infrastructure targeting needs as soon as feasible in your workflows. It will offer a significantly more flexible and powerful experience.
  To learn more see the Filters feature documentation.

What's Changed

• fix: Using testing/synctest to make TestWriteUnitLevelSummary more reliable by @yhakbar in #5253
• chore: Cleaning up test symlinks resolution by @yhakbar in #5251
• fix: Fixing report run duplication error by @yhakbar in #5252
• fix: improved log error messages by @denis256 in #5256
• chore: Dropping ListContains and ListEquals and using standard library instead by @yhakbar in #5221
• chore: Adding debug log for assume already applied by @yhakbar in #5198
• Adding ambassador by @karlcarstensen in #5261
• Adding ambassador by @karlcarstensen in #5259
• Adding announcement banner by @karlcarstensen in #5260
• chore: Removing latest Terraform OSS workflows by @yhakbar in #5262
• chore: Backporting queue flags into filter flags by @yhakbar in #5241
• docs: Documenting backport of queue flags into filter flags by @yhakbar in #5263

Full Changelog: v0.96.1...v0.97.0-rc2025121901

Original source Report a problem

Experiments Updated

• The --filter-affected flag has more robust determination of the default branch in a Git repository.

• The --filter-affected flag will now use Git plumbing to interrogate the default branch as considered by the remote repository before falling back to interrogating local configurations for determination of a default branch (remember that you must use the filter-flag experiment to try this out).

  • This is checked first:

    $ git rev-parse --abbrev-ref origin/HEAD
    

  • Followed by this:

    $ git ls-remote --symref origin HEAD
    

  • Followed with this:

    $ git config init.defaultBranch
    

  • If none of the above succeed, the default branch is assumed to be main.

• Git-based filter expressions now warn users when using local state

  • Usage of --filter Git-based expressions in combination with local state will now emit a warning, recommending usage of remote states (remember that you must use the filter-flag experiment to try this out).

    Example:

    $ terragrunt run --all --filter '[HEAD~1...HEAD]' -- plan
    

    09:30:38.017 WARN One or more units discovered using Git-based filter expressions (e.g. [HEAD~1...HEAD]) do not have a remote_state configuration. This may result in unexpected outcomes, such as outputs for dependencies returning empty. It is strongly recommended to use remote state when working with Git-based filter expressions.
    See the warning at the bottom of Git-based expressions documentation for more information.
    

• OpenTelemetry traces added for filter evaluation

  • Filter evaluation now emits OpenTelemetry spans and metrics, including filter resolution details, evaluation duration, and filtering scope. This helps teams analyze performance and pinpoint bottlenecks in filtering with large Terragrunt repositories.

🐛 Bug Fixes

• Path-based filters targeting external paths fixed

  • A bug in the parsing of path-based filter expressions in the --filter flag of the filter-flag experiment prevented parsing of path-based filters for external paths (e.g. --filter ../external-dir). This bug has been fixed.

• HTTPS Git CAS URLs fixed

  • A bug in the parsing of source URLs with forced usage of the Git protocol (e.g. git::https://github.com/acme/catalog) prevented using the cas experiment with HTTPS Git URLs with forced usage of the Git protocol. This bug has been fixed.

• Regression of support for root terragrunt.hcl fixed

  • A bug in the processing of --queue-exclude-dir resulted in prefix based matching of non-glob expressions in --queue-exclude-dir values. This broke backwards compatibility for users with a root terragrunt.hcl file instead of a differently named file for the root include (e.g. root.hcl). This bug has been fixed.

  • Note that you are still advised to migrate away from using a root terragrunt.hcl as soon as possible for your team. We will maintain backwards compatibility until at least 2.0, however.

What's Changed

• feat: add opentelemetry integration in filter flag by @denis256 in #5247

• feat: Adding warnings for local state usage with Git-based expressions by @yhakbar in #5245

• feat: Use more robust default branch detection in Git-based expressions by @yhakbar in #5243

• fix: Fixing parsing of external filters by @yhakbar in #5238

• fix: Fixing HTTPS CAS URLs by @yhakbar in #5240

• fix: Fixing warnings for how to reproduce tofu runs by @yhakbar in #5246

• fix: Fixing regression with support for include of root terragrunt.hcl by @yhakbar in #5249

• chore: Verify --queue-include-external isn't necessary when using the --filter flag by @yhakbar in #5216

• chore: Verify --filter results in minimal parsing by @yhakbar in #5229

• chore: Dropping util.JoinPath by @yhakbar in #5219

• docs: Cleaning up some docs by @yhakbar in #5239

Full Changelog: v0.96.0...v0.96.1

Original source Report a problem

🛠️ Breaking Changes

The --no-destroy-dependencies-check flag has been deprecated

The default behavior of Terragrunt with respect to checking dependents during destroys has been inverted. As a consequence the --no-destroy-dependencies-check has been deprecated, and a new --destroy-dependencies-check flag has been introduced.

Previously, Terragrunt would automatically parse all configurations that might depend on a unit being destroyed to warn users that the destroyed configuration might orphan other units that depend on it. This was frequently undesirable behavior due to the fact that it introduced additional unnecessary work (parsing all HCL configurations unnecessarily), and could introduce errors if users had unrelated invalid HCL configurations.

Terragrunt now requires that users opt-in to this behavior via the new --destroy-dependencies-check flag, which enables the destroy check, and will not perform the destroy check by default.

terragrunt run --destroy-dependencies-check -- destroy

To learn more, see the no-destroy-dependencies-check strict control.

The --disable-command-validation flag has been deprecated

Terragrunt no longer performs command name validation when passing commands to OpenTofu/Terraform from Terragrunt when using the run command. This makes the --disable-command-validation flag unnecessary, as the lack of validation is now the default behavior.

Previously, Terragrunt had no way to explicitly indicate that a command being used on the Terragrunt CLI was intended as a passthrough to the OpenTofu/Terraform CLI, so it was important that validation be done on the command being supplied on the Terragrunt CLI.

Since completion of the CLI Redesign, this has changed significantly. Users now have explicit shortcuts on the Terragrunt CLI for common OpenTofu/Terraform commands and an explicit interface for passing through OpenTofu/Terraform commands to the OpenTofu/Terraform CLIs using the run command. By removing this validation, Terragrunt will now automatically support new OpenTofu/Terraform commands in future versions of the tools and allow for greater flexibility in IaC Engines, as novel commands can be introduced.

To learn more, see the disable-command-validation strict control.

The --experimental-engine flag now enables the iac-engine experiment

The experimental IaC Engine feature was introduced in Terragrunt prior to the introduction of the experiment system. As such, it wasn’t enabled when users enabled experiment mode, and didn’t have a dedicated section in the experiments docs.

The --experimental-engine flag is now an alias for explicitly enabling the iac-engine experiment, and using IaC Engines will be allowed when using Terragrunt in experiment mode. This increases consistency with how experimental features are managed in Terragrunt, and reduces the surface area users have to be aware of in the Terragrunt CLI.

terragrunt run --experiment=iac-engine

Note that you can explicitly disable usage of engines now with the --no-engine flag, even when the experiment is active.

terragrunt run --experiment=iac-engine --no-engine

To learn more, see the iac-engine experiment.

The --dependency-fetch-output-from-state flag now enables the dependency-fetch-output-from-state experiment

The experimental —dependency-fetch-output-from-state flag was introduced in Terragrunt prior to the introduction of the experiment system. As such, it wasn’t enabled when users enabled experiment mode, and didn’t have a dedicated section in the experiments docs.

The --dependency-fetch-output-from-state flag is now an alias for explicitly enabling the dependency-fetch-output-from-state experiment, and Terragrunt will automatically attempt to fetch outputs from backend state when in experiment mode. This increases consistency with how experimental features are managed in Terragrunt, and reduces the surface area users have to be aware of in the Terragrunt CLI.

terragrunt run --experiment=dependency-fetch-output-from-state

Note that you can explicitly disable fetching output from state with the --no-dependency-fetch-output-from-state flag, even when the experiment is active.

terragrunt run --experiment=dependency Fetch-output-from-state --no-dependency-fetch-output-from-state

To learn more, see the dependency-fetch-output-from-state experiment.

🧪 Experiments Updated

The filter-flag experiment now supports the --filters-file flag

The --filters-file flag has been introduced to allow for the application of multiple filters as defined in a newline-delimited text file, similar to the existing --excludes-file flag (remember that you must use the filter-flag experiment to try this).

# custom-filters.txt
!./unstable/**
$ terragrunt find --filters-file custom-filters.txt
# No results in `./unstable` discovered.

When the filter-flag experiment is active, Terragrunt will automatically parse and apply filters found in a .terragrunt-filters file, similar to how it automatically parses and applies excludes found in a .terragrunt-excludes file.

# .terragrunt-filters
!./unstable/**

Note that it only does this by default when the experiment is active.

terragrunt find

Still no results in ./unstable discovered.

To explicitly disable usage of filter files (including the automatic .terragrunt-filters file), use the --no-filters-file flag.

# .terragrunt-filters
!./unstable/**

Note that it only does this by default when the experiment is active.

terragrunt find --no-filters-file

This will allow results in ./unstable to be discovered.

Unlike the --excludes-file, usage of the --filters-file flag also allows for always filtering for particular configurations.

# .terragrunt-filters
./always-include/**

To learn more, see the filters file documentation.

🐛 Bug Fixes

Unnecessary .terragrunt-cache directory no longer generated in run --all runs

Fixed a regression where run --all would create empty .terragrunt-cache directories in the current working directory, even when not needed.

What's Changed

• feat: Adding --destroy-dependencies-check by @yhakbar in #5204
• feat: Adding --filters-file flag by @yhakbar in #5111
• feat: Removing support for --disable-command-validation by @yhakbar in #5189
• feat: Add iac-engine experiment by @yhakbar in #5203
• feat: Add dependency-fetch-output-from-state experiment by @yhakbar in #5201
• fix: Remove unnecessary .terragrunt-cache dir at the stack level by @yhakbar in #5231
• docs: Documenting --filters-file flag by @yhakbar in #5112
• docs: Update terminology from 'module' to 'unit' in scaffold.md by @josh-padnick in #5121
• docs: Fix Runner Pool description in terminology section by @maddawik in #5236
• build(deps): bump actions/upload-artifact from 5 to 6 by @dependabot[bot] in #5233
• build(deps): bump actions/download-artifact from 6 to 7 by @dependabot[bot] in #5235
• build(deps): bump actions/cache from 4 to 5 by @dependabot[bot] in #5234

New Contributors

• @maddawik made their first contribution in #5236

Full Changelog: v0.95.1...v0.96.0

Original source Report a problem