Merge pull request #22547 from Homebrew/hide-maintainer-commands-manpage

MikeMcQuaid · web-flow · commit f66b2f63c0a6 · 2026-06-05T11:01:51.000Z
Hide maintainer commands
diff --git a/Library/Homebrew/commands.rb b/Library/Homebrew/commands.rb
@@ -211,7 +211,10 @@ def self.rebuild_internal_commands_completion_list
     require "completions"
 
     cmds = internal_commands + internal_developer_commands
-    cmds.reject! { |cmd| Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST.include? cmd }
+    cmds.reject! do |cmd|
+      Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST.include?(cmd) ||
+        Homebrew::Completions.command_hidden_from_manpage?(cmd)
+    end
 
     file = HOMEBREW_REPOSITORY/"completions/internal_commands_list.txt"
     file.atomic_write("#{cmds.sort.join("\n")}\n")
@@ -225,6 +228,7 @@ def self.rebuild_commands_completion_list
     HOMEBREW_CACHE.mkpath
 
     cmds = commands - Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST
+    cmds.reject! { |cmd| Homebrew::Completions.command_hidden_from_manpage?(cmd) }
 
     all_commands_file = HOMEBREW_CACHE/"all_commands_list.txt"
     external_commands_file = HOMEBREW_CACHE/"external_commands_list.txt"
diff --git a/Library/Homebrew/completions.rb b/Library/Homebrew/completions.rb
@@ -15,6 +15,8 @@ module Completions
       :aliases,
       :builtin_command_descriptions,
       :completion_functions,
+      :maintainer_descriptions,
+      :maintainer_commands,
       :function_mappings,
     )
 
@@ -125,7 +127,10 @@ def self.show_completions_message_if_needed
 
     sig { void }
     def self.update_shell_completions!
-      commands = Commands.commands(external: false).sort
+      commands = (Commands.internal_commands_paths + Commands.internal_developer_commands_paths)
+                 .map { |path| Commands.basename_without_extension(path) }
+                 .uniq
+                 .sort
 
       puts "Writing completions to #{COMPLETIONS_DIR}"
 
@@ -139,6 +144,21 @@ def self.command_gets_completions?(command)
       command_options(command).any? || Commands.command_subcommands(command).any?
     end
 
+    sig { params(command: String).returns(T::Boolean) }
+    def self.command_hidden_from_manpage?(command)
+      return false unless (cmd_path = Commands.path(command))
+
+      Homebrew::CLI::Parser.from_cmd_path(cmd_path)&.hide_from_man_page == true
+    end
+
+    sig { params(command: String).returns(T.nilable(String)) }
+    def self.zsh_command_description(command)
+      description = Commands.command_description(command, short: true)
+      return if description.blank?
+
+      "'#{command}:#{format_description(description)}'"
+    end
+
     sig { params(subcommands: T::Array[Homebrew::CLI::Parser::Subcommand]).returns(T::Array[String]) }
     def self.subcommand_completion_names(subcommands)
       subcommands.flat_map { |subcommand| [subcommand.name, *subcommand.aliases] }
@@ -293,6 +313,7 @@ def self.generate_bash_completion_file(commands)
         completion_functions: commands.filter_map do |command|
           generate_bash_subcommand_completion command
         end,
+        maintainer_commands:  commands.select { |command| command_hidden_from_manpage?(command) },
         function_mappings:    commands.filter_map do |command|
           next unless command_gets_completions? command
 
@@ -466,12 +487,15 @@ def self.generate_zsh_completion_file(commands)
 
         builtin_command_descriptions: commands.filter_map do |command|
           next if Commands::HOMEBREW_INTERNAL_COMMAND_ALIASES.key? command
+          next if command_hidden_from_manpage?(command)
+
+          zsh_command_description(command)
+        end,
 
-          description = Commands.command_description(command, short: true)
-          next if description.blank?
+        maintainer_descriptions:      commands.filter_map do |command|
+          next unless command_hidden_from_manpage?(command)
 
-          description = format_description description
-          "'#{command}:#{description}'"
+          zsh_command_description(command)
         end,
 
         completion_functions:         commands.filter_map do |command|
@@ -484,18 +508,20 @@ def self.generate_zsh_completion_file(commands)
 
     sig { params(command: String).returns(T.nilable(String)) }
     def self.generate_fish_subcommand_completion(command)
-      return unless command_gets_completions? command
-
-      subcommands = Commands.command_subcommands(command)
-      return generate_fish_nested_subcommand_completion(command, subcommands) if subcommands.present?
-
       command_description = format_description Commands.command_description(command, short: true).to_s, fish: true
       lines = if COMPLETIONS_EXCLUSION_LIST.include?(command) ||
                  Commands::HOMEBREW_INTERNAL_COMMAND_ALIASES.key?(command)
         []
+      elsif command_hidden_from_manpage?(command)
+        ["complete -f -c brew -n 'not __fish_brew_command; and set -q HOMEBREW_DEVELOPER' " \
+         "-a '#{command}' -d '#{command_description}'"]
       else
         ["__fish_brew_complete_cmd '#{command}' '#{command_description}'"]
       end
+      return unless command_gets_completions? command
+
+      subcommands = Commands.command_subcommands(command)
+      return generate_fish_nested_subcommand_completion(command, subcommands) if subcommands.present?
 
       options = command_options(command).sort.filter_map do |opt, desc|
         arg_line = "__fish_brew_complete_arg '#{command}' -l #{opt.sub(/^-+/, "")}"
diff --git a/Library/Homebrew/completions/bash.erb b/Library/Homebrew/completions/bash.erb
@@ -113,6 +113,7 @@ __brew_complete_commands() {
 
   local cur="${COMP_WORDS[COMP_CWORD]}"
   local cmds
+  local maintainer_cmds
 
   if [[ -n ${__HOMEBREW_COMMANDS} ]]
   then
@@ -124,11 +125,15 @@ __brew_complete_commands() {
   then
     cmds="$(< "${HOMEBREW_REPOSITORY}/completions/internal_commands_list.txt")"
   fi
+  if [[ -n ${HOMEBREW_DEVELOPER:-} ]]
+  then
+    maintainer_cmds="<%= maintainer_commands.join(" ") %>"
+  fi
   while read -r line
   do
     [[ $(__brew_internal_command_alias "${line}") == "${line}" ]] || continue
     COMPREPLY+=("${line}")
-  done < <(compgen -W "${cmds}" -- "${cur}")
+  done < <(compgen -W "${cmds} ${maintainer_cmds}" -- "${cur}")
   export __HOMEBREW_COMMANDS=${cmds}
 }
 
diff --git a/Library/Homebrew/completions/zsh.erb b/Library/Homebrew/completions/zsh.erb
@@ -132,6 +132,11 @@ __brew_internal_commands() {
   commands=(
     <%= builtin_command_descriptions.join("\n    ") + "\n" %>
   )
+  if [[ -n ${HOMEBREW_DEVELOPER:-} ]]; then
+    commands+=(
+      <%= maintainer_descriptions.join("\n      ") + "\n" %>
+    )
+  fi
   _describe -t internal-commands 'internal commands' commands
 }
 
diff --git a/Library/Homebrew/dev-cmd/dispatch-build-bottle.rb b/Library/Homebrew/dev-cmd/dispatch-build-bottle.rb
@@ -35,6 +35,8 @@ class DispatchBuildBottle < AbstractCommand
         conflicts "--linux", "--linux-self-hosted"
 
         named_args :formula, min: 1
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/formula-analytics.rb b/Library/Homebrew/dev-cmd/formula-analytics.rb
@@ -54,6 +54,8 @@ class FormulaAnalytics < AbstractCommand
         conflicts "--json", "--all-core-formulae-json", "--setup"
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       FIRST_INFLUXDB_ANALYTICS_DATE = T.let(Date.new(2023, 03, 27).freeze, Date)
diff --git a/Library/Homebrew/dev-cmd/generate-analytics-api.rb b/Library/Homebrew/dev-cmd/generate-analytics-api.rb
@@ -27,6 +27,8 @@ class GenerateAnalyticsApi < AbstractCommand
         EOS
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { params(category_name: String, data_source: T.nilable(String)).returns(String) }
diff --git a/Library/Homebrew/dev-cmd/generate-cask-api.rb b/Library/Homebrew/dev-cmd/generate-cask-api.rb
@@ -25,6 +25,8 @@ class GenerateCaskApi < AbstractCommand
                description: "Generate API data without writing it to files."
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/generate-formula-api.rb b/Library/Homebrew/dev-cmd/generate-formula-api.rb
@@ -26,6 +26,8 @@ class GenerateFormulaApi < AbstractCommand
                description: "Generate API data without writing it to files."
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/generate-internal-api.rb b/Library/Homebrew/dev-cmd/generate-internal-api.rb
@@ -20,6 +20,8 @@ class GenerateInternalApi < AbstractCommand
                description: "Generate internal API data without writing it to files."
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/pr-automerge.rb b/Library/Homebrew/dev-cmd/pr-automerge.rb
@@ -33,6 +33,8 @@ class PrAutomerge < AbstractCommand
                description: "Include pull requests that have failing status checks."
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/pr-publish.rb b/Library/Homebrew/dev-cmd/pr-publish.rb
@@ -29,6 +29,8 @@ class PrPublish < AbstractCommand
                description: "Target workflow filename (default: `publish-commit-bottles.yml`)."
 
         named_args :pull_request, min: 1
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/pr-pull.rb b/Library/Homebrew/dev-cmd/pr-pull.rb
@@ -69,6 +69,8 @@ class PrPull < AbstractCommand
         conflicts "--clean", "--autosquash"
 
         named_args :pull_request, min: 1
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/pr-upload.rb b/Library/Homebrew/dev-cmd/pr-upload.rb
@@ -39,6 +39,8 @@ class PrUpload < AbstractCommand
         conflicts "--upload-only", "--no-commit"
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/release.rb b/Library/Homebrew/dev-cmd/release.rb
@@ -31,6 +31,8 @@ class Release < AbstractCommand
         conflicts "--major", "--minor"
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/update-license-data.rb b/Library/Homebrew/dev-cmd/update-license-data.rb
@@ -16,6 +16,8 @@ class UpdateLicenseData < AbstractCommand
         EOS
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/update-maintainers.rb b/Library/Homebrew/dev-cmd/update-maintainers.rb
@@ -17,6 +17,8 @@ class UpdateMaintainers < AbstractCommand
         EOS
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/dev-cmd/update-sponsors.rb b/Library/Homebrew/dev-cmd/update-sponsors.rb
@@ -19,6 +19,8 @@ class UpdateSponsors < AbstractCommand
         EOS
 
         named_args :none
+
+        hide_from_man_page!
       end
 
       sig { override.void }
diff --git a/Library/Homebrew/test/commands_spec.rb b/Library/Homebrew/test/commands_spec.rb
@@ -50,6 +50,15 @@
     expect(cmds).not_to include("rbdevcmd"), "Dev commands shouldn't be included"
   end
 
+  specify "::internal_commands omits commands hidden from the manpage" do
+    hidden_parser = instance_double(Homebrew::CLI::Parser, hide_from_man_page: true)
+    allow(Homebrew::CLI::Parser).to receive(:from_cmd_path).and_call_original
+    allow(Homebrew::CLI::Parser).to receive(:from_cmd_path).with(Commands::HOMEBREW_CMD_PATH/"rbcmd.rb")
+                                                           .and_return(hidden_parser)
+
+    expect(klass.internal_commands).not_to include("rbcmd")
+  end
+
   specify "::internal_developer_commands" do
     cmds = klass.internal_developer_commands
     expect(cmds).to include("rbdevcmd"), "Ruby commands files should be recognized"
@@ -91,6 +100,22 @@
         expect(commands & klass.internal_commands_aliases).to be_empty
       end
     end
+
+    it "omits commands hidden from the manpage" do
+      mktmpdir do |repository|
+        stub_const("HOMEBREW_REPOSITORY", repository)
+        (repository/"completions").mkpath
+        hidden_parser = instance_double(Homebrew::CLI::Parser, hide_from_man_page: true)
+        allow(Homebrew::CLI::Parser).to receive(:from_cmd_path).and_call_original
+        allow(Homebrew::CLI::Parser).to receive(:from_cmd_path).with(Commands::HOMEBREW_CMD_PATH/"rbcmd.rb")
+                                                               .and_return(hidden_parser)
+
+        klass.rebuild_internal_commands_completion_list
+
+        commands = (repository/"completions/internal_commands_list.txt").read.lines(chomp: true)
+        expect(commands).not_to include("rbcmd")
+      end
+    end
   end
 
   describe "::rebuild_commands_completion_list" do
@@ -105,6 +130,22 @@
         expect(commands & klass.internal_commands_aliases).to be_empty
       end
     end
+
+    it "omits commands hidden from the manpage from the cached command list" do
+      mktmpdir do |cache|
+        stub_const("HOMEBREW_CACHE", cache)
+        allow(klass).to receive(:external_commands).and_return(["external"])
+        hidden_parser = instance_double(Homebrew::CLI::Parser, hide_from_man_page: true)
+        allow(Homebrew::CLI::Parser).to receive(:from_cmd_path).and_call_original
+        allow(Homebrew::CLI::Parser).to receive(:from_cmd_path).with(Commands::HOMEBREW_CMD_PATH/"rbcmd.rb")
+                                                               .and_return(hidden_parser)
+
+        klass.rebuild_commands_completion_list
+
+        commands = (cache/"all_commands_list.txt").read.lines(chomp: true)
+        expect(commands).not_to include("rbcmd")
+      end
+    end
   end
 
   describe "::path" do
diff --git a/Library/Homebrew/test/completions_spec.rb b/Library/Homebrew/test/completions_spec.rb
@@ -411,6 +411,14 @@ def stub_nested_completion_command(command, subcommands)
         expect(file).to match(/^ {4}up\) echo "update" ;;$/)
         expect(file).to match(/^ {4}update\) _brew_update ;;$/)
       end
+
+      it "keeps argument completions for commands hidden from the manpage" do
+        file = klass.generate_bash_completion_file(%w[generate-internal-api])
+        expect(file).to include("if [[ -n ${HOMEBREW_DEVELOPER:-} ]]")
+        expect(file).to include('maintainer_cmds="generate-internal-api"')
+        expect(file).to match(/^_brew_generate_internal_api\(\) {$/)
+        expect(file).to match(/^ {4}generate-internal-api\) _brew_generate_internal_api ;;/)
+      end
     end
 
     describe ".generate_zsh_subcommand_completion" do
@@ -505,6 +513,14 @@ def stub_nested_completion_command(command, subcommands)
         expect(file).to match(/^_brew_update\(\) {$/)
         expect(file).to match(/^_brew "\$@"$/)
       end
+
+      it "maintainer-gates command completions but keeps argument completions for commands hidden from the manpage" do
+        file = klass.generate_zsh_completion_file(%w[generate-internal-api])
+        expect(file).to include("if [[ -n ${HOMEBREW_DEVELOPER:-} ]]; then")
+        expect(file).to match(/^      'generate-internal-api:Generate internal API data files for .*'$/)
+        expect(file).to match(/^# brew generate-internal-api$/)
+        expect(file).to match(/^_brew_generate_internal_api\(\) {$/)
+      end
     end
 
     describe ".generate_fish_subcommand_completion" do
@@ -565,6 +581,13 @@ def stub_nested_completion_command(command, subcommands)
         expect(completion).to include("__fish_brew_complete_sub_arg 'subcommand-test' 'info i' " \
                                       "-a '(__fish_brew_suggest_services)'")
       end
+
+      it "maintainer-gates command completions but keeps argument completions for commands hidden from the manpage" do
+        completion = klass.generate_fish_subcommand_completion("generate-internal-api")
+        expect(completion).to include("set -q HOMEBREW_DEVELOPER")
+        expect(completion).to include("-a 'generate-internal-api'")
+        expect(completion).to include("__fish_brew_complete_arg 'generate-internal-api' -l dry-run")
+      end
     end
 
     describe ".generate_fish_completion_file" do
diff --git a/Library/Homebrew/test/manpages_spec.rb b/Library/Homebrew/test/manpages_spec.rb
diff --git a/completions/bash/brew b/completions/bash/brew
diff --git a/completions/fish/brew.fish b/completions/fish/brew.fish
diff --git a/completions/internal_commands_list.txt b/completions/internal_commands_list.txt
diff --git a/completions/zsh/_brew b/completions/zsh/_brew
diff --git a/docs/Manpage.md b/docs/Manpage.md
diff --git a/manpages/brew.1 b/manpages/brew.1

Original file line number	Diff line number	Diff line change
`@@ -132,6 +132,11 @@ __brew_internal_commands() {`
`132`	`132`	`commands=(`
`133`	`133`	`<%= builtin_command_descriptions.join("\n ") + "\n" %>`
`134`	`134`	`)`
	`135`	`+ if [[ -n ${HOMEBREW_DEVELOPER:-} ]]; then`
	`136`	`+ commands+=(`
	`137`	`+ <%= maintainer_descriptions.join("\n ") + "\n" %>`
	`138`	`+ )`
	`139`	`+ fi`
`135`	`140`	`_describe -t internal-commands 'internal commands' commands`
`136`	`141`	`}`
`137`	`142`