Hide maintainer commands

[MikeMcQuaid]

• Keep maintainer-only commands out of generated manpages.
• Avoid top-level completion suggestions for those commands.
• Preserve option completion after maintainers type the command.

---

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

OpenAI Codex 5.5 xhigh with local review and testing.

---

[Copilot]

Pull request overview

This PR introduces a hide_from_man_page! marker for maintainer-only/internal commands and updates manpage/completion generation so these commands are omitted from generated manpages and from top-level shell command suggestions, while still retaining option/argument completion once the command is explicitly typed.

Changes:

• Mark specific dev-cmd commands as hidden from manpage generation (hide_from_man_page!) and regenerate docs/Manpage.md + manpages/brew.1 accordingly.
• Update completion generation to suppress top-level suggestions for hidden commands (zsh/fish, plus cached command lists) while preserving per-command completion functions.
• Add/extend tests to assert hidden commands are excluded from manpages and command suggestion lists, but still have argument completions.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
manpages/brew.1	Regenerated manpage output removing hidden maintainer command sections.
docs/Manpage.md	Regenerated Markdown manpage output removing hidden maintainer command sections.
Library/Homebrew/completions.rb	Adds hidden-command detection and omits hidden commands from zsh top-level suggestions; adjusts fish generation to drop command suggestions but keep arg completions.
Library/Homebrew/commands.rb	Removes hide filtering from internal command discovery; filters hidden commands out of completion command lists.
Library/Homebrew/test/manpages_spec.rb	Adds a test ensuring hidden commands don’t appear in generated manpage output.
Library/Homebrew/test/completions_spec.rb	Adds tests asserting hidden commands keep argument completions (bash/zsh/fish behaviors).
Library/Homebrew/test/commands_spec.rb	Adds tests asserting hidden commands are excluded from cached command lists (used for top-level suggestions).
Library/Homebrew/dev-cmd/dispatch-build-bottle.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/formula-analytics.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/generate-analytics-api.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/generate-cask-api.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/generate-formula-api.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/generate-internal-api.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/pr-automerge.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/pr-publish.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/pr-pull.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/pr-upload.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/release.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/update-license-data.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/update-maintainers.rb	Marks command hidden from manpage generation.
Library/Homebrew/dev-cmd/update-sponsors.rb	Marks command hidden from manpage generation.
completions/zsh/_brew	Regenerated zsh completion file reflecting hidden-command omission from top-level suggestions while keeping functions.
completions/internal_commands_list.txt	Regenerated internal command suggestion list with hidden commands removed.
completions/fish/brew.fish	Regenerated fish completion file omitting command suggestions for hidden commands while keeping arg completions.
completions/bash/brew	Regenerated bash completion file; top-level suggestions depend on updated cached/internal command lists.

---

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

[github-code-quality]

Code Coverage Overview

Languages: Ruby

Ruby / code-coverage/simplecov

The overall coverage in the hide-maintainer-comm... branch remains at 78%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main c6a08de	hide-maintainer-comm... e2dc82e	+/-
utils/tty.rb	92%	91%	-1%
bundle/extensio...de_extension.rb	99%	98%	-1%
download_queue.rb	74%	73%	-1%
dev-cmd/release.rb	23%	23%	0%
dev-cmd/formula-analytics.rb	17%	18%	+1%
dev-cmd/generat...nalytics-api.rb	22%	23%	+1%
dev-cmd/pr-upload.rb	32%	33%	+1%
manpages.rb	50%	54%	+4%
services/cli.rb	62%	67%	+5%
extend/pathname.rb	75%	82%	+7%

---

_{Updated June 05, 2026 09:47 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}