feature: Add deep_merge HCL function for deep map/object input merging

[EvansM4]

Implements #4820

Add a new Terragrunt HCL function, deep_merge(...), to support deep merging of map/object inputs (including decoded JSON objects) this works similar to the existing merge(...) function behavior but provides deep merging.

Changes included:

• Added deep_merge function to the Terragrunt eval context.
• Implemented deep merge semantics for maps/objects:
  • later arguments override earlier ones on key conflicts
  • nested maps/objects merge recursively
  • lists are appended
• Added validation/error handling for invalid argument types (non map/object).
• Added tests for:
  • HCL object deep merge
  • JSON-decoded object deep merge
  • mixed HCL + JSON deep merge
  • invalid argument type behavior
• Updated function docs with usage example for merging multiple JSON files.

TODOs

Read the Gruntwork contribution guidelines (https://gruntwork.notion.site/Gruntwork-Coding-Methodology-02fdcd6e4b004e818553684760bf691e).

• I authored this code entirely myself
• I am submitting code based on open source software (e.g. MIT, MPL-2.0, Apache)]
• I am adding or upgrading a dependency or adapted code and confirm it has a compatible open source license
• Update the docs.
• Run the relevant tests successfully, including pre-commit checks.
• Include release notes. If this PR is backward incompatible, include a migration guide.

Release Notes (draft)

Added deep_merge(...) Terragrunt HCL function for deep map/object merging

Migration Guide

No migration required. This is additive and does not change existing merge(...) behaviour.

Summary by CodeRabbit

• New Features

  • Added deep_merge to recursively merge multiple maps/objects: later inputs override earlier ones; nested maps merge and lists are appended.

• Documentation

  • Added usage docs and a practical example demonstrating composing nested configurations (added in reference pages).

• Tests

  • Added tests for nested merge behavior and for invalid-input error handling.

[vercel]

@EvansM4 is attempting to deploy a commit to the Gruntwork Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 97e37a1a-ee82-4416-b2d6-d332ca3b8cfc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new Terragrunt HCL built-in function deep_merge that recursively merges multiple maps/objects (later args override earlier ones), appends lists, registers it in the eval context, adds unit tests for normal and invalid usage, and updates documentation with two identical deep_merge blocks.

Changes

Cohort / File(s)	Summary
Documentation docs-starlight/src/content/docs/04-reference/01-hcl/04-functions.mdx	Inserted two identical deep_merge documentation blocks describing semantics and providing a usage example for composing nested configuration.
Function Implementation pkg/config/cty_helpers.go	Added deepMergeMapValuesAsFuncImpl() returning a cty.Function that accepts dynamic args, skips nulls, validates map/object types, and progressively deep-merges maps (recursive for nested maps; appends lists).
Function Registration pkg/config/config_helpers.go	Added FuncNameDeepMerge = "deep_merge" constant and wired deep_merge into the Terragrunt HCL eval context mapping to the new function.
Tests pkg/config/config_helpers_test.go	Added TestTerragruntDeepMergeFunction (multiple merge cases) and TestTerragruntDeepMergeFunctionInvalidType (invalid-type error handling).

Sequence Diagram(s)

sequenceDiagram
    participant Parser as HCL Parser
    participant Eval as Eval Context
    participant Func as deep_merge Function
    participant Merge as Merge Logic
    participant Result as Cty Value

    Parser->>Eval: Parse HCL invoking deep_merge(...)
    Eval->>Func: Call deepMergeMapValuesAsFuncImpl with args
    Func->>Func: Iterate args, skip nulls, validate map/object types
    alt Invalid type detected
        Func->>Result: Return InvalidParameterTypeError
    else All args valid
        Func->>Merge: Provide validated maps/values
        Merge->>Merge: Recursively merge maps (later overrides)
        Merge->>Merge: Append list values
        Merge->>Result: Return merged cty.Value
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and concisely describes the main feature: adding a deep_merge HCL function for deep map/object merging, which aligns with the core purpose of all changes.
Description check	✅ Passed	The description includes all critical template sections: issue reference (#4820), detailed feature explanation, implementation details, test coverage, and release notes. Minor checklist items remain, but core content is complete.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[EvansM4]

@yhakbar would you mind reviewing this when you get a chance, I do realise that adding new features prior to the 1.0 release would likely not happen.

[yhakbar]

Hey @EvansM4 ,

I don't see anything seriously wrong with this function, but we are in a feature freeze pending release of 1.0. I'm going to move this PR in-draft to signal that. I imagine we'll also need to rebase the PR once we've released 1.0, as main will have moved quite a bit.

Thanks for opening this! Looking forward to reviewing it again after 1.0. Please mark as ready for review and tag maintainers until it's reviewed after 1.0.