fix: Closing gap from CLI Redesign #3862
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Caution Review failedThe pull request is closed. WalkthroughThis pull request updates the Terragrunt documentation by renaming various command-line flags and parameters to remove redundant prefixes and simplify terminology. The changes span multiple documentation sections including Getting Started, Features, Reference, and Troubleshooting. Updated examples and references now consistently use the simplified names without altering the underlying functionality. Changes
Suggested labels
Suggested reviewers
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (3)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx (1)
133-133: Grammar Suggestion for Clarity
Static analysis suggests that the phrase “If you would prefer that Terragrunt output look more like the output from tofu/terraform…” could be improved by removing the word “would.” For example, consider:- If you would prefer that Terragrunt output look more like the output from tofu/terraform... + If you prefer Terragrunt output to look more like that from tofu/terraform...This small change can make the sentence more direct.
🧰 Tools
🪛 LanguageTool
[grammar] ~133-~133: Consider removing ‘would’. (Usually, ‘would’ does not occur in a conditional clause, unless to make a request or give a polite order.)
Context: ...xtra information helpful. If you would prefer that Terragrunt output look more like t...(CONDITIONAL_CLAUSE)
docs-starlight/src/content/docs/02-features/01-units.mdx (2)
156-156: Suggestion: Simplify Syntax DescriptionThe text uses “supports the exact same syntax” which comes off as a bit wordy. Consider simplifying it to “supports the same syntax” or “supports identical syntax” for improved clarity.
Here's a possible diff suggestion:
- ... so the `source` parameter supports the exact same syntax as the [module source]... + ... so the `source` parameter supports the same syntax as the [module source]...🧰 Tools
🪛 LanguageTool
[style] ~156-~156: ‘exact same’ might be wordy. Consider a shorter alternative.
Context: ... so thesourceparameter supports the exact same syntax as the [module source](https://o...(EN_WORDINESS_PREMIUM_EXACT_SAME)
201-201: Grammar Improvement: Comma for ClarityAdding a comma before “and” improves the readability of the sentence describing the
--source-updateflag.Suggested change:
- run Terragrunt with the `--source-update` flag and it’ll delete... + run Terragrunt with the `--source-update` flag, and it’ll delete...🧰 Tools
🪛 LanguageTool
[uncategorized] ~201-~201: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...rragrunt with the--source-updateflag and it’ll delete the tmp folder, download t...(COMMA_COMPOUND_SENTENCE)
docs-starlight/src/content/docs/02-features/02-stacks.mdx (2)
359-359: Grammar Note: Subject-Verb AgreementIn the note about
destroyruns, the phrase “once resources in a dependency is destroyed” should use “are destroyed” instead of “is destroyed” for proper grammar.Example correction:
- ... once resources in a dependency is destroyed, any commands run on dependent units may fail. + ... once resources in a dependency are destroyed, any commands run on dependent units may fail.🧰 Tools
🪛 LanguageTool
[grammar] ~359-~359: Did you mean “are”?
Context: ...ows that once resources in a dependency is destroyed, any commands run on dependen...(SUBJECTVERBAGREEMENT_2)
424-424: Suggestion: Minor Punctuation for ReadabilityThe line is very clear. For extra readability, consider adding a comma after “at any given time” as in “...at any given time, use the
--parallelism [number]flag.”
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx(4 hunks)docs-starlight/src/content/docs/01-getting-started/04-terminology.md(3 hunks)docs-starlight/src/content/docs/02-features/01-units.mdx(3 hunks)docs-starlight/src/content/docs/02-features/02-stacks.mdx(9 hunks)docs-starlight/src/content/docs/02-features/03-includes.mdx(2 hunks)docs-starlight/src/content/docs/02-features/08-aws-authentication.md(3 hunks)docs-starlight/src/content/docs/02-features/09-hooks.md(3 hunks)docs-starlight/src/content/docs/02-features/10-auto-init.md(1 hunks)docs-starlight/src/content/docs/02-features/12-provider-cache-server.md(6 hunks)docs-starlight/src/content/docs/04-reference/01-hcl/01-overview.mdx(2 hunks)docs-starlight/src/content/docs/04-reference/01-hcl/02-blocks.md(6 hunks)docs-starlight/src/content/docs/04-reference/01-hcl/03-attributes.mdx(5 hunks)docs-starlight/src/content/docs/04-reference/01-hcl/04-functions.mdx(4 hunks)docs-starlight/src/content/docs/05-troubleshooting/01-debugging.mdx(2 hunks)
✅ Files skipped from review due to trivial changes (2)
- docs-starlight/src/content/docs/02-features/10-auto-init.md
- docs-starlight/src/content/docs/04-reference/01-hcl/02-blocks.md
🧰 Additional context used
🪛 LanguageTool
docs-starlight/src/content/docs/05-troubleshooting/01-debugging.mdx
[typographical] ~19-~19: After the expression ‘for example’ a comma is usually used.
Context: ...te terragrunt-debug.tfvars.json. For example you could use it like this to debug an ...
(COMMA_FOR_EXAMPLE)
docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx
[grammar] ~133-~133: Consider removing ‘would’. (Usually, ‘would’ does not occur in a conditional clause, unless to make a request or give a polite order.)
Context: ...xtra information helpful. If you would prefer that Terragrunt output look more like t...
(CONDITIONAL_CLAUSE)
docs-starlight/src/content/docs/02-features/01-units.mdx
[style] ~156-~156: ‘exact same’ might be wordy. Consider a shorter alternative.
Context: ... so the source parameter supports the exact same syntax as the [module source](https://o...
(EN_WORDINESS_PREMIUM_EXACT_SAME)
[uncategorized] ~201-~201: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...rragrunt with the --source-update flag and it’ll delete the tmp folder, download t...
(COMMA_COMPOUND_SENTENCE)
docs-starlight/src/content/docs/02-features/02-stacks.mdx
[grammar] ~359-~359: Did you mean “are”?
Context: ...ows that once resources in a dependency is destroyed, any commands run on dependen...
(SUBJECTVERBAGREEMENT_2)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: unessential
- GitHub Check: build-and-test
🔇 Additional comments (39)
docs-starlight/src/content/docs/05-troubleshooting/01-debugging.mdx (3)
15-17: CLI Flag Update for Debugging:
Great job updating the text to reference the new--log-leveland--debug-inputsflags. This change aligns perfectly with the streamlined CLI design.
23-24: Updated Example Command:
The example command now readsterragrunt apply --log-level debug --debug-inputs, and it’s crystal clear. Nice work ensuring the live examples reflect the updated flag names.
97-98: Consistent Command Usage:
Repeating the updated command in a later shell code block reinforces the new syntax—well done on keeping things consistent throughout the document!docs-starlight/src/content/docs/04-reference/01-hcl/01-overview.mdx (2)
31-31: Simplified Config Flag:
Changing from--terragrunt-configto--configmakes the documentation cleaner and easier to follow. Please double-check that all related references elsewhere are updated too.
124-131: Enhanced HCL Formatting Options:
The revised section now clearly documents the new flags—--diff,--check,--hclfmt-exclude-dir, and--hclfmt-file—with concise examples. This extra clarity will surely help users format their files with ease.docs-starlight/src/content/docs/02-features/09-hooks.md (1)
275-287: Streamlined tflint Parameter:
Switching from the legacy--terragrunt-external-tflintto the simplified--external-tflintis a great move to simplify the hook configuration. The updated example is clear and directly supports the CLI redesign goals.docs-starlight/src/content/docs/02-features/12-provider-cache-server.md (7)
21-24: Enabling Experimental Provider Cache:
The updated text now informs users that the Provider Cache feature is experimental and must be enabled via the--provider-cacheflag. This note is clear and helpful for setting the right expectations.
35-37: Updated Default Cache Paths:
The revised default paths for Unix, Darwin, and Windows are now accurate. This clarity minimizes any potential confusion for users migrating from older versions where the cache location differed.
42-45: Custom Cache Directory Example:
The example demonstrating how to override the default cache directory with the--provider-cache-dirflag is concise and very practical.
55-61: Registry Names Override:
The documentation now explains how to override the default provider registries using the--provider-cache-registry-namesflag. The step-by-step example is easy to follow and very useful.
64-70: Environment Variable for Registry Names:
Including an example for settingTERRAGRUNT_PROVIDER_CACHE_REGISTRY_NAMESvia environment variables offers complete guidance for both CLI and environment-based configurations.
116-119: Provider Cache Server Configuration Flags:
Listing the new flags (--provider-cache-hostname,--provider-cache-port, and--provider-cache-token) alongside their default behavior makes this section much more informative. Great clarity here!
122-128: Configuring the Provider Cache Server:
The detailed shell command example for configuring the cache server—with host, port, and token settings—is both clear and instructive. It perfectly demonstrates how to set up the feature.docs-starlight/src/content/docs/04-reference/01-hcl/03-attributes.mdx (6)
115-117: Simplified Download Directory Flag:
Updating the flag to--download-dir(in place of the longer--terragrunt-download-dir) helps cut through the clutter. This update enhances readability and keeps the documentation aligned with the overall redesign.
180-183: Updated IAM Role Flag:
Switching to--iam-rolemaintains consistency with the new CLI standards while keeping the explanation clear. Users will appreciate the streamlined reference here.
201-203: Clear Role Duration Flag Update:
The update to the--iam-assume-role-durationflag is straightforward and improves clarity regarding the command precedence. Well done!
217-219: Session Name Flag Update:
The revised section now refers to--iam-assume-role-session-name, which is in line with the update on the IAM-related flags. This makes it much easier for users to set their STS session name correctly.
225-227: Web Identity Token Flag Update:
Switching to the simpler--iam-web-identity-tokenflag is a welcomed change. It’s consistent with the overall move towards clearer and shorter flag names in the documentation.
271-273: Simplified Terraform Binary Flag:
The change from--terragrunt-tfpathto--tf-pathis a fantastic simplification that makes the instructions much more digestible.docs-starlight/src/content/docs/02-features/08-aws-authentication.md (3)
43-47: Update on IAM Role Flag Naming
The updated text now uses the simplified--iam-roleflag (with an appropriate link), which is clear and consistent with the overall CLI redesign.
70-76: Clear Explanation of OIDC Role Assumption
The section explaining that you can combine the--iam-roleflag with the--iam-web-identity-tokenflag is concise and informative. This update makes the intended usage very clear.
109-113: Auth Provider Command Update
The revised description and example for using the--auth-provider-cmdflag are straightforward and easy to follow. This change maintains consistency across the documentation.docs-starlight/src/content/docs/02-features/03-includes.mdx (2)
446-449: Introduction of the Queue Flag
The updated explanation introducing the--queue-include-units-readingflag is very clear. It effectively communicates how Terragrunt will automatically add units that read the specified file to the run queue. Great job on this clarification!
468-474: Using the Working Directory for Scoped Rollouts
The examples leveraging the--working-dirflag to progressively rollout changes to environments (e.g., qa, stage, prod) are detailed and practical. This makes it easier for users to understand how to target subsets of units when applying changes.docs-starlight/src/content/docs/01-getting-started/04-terminology.md (1)
1-7: Consistent CLI Flag Terminology in Documentation
The document now consistently updates CLI flag references—changing--terragrunt-configto--config,--terragrunt-include-dirto--include-dir,--terragrunt-exclude-dirto--exclude-dir, and--terragrunt-parallelismto--parallelism. This uniformity across the documentation is excellent.docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx (2)
49-50: Helpful Note on Binary Selection
The note advising users that if they have both OpenTofu and Terraform installed they should consult the [tf‑path] documentation is very helpful. It provides the necessary context for choosing the right binary.
138-141: Updated Command Examples for Logging and Interactivity
The examples using the--log-format bareand--non-interactiveflags are now in line with the CLI redesign and clearly demonstrate the new reduced verbosity and non-interactive mode.docs-starlight/src/content/docs/04-reference/01-hcl/04-functions.mdx (3)
715-719: Usage of the--quietFlag with run_cmd()
The explanation for using the special--quietargument (passed as one of the first arguments torun_cmd()) to redact sensitive output is clear and practical. This update will help users protect secret data from appearing in terminal logs.
770-774: Introduction of the--global-cacheArgument
The new--global-cacheargument is explained well. It’s a neat addition that lets users modify caching behavior by ignoring the current directory if appropriate. The provided example clarifies its usage effectively.
897-901: Alignment of get_terragrunt_source_cli_flag() with Updated Flag Naming
Updatingget_terragrunt_source_cli_flag()to work with the new--sourceflag is consistent with the recent changes. The function’s description is now perfectly in line with the revised naming conventions.docs-starlight/src/content/docs/02-features/02-stacks.mdx (9)
387-387: Approval: Clear Local Source ExampleThe command example using
--source /source/modulesis clear and concise. It effectively demonstrates how to override the source from a remote URL.
396-396: Approval: Informative Step DescriptionThe explanation “3. Append the path to the
--sourceparameter to create the final local path for that unit” is clear and helpful for users understanding the local override flow.
411-411: Approval: Consistent Command ExampleThis command example using
--source /source/infrastructure-modulesis consistent with the documentation and clearly demonstrates the usage.
440-440: Approval: Command ClarityThe usage of
terragrunt run-all plan --out-dir /tmp/tfplanis straightforward and easy to follow.
458-458: Approval: Clear Apply Command ExampleThe command example
$ terragrunt run-all apply --out-dir /tmp/tfplanis well presented and matches the earlier pattern.
464-465: Approval: Consistent Destroy Operation ExamplesThe examples for destroy operations, using:
terragrunt run-all plan -destroy --out-dir /tmp/tfplan terragrunt run-all apply --out-dir /tmp/tfplanare consistent and illustrative. Just ensure that the use of
-destroyis aligned with Terragrunt’s recommended notation.
471-471: Approval: JSON Out Directory CommandThe command
terragrunt run-all plan --json-out-dir /tmp/jsonis clear and concise.
490-490: Approval: Combined Out Directory UsageThis combined command example:
terragrunt run-all plan --out-dir /tmp/all --json-out-dir /tmp/alleffectively illustrates saving both binary and JSON plans, and is easy to understand.
556-556: Approval: Detailed Run Queue ExplanationThe added explanation about using flags like
--include-dirand--exclude-dirto manage the run queue is very helpful and clear.
Description
Closes the gap a bit with the docs update here:
#3723
There's still some delta that needs to be addressed, but for now this brings the docs rewrite closer to what the docs will look like when the CLI Redesign PR is merged.
TODOs
Read the Gruntwork contribution guidelines.
Release Notes (draft)
Updated
docs-starlightto use flags from the CLI Redesign PR.Summary by CodeRabbit