post_install: improvements and fixes.

- warn if running `brew postinstall` explicitly and there's no
  `post_install` defined in the formula
- add a `post_install` alias for `brew postinstall` to make life
  easier for those jumping between `postinstall` and `post_install` in
  e.g. Homebrew development
- refactor `post_install` formula path logic into a new method for
  improved readability
- handle the JSON API `post_install` formula path case

Library/Homebrew/brew.sh

@@ -826,6 +826,7 @@ case "${HOMEBREW_COMMAND}" in
   ln) HOMEBREW_COMMAND="link" ;;
   instal) HOMEBREW_COMMAND="install" ;; # gem does the same
   uninstal) HOMEBREW_COMMAND="uninstall" ;;
+  post_install) HOMEBREW_COMMAND="postinstall" ;;
   rm) HOMEBREW_COMMAND="uninstall" ;;
   remove) HOMEBREW_COMMAND="uninstall" ;;
   abv) HOMEBREW_COMMAND="info" ;;

Library/Homebrew/cmd/postinstall.rb

@@ -28,6 +28,8 @@ module Homebrew
       if f.post_install_defined?
         fi = FormulaInstaller.new(f, **{ debug: args.debug?, quiet: args.quiet?, verbose: args.verbose? }.compact)
         fi.post_install
+      else
+        opoo "#{f}: no `post_install` method was defined in the formula!"
       end
     end
   end

Library/Homebrew/commands.rb

@@ -19,6 +19,7 @@ module Commands
     "ln"           => "link",
     "instal"       => "install", # gem does the same
     "uninstal"     => "uninstall",
+    "post_install" => "postinstall",
     "rm"           => "uninstall",
     "remove"       => "uninstall",
     "abv"          => "info",

Library/Homebrew/formula_installer.rb

@@ -1095,6 +1095,36 @@ on_request: installed_on_request?, options: options)
     @show_summary_heading = true
   end
 
+  sig { returns(Pathname) }
+  def post_install_formula_path
+    # Use the formula from the keg when any of the following is true:
+    # * We're installing from the JSON API
+    # * We're installing a local bottle file
+    # * The formula doesn't exist in the tap (or the tap isn't installed)
+    # * The formula in the tap has a different `pkg_version``.
+    #
+    # In all other cases, including if the formula from the keg is unreadable
+    # (third-party taps may `require` some of their own libraries) or if there
+    # is no formula present in the keg (as is the case with very old bottles),
+    # use the formula from the tap.
+    keg_formula_path = formula.opt_prefix/".brew/#{formula.name}.rb"
+    return keg_formula_path if formula.loaded_from_api?
+    return keg_formula_path if formula.local_bottle_path.present?
+
+    tap_formula_path = formula.specified_path
+    return keg_formula_path unless tap_formula_path.exist?
+
+    begin
+      keg_formula = Formulary.factory(keg_formula_path)
+      tap_formula = Formulary.factory(tap_formula_path)
+      return keg_formula_path if keg_formula.pkg_version != tap_formula.pkg_version
+
+      tap_formula_path
+    rescue FormulaUnavailableError, FormulaUnreadableError
+      tap_formula_path
+    end
+  end
+
   sig { void }
   def post_install
     args = [
@@ -1105,34 +1135,7 @@ on_request: installed_on_request?, options: options)
       HOMEBREW_LIBRARY_PATH/"postinstall.rb"
     ]
 
-    # Use the formula from the keg if:
+    args << post_install_formula_path
-    # * Installing from a local bottle, or
-    # * The formula doesn't exist in the tap (or the tap isn't installed), or
-    # * The formula in the tap has a different pkg_version.
-    #
-    # In all other cases, including if the formula from the keg is unreadable
-    # (third-party taps may `require` some of their own libraries) or if there
-    # is no formula present in the keg (as is the case with old bottles), use
-    # the formula from the tap.
-    formula_path = begin
-      keg_formula_path = formula.opt_prefix/".brew/#{formula.name}.rb"
-      tap_formula_path = formula.specified_path
-      keg_formula = Formulary.factory(keg_formula_path)
-      tap_formula = Formulary.factory(tap_formula_path) if tap_formula_path.exist?
-      other_version_installed = (keg_formula.pkg_version != tap_formula&.pkg_version)
-
-      if formula.local_bottle_path.present? ||
-         !tap_formula_path.exist? ||
-         other_version_installed
-        keg_formula_path
-      else
-        tap_formula_path
-      end
-    rescue FormulaUnavailableError, FormulaUnreadableError
-      tap_formula_path
-    end
-
-    args << formula_path
 
     Utils.safe_fork do
       if Sandbox.available?

completions/bash/brew

@@ -1651,6 +1651,23 @@ _brew_pin() {
   __brew_complete_installed_formulae
 }
 
+_brew_post_install() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  case "${cur}" in
+    -*)
+      __brewcomp "
+      --debug
+      --help
+      --quiet
+      --verbose
+      "
+      return
+      ;;
+    *) ;;
+  esac
+  __brew_complete_installed_formulae
+}
+
 _brew_postgresql_upgrade_database() {
   local cur="${COMP_WORDS[COMP_CWORD]}"
   case "${cur}" in
@@ -2713,6 +2730,7 @@ _brew() {
     options) _brew_options ;;
     outdated) _brew_outdated ;;
     pin) _brew_pin ;;
+    post_install) _brew_post_install ;;
     postgresql-upgrade-database) _brew_postgresql_upgrade_database ;;
     postinstall) _brew_postinstall ;;
     pr-automerge) _brew_pr_automerge ;;

completions/fish/brew.fish

@@ -1134,6 +1134,14 @@ __fish_brew_complete_arg 'pin' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'pin' -a '(__fish_brew_suggest_formulae_installed)'
 
 
+__fish_brew_complete_cmd 'post_install' 'Rerun the post-install steps for formula'
+__fish_brew_complete_arg 'post_install' -l debug -d 'Display any debugging information'
+__fish_brew_complete_arg 'post_install' -l help -d 'Show this message'
+__fish_brew_complete_arg 'post_install' -l quiet -d 'Make some output more quiet'
+__fish_brew_complete_arg 'post_install' -l verbose -d 'Make some output more verbose'
+__fish_brew_complete_arg 'post_install' -a '(__fish_brew_suggest_formulae_installed)'
+
+
 __fish_brew_complete_cmd 'postgresql-upgrade-database' 'Upgrades the database for the `postgresql` formula'
 __fish_brew_complete_arg 'postgresql-upgrade-database' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'postgresql-upgrade-database' -l help -d 'Show this message'

completions/internal_commands_list.txt

@@ -68,6 +68,7 @@ nodenv-sync
 options
 outdated
 pin
+post_install
 postgresql-upgrade-database
 postinstall
 pr-automerge

completions/zsh/_brew

@@ -22,6 +22,7 @@ __brew_list_aliases() {
     ln link
     instal install
     uninstal uninstall
+    post_install postinstall
     rm uninstall
     remove uninstall
     abv info
@@ -1404,6 +1405,17 @@ _brew_pin() {
     '*::installed_formula:__brew_installed_formulae'
 }
 
+# brew post_install
+_brew_post_install() {
+  _arguments \
+    '--debug[Display any debugging information]' \
+    '--help[Show this message]' \
+    '--quiet[Make some output more quiet]' \
+    '--verbose[Make some output more verbose]' \
+    - installed_formula \
+    '*::installed_formula:__brew_installed_formulae'
+}
+
 # brew postgresql-upgrade-database
 _brew_postgresql_upgrade_database() {
   _arguments \

docs/Manpage.md

@@ -533,7 +533,7 @@ issuing the `brew upgrade` *`formula`* command. See also `unpin`.
 
 Upgrades the database for the `postgresql` formula.
 
-### `postinstall` *`installed_formula`* [...]
+### `postinstall`, `post_install` *`installed_formula`* [...]
 
 Rerun the post-install steps for *`formula`*.
 

manpages/brew.1

@@ -746,7 +746,7 @@ Pin the specified \fIformula\fR, preventing them from being upgraded when issuin
 .SS "\fBpostgresql\-upgrade\-database\fR"
 Upgrades the database for the \fBpostgresql\fR formula\.
 .
-.SS "\fBpostinstall\fR \fIinstalled_formula\fR [\.\.\.]"
+.SS "\fBpostinstall\fR, \fBpost_install\fR \fIinstalled_formula\fR [\.\.\.]"
 Rerun the post\-install steps for \fIformula\fR\.
 .
 .SS "\fBpyenv\-sync\fR"