docs: Update terminology to use the new root.hcl pattern

[hashlash]

Description

Update unit terminology to use the new root.hcl pattern.

Quoting the new pattern docs:

terragrunt/docs-starlight/src/content/docs/07-migrate/01-migrating-from-root-terragrunt-hcl.md

Lines 122 to 124 in 25150a6

	Naming the root file `root.hcl` is the recommended pattern, but it is not a requirement.
	Our documentation and examples are updated to reference this new pattern, and following this pattern will allow users to pattern match when writing their own configurations.

TODOs (irrelevant I think?)

TODOs

Read the Gruntwork contribution guidelines.

• 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)

Updated docs about root config file in Unit terminology section

Migration Guide

Summary by CodeRabbit

• Documentation
  • Updated terminology and naming conventions for root configuration files in getting started guides, clarifying how root configuration is structured and named.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

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

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation update replacing references to "root terragrunt.hcl" with "root.hcl" in the terminology guide, clarifying the naming convention for root configuration files and their relationship to child directory structures.

Changes

Cohort / File(s)	Summary
Documentation: Root configuration naming docs-starlight/src/content/docs/01-getting-started/04-terminology.md	Updated references from "root terragrunt.hcl" to "root.hcl" throughout; clarified that root.hcl is not a unit and child directories contain terragrunt.hcl files.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• terragrunt#4058 — Performs the same documentation rename from "terragrunt.hcl" to "root.hcl" in documentation files.
• terragrunt#3912 — Modifies the same terminology documentation file with a hyperlink fix.

Suggested reviewers

• denis256
• yhakbar
• levkohimins

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the change purpose but is missing required sections including linked issue, comprehensive description, and proper release notes documentation.	Add the issue reference (Fixes #XXXX), a more detailed description of the change, and properly format the release notes outside the collapsed details section.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: updating terminology documentation to use the new root.hcl pattern.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

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

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 25150a6 and 0e550f3.

📒 Files selected for processing (1)

• docs-starlight/src/content/docs/01-getting-started/04-terminology.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

docs-starlight/**/*.md*

⚙️ CodeRabbit configuration file

docs-starlight/**/*.md*: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration underway from the Jekyll based documentation in docs to the Starlight + Astro based documentation in docs-starlight. Make sure that the docs-starlight documentation is accurate and up-to-date with the docs documentation, and that any difference between them results in an improvement in the docs-starlight documentation.

Referenced Documentation Contents

docs-starlight/src/content/docs/01-getting-started/04-terminology.md:
Guidelines relevant to the root.hcl pattern:

• Emphasize that the common pattern places a root.hcl at repository root and child directories contain terragrunt.hcl; root.hcl is not a unit.
• Refer to root.hcl as the root configuration file (can be named root.hcl or use root.hcl as the conventional name), replacing references to root terragrunt.hcl.
• Ensure sections consistently describe root.hcl as the shared configuration container and clarify that child directories with terragrunt.hcl remain units.
• Note that units and the root file naming are configurable via --config, but the conventional pattern uses root.hcl.
• Update any terminology entries to reflect that root configuration naming is flexible, with root.hcl as the prevalent pattern.

Files:

• docs-starlight/src/content/docs/01-getting-started/04-terminology.md

🧠 Learnings (3)

📓 Common learnings

Learnt from: yhakbar
Repo: gruntwork-io/terragrunt PR: 3868
File: docs-starlight/patches/@astrojs%[email protected]:33-33
Timestamp: 2025-02-10T23:20:04.295Z
Learning: In Terragrunt projects, all `.hcl` files can be assumed to be Terragrunt configurations by default, with specific exceptions like `.terraform.lock.hcl` that need explicit handling.

Learnt from: jkarkoszka
Repo: gruntwork-io/terragrunt PR: 5116
File: test/integration_test.go:2785-2795
Timestamp: 2025-11-18T09:54:06.008Z
Learning: In Terragrunt, `read_terragrunt_config_with_cache` intentionally has different semantics than `read_terragrunt_config`: it caches the first parse result (including context like `original_terragrunt_dir`) and returns that cached value on subsequent calls to the same file, even if the calling context has changed. This is a performance optimization that trades context accuracy for speed. Tests showing different assertions between cached and non-cached variants for context-dependent values like `original_terragrunt_dir` are expected and correct.

📚 Learning: 2025-02-10T23:20:04.295Z

Learnt from: yhakbar
Repo: gruntwork-io/terragrunt PR: 3868
File: docs-starlight/patches/@astrojs%[email protected]:33-33
Timestamp: 2025-02-10T23:20:04.295Z
Learning: In Terragrunt projects, all `.hcl` files can be assumed to be Terragrunt configurations by default, with specific exceptions like `.terraform.lock.hcl` that need explicit handling.

Applied to files:

• docs-starlight/src/content/docs/01-getting-started/04-terminology.md

📚 Learning: 2025-11-18T09:54:06.008Z

Learnt from: jkarkoszka
Repo: gruntwork-io/terragrunt PR: 5116
File: test/integration_test.go:2785-2795
Timestamp: 2025-11-18T09:54:06.008Z
Learning: In Terragrunt, `read_terragrunt_config_with_cache` intentionally has different semantics than `read_terragrunt_config`: it caches the first parse result (including context like `original_terragrunt_dir`) and returns that cached value on subsequent calls to the same file, even if the calling context has changed. This is a performance optimization that trades context accuracy for speed. Tests showing different assertions between cached and non-cached variants for context-dependent values like `original_terragrunt_dir` are expected and correct.

Applied to files:

• docs-starlight/src/content/docs/01-getting-started/04-terminology.md

🔇 Additional comments (3)

docs-starlight/src/content/docs/01-getting-started/04-terminology.md (3)

49-50: Root configuration pattern description is clear and accurate.

The updated paragraph effectively describes the common root.hcl pattern by:

• Explicitly stating root.hcl is not a unit
• Clarifying that child directories with terragrunt.hcl are the actual units
• Describing root.hcl as the shared configuration container

This aligns well with the guidelines and maintains clarity.

---

51-52: Configuration flexibility note follows guidelines well.

The note appropriately emphasizes that root.hcl is the conventional pattern while acknowledging the --config flexibility and encouraging industry standard adherence. The phrasing is clear and avoids overstating the requirement.

---

97-97: Verify consistency of terminology on line 97.

Line 97 still references "root terragrunt.hcl file" when describing state path conventions. This appears inconsistent with the updated root.hcl terminology introduced in the Unit section (lines 49-52). For consistency, consider clarifying this as "root configuration file" or "root directory" to align with the new pattern documentation.

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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.}