docs: Documenting support for --filter in the run command

[yhakbar]

Description

Documents support for the --filter flag in the run command.

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 docs for --filter support in run.

Migration Guide

Summary by CodeRabbit

• Documentation
  • Updated documentation to reflect --filter flag support in the run command (now available in find, list, and run).
  • Added comprehensive "Filtering Units" section with basic and advanced filtering examples for the run command.
  • Marked filter-flag integration with run command as completed.
  • Updated command support tables and flag availability across documentation.

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
terragrunt-docs	Ready	Preview	Comment	Oct 24, 2025 1:04pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates across multiple files to reflect that the --filter flag is now available in the run command alongside find and list. Marks the run command integration as completed in the experiments tracking document and adds comprehensive filter usage documentation to the run command reference.

Changes

Cohort / File(s)	Summary
Filter flag documentation updates docs-starlight/src/content/docs/03-features/18-filter.mdx, docs-starlight/src/data/flags/filter.mdx	Updated filter flag availability to include run command in supported commands list
Run command filter documentation docs-starlight/src/data/commands/run.mdx	Added comprehensive "Filtering Units" section with filter flag usage, syntax examples (glob, name, type), negation, and advanced filtering patterns
Experiments status tracking docs-starlight/src/content/docs/04-reference/04-experiments.md	Marked run command integration as completed; expanded future work items to include --filters-file, --filter-allow-destroy, --filter-affected, comprehensive testing, and legacy flag deprecation

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• gruntwork-io/terragrunt#4981: Implements --filter support in the run command (flags, builder integration, and tests) that these docs are documenting.
• gruntwork-io/terragrunt#4973: Modifies the same filter-related documentation files to reflect filter flag additions.
• gruntwork-io/terragrunt#4996: Updates filter documentation to clarify filter usage and examples in the features guide.

Suggested reviewers

• denis256
• josh-padnick

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "docs: Documenting support for --filter in the run command" directly and clearly summarizes the main objective of the changeset. All four documentation files updated in this PR are focused on documenting the --filter flag's support in the run command. The title is concise, specific, and uses clear language without vague terms or unnecessary noise. A reviewer scanning the commit history would immediately understand that this PR adds documentation for --filter support in the run command.
Description Check	✅ Passed	The PR description follows the required template structure with all key sections present: a Description section explaining the change, a complete TODOs checklist with appropriate items checked or unchecked, a Release Notes (draft) section with a concise one-line summary, and a Migration Guide section (appropriately left blank since this is a documentation-only change with no backward incompatible changes). The description is brief but sufficient for a documentation update, and all required checklist items are properly addressed by the author.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/documenting-support-for-filter-in-run-command

---

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

The base branch was changed.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs-starlight/src/data/commands/run.mdx (1)

112-112: Path format should be consistent with feature documentation.

Line 112 shows 'prod/**' without the leading ./ prefix, but the filter feature documentation in docs-starlight/src/content/docs/03-features/18-filter.mdx consistently uses './envs/prod/**' for relative paths (see lines 108-109). For consistency across documentation, update this example to use the ./ prefix:

- terragrunt run --all --filter 'prod/**' -- plan
+ terragrunt run --all --filter './prod/**' -- plan

📜 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 7762a56 and 1a43f7d.

📒 Files selected for processing (4)

• docs-starlight/src/content/docs/03-features/18-filter.mdx (2 hunks)
• docs-starlight/src/content/docs/04-reference/04-experiments.md (2 hunks)
• docs-starlight/src/data/commands/run.mdx (2 hunks)
• docs-starlight/src/data/flags/filter.mdx (2 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/commands/run.mdx
• docs-starlight/src/content/docs/03-features/18-filter.mdx
• docs-starlight/src/content/docs/04-reference/04-experiments.md
• docs-starlight/src/data/flags/filter.mdx

⏰ 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). (3)

• GitHub Check: license_check / License Check
• GitHub Check: Pull Request has non-contributor approval
• GitHub Check: build-and-test

🔇 Additional comments (4)

docs-starlight/src/content/docs/03-features/18-filter.mdx (1)

23-23: Updates are consistent with feature completion.

The changes correctly reflect that --filter is now available in the run command alongside find and list. The updates maintain consistency with the status changes in other files.

Also applies to: 320-320

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

20-20: Updates accurately reflect filter support in run command.

The documentation correctly indicates that --filter is now available in the run command, and the usage example appropriately shows --all --filter together, which is the correct pattern for filtering across multiple units.

Also applies to: 116-116

docs-starlight/src/data/commands/run.mdx (1)

94-143: New filtering section is well-structured and comprehensive.

The "Filtering Units" section provides clear progression from basic to advanced examples, the experimental feature notice is properly formatted, and the "Learn More" tip appropriately directs users to comprehensive filter documentation. The examples correctly show that --all is used together with --filter in the run command context.

docs-starlight/src/content/docs/04-reference/04-experiments.md (1)

131-131: Experiment status correctly reflects run command integration completion.

The updates to the filter-flag experiment status accurately reflect that the run command integration is now complete and available (marked with ✅ and [x]). The expanded "Not Yet Implemented" section appropriately outlines the remaining work items for stabilizing the filter-flag feature.

Also applies to: 166-166