fix: Adding docs back for -detailed-exitcode, etc.

[yhakbar]

Description

Fixes #000.

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)

Added / Removed / Updated [X].

Migration Guide

Summary by CodeRabbit

• Documentation
  • Added caution about using run --all with unapplied dependencies, recommending mock outputs in dependency blocks to resolve outputs before deployment.
  • Noted that run --all with apply or destroy implicitly adds -auto-approve to OpenTofu/Terraform due to shared stdin limitations.
  • Documented aggregate exit code behavior with -detailed-exitcode when using run --all: any unit returns 1 ⇒ overall 1; else any 2 ⇒ overall 2; otherwise 0.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added three informational Asides to docs-starlight/src/data/flags/all.mdx documenting behavior of run --all with dependencies, implicit -auto-approve when combined with apply/destroy, and aggregate exit code semantics with -detailed-exitcode. No code or API changes.

Changes

Cohort / File(s)	Summary
Docs: Flags page updates docs-starlight/src/data/flags/all.mdx	Added Asides: caution on using run --all with unapplied dependencies (suggest mock outputs); note that apply/destroy with run --all implies -auto-approve; note documenting aggregate exit code when using -detailed-exitcode with run --all.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• fix: Adding docs for --all and --graph #4036 — Also updates docs for the --all flag, covering dependency handling and implicit -auto-approve.

Suggested reviewers

• denis256
• wakeful

Pre-merge checks (2 passed, 1 warning)

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The PR description is largely the unedited template: it contains "Fixes #000." and placeholder comments instead of an actual summary of the changes, the Release Notes section is a placeholder, the Migration Guide is empty, and the TODO checklist is marked complete but lacks supporting detail; therefore required descriptive information is missing or incomplete.	Please replace the placeholders with a clear description of the changes (e.g., the three new Aside blocks added to docs-starlight/src/data/flags/all.mdx), update "Fixes #000" with the real issue number or remove it, provide a one-line Release Notes entry, add a Migration Guide if there are breaking changes, and ensure the TODO checklist accurately reflects completed verification and test results.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "fix: Adding docs back for -detailed-exitcode, etc." directly references restoring documentation for -detailed-exitcode which is present in the changeset and generally reflects that this PR is a docs restore, but the trailing "etc." is informal and makes the title less precise.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

• Failed to retrieve linked issues from the platform client.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/fixing-detailed-exitcode-docs

---

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
terragrunt-docs	Ready	Preview	Comment	Sep 12, 2025 2:21pm

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs-starlight/src/data/flags/all.mdx (2)

47-51: Be explicit about implicit -auto-approve and add a safety tip.

“Silently” can read as surprising behavior; “implicitly” is more neutral. Add a short best-practice note.

 <Aside type="note">
-Using `run --all` with `apply` or `destroy` silently adds the `-auto-approve` flag to the command line
-arguments passed to OpenTofu/Terraform due to issues with shared `stdin` making individual approvals impossible.
-
+When you use `run --all` with `apply` or `destroy`, Terragrunt implicitly adds `-auto-approve` to the
+OpenTofu/Terraform invocation. Because multiple units share a single `stdin` stream, interactive approvals
+aren’t possible.
+
+Best practice: review plans first (for example, `run --all plan -detailed-exitcode`) and narrow the scope
+with [`--include-dir`](/docs/reference/cli/commands/run#include-dir) and/or
+[`--exclude-dir`](/docs/reference/cli/commands/run#exclude-dir).
 </Aside>

---

53-62: Clarify that -detailed-exitcode is plan-specific and improve wording (“exits with code”).

This aligns reader expectations and matches Terraform/OpenTofu semantics where 2 = “changes present,” not an error.

 <Aside type="note">
-Using the OpenTofu/Terraform [-detailed-exitcode](https://opentofu.org/docs/cli/commands/plan/#other-options)
-flag with the `run --all` command results in an aggregate exit code being returned, rather than the exit code of any particular unit.
+When using the OpenTofu/Terraform [-detailed-exitcode](https://opentofu.org/docs/cli/commands/plan/#other-options)
+flag with `run --all` (typically with the `plan` command), Terragrunt returns an aggregate exit code rather than
+the exit code of any particular unit. Note: exit code 2 means “plan succeeded with changes.”
 
-The algorithm for determining the aggregate exit code is as follows:
+The algorithm for determining the aggregate exit code is as follows:
 
-- If any unit throws a 1, Terragrunt will throw a 1.
-- If any unit throws a 2, but nothing throws a 1, Terragrunt will throw a 2.
-- If nothing throws a non-zero, Terragrunt will throw a 0.
+- If any unit exits with code 1, Terragrunt exits with code 1.
+- Else if any unit exits with code 2, Terragrunt exits with code 2.
+- Else Terragrunt exits with code 0.
 </Aside>

If desired, we can cross-check that this matches current behavior in error aggregation. Would you like a follow-up PR linking to a short “Exit codes” reference page and the MultiError rationale?

📜 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 985de73 and 4e57d6e.

📒 Files selected for processing (1)

• docs-starlight/src/data/flags/all.mdx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

docs-starlight/**/*.md*

⚙️ CodeRabbit configuration file

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.

Files:

• docs-starlight/src/data/flags/all.mdx

🧠 Learnings (1)

📓 Common learnings

Learnt from: jorhett
PR: gruntwork-io/terragrunt#1234
File: errors/multierror.go:35-39
Timestamp: 2025-09-10T04:41:35.652Z
Learning: In Terragrunt's MultiError.Error() method, checking for the exact string "exit status 2" and returning it directly is not a brittle hack but a semantic fix. Terraform's --detailed-exitcode flag uses exit code 2 to mean "plan succeeded with changes" (not an error), so when multiple modules return this status, it should not be wrapped in "Hit multiple errors:" formatting as that misrepresents successful operations as errors.

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)

• GitHub Check: Pull Request has non-contributor approval
• GitHub Check: build_no_proxy / Build (linux/amd64)
• GitHub Check: build_no_proxy / Build (windows/386)
• GitHub Check: build_no_proxy / Build (windows/amd64)
• GitHub Check: build_no_proxy / Build (linux/arm64)
• GitHub Check: base_tests / Test (macos)
• GitHub Check: base_tests / Test (ubuntu)
• GitHub Check: Pull Request has non-contributor approval

🔇 Additional comments (1)

docs-starlight/src/data/flags/all.mdx (1)

37-45: Tighten wording and link to the dependency docs (mock_outputs attribute)

Clarify the ambiguous "it" and point directly to the dependency block docs — there’s no #dependency-mock_outputs anchor. Suggested replacement:

<Aside type="caution">
Use `run --all` with care if you have unapplied dependencies.

If your stack defines inter-unit dependencies via `dependency` blocks and you haven’t deployed them yet,
commands like `run --all plan` can fail because Terragrunt cannot resolve dependency outputs until their
source units have been applied.

To plan successfully before the first apply, use the `mock_outputs` attribute in `dependency` blocks.
See [dependency block docs](/docs/reference/hcl/blocks/#dependency) for details.
</Aside>

Likely an incorrect or invalid review comment.