Scope subcommand usage help

[MikeMcQuaid]

• Avoid overwhelming UsageError output for commands with subcommands.
• Keep root command help to subcommand summaries and root flags.
• Reuse parser metadata so matched subcommands show valid flags only.

---

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
• Have you written new tests (excluding integration tests) for your changes? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) with your changes locally?

---

• AI was used to generate or assist with generating this PR. Please specify below how you used AI to help you, and what steps you have taken to manually verify the changes. Non-maintainers may only have one AI-assisted/generated PR open at a time.

OpenAI Codex 5.5 xhigh with local review and testing.

---

[Copilot]

Pull request overview

This PR scopes help, manpage, and shell completion output for commands with subcommands so root help shows root options/subcommand summaries while matched subcommands show their own valid flags.

Changes:

• Adds subcommand-aware option metadata and help generation in the CLI parser.
• Updates completions/manpage generation to use root vs subcommand-specific options.
• Refines bundle and services option descriptions and adds regression tests.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Library/Homebrew/cli/parser.rb	Adds root/subcommand option summary tracking and scoped help rendering.
Library/Homebrew/help.rb	Passes usage-error context into parser help generation.
Library/Homebrew/commands.rb	Returns root-only options when no subcommand is requested.
Library/Homebrew/completions.rb	Generates top-level completions from root options only.
Library/Homebrew/manpages.rb	Emits root options and subcommand options separately.
Library/Homebrew/bundle/subcommand/*	Updates bundle option descriptions to be subcommand-specific.
Library/Homebrew/bundle/extensions/*	Removes shared extension switch description helper.
Library/Homebrew/services/subcommand/*	Updates services --all descriptions per operation.
Library/Homebrew/test/*	Adds/updates parser, manpage, completion, bundle, and services coverage.
completions/bash/brew	Regenerates bash completion output.
completions/fish/brew.fish	Regenerates fish completion output.
completions/zsh/_brew	Regenerates zsh completion output.
docs/Manpage.md	Regenerates Markdown manpage documentation.
manpages/brew.1	Regenerates roff manpage documentation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.