Add brew update-if-needed

This uses the logic in `brew.sh` for deciding whether or not to run
`brew update --auto-update` and makes it a dedicated command that can
be used instead of `brew update` in scripts to be really fast in the
no-op case.

`brew update` will always do at least some updating which is a nicer
default but is much slower.

Library/Homebrew/brew.sh

@@ -384,6 +384,22 @@ auto-update() {
   unset HOMEBREW_AUTO_UPDATE_CASK_TAP
 }
 
+# Only `brew update-if-needed` should be handled here.
+# We want it as fast as possible but it needs auto-update() defined above.
+# HOMEBREW_LIBRARY set by bin/brew
+# shellcheck disable=SC2154
+# doesn't need a default case as other arguments handled elsewhere.
+# shellcheck disable=SC2249
+# Don't need to pass through any arguments.
+# shellcheck disable=SC2119
+case "$@" in
+  update-if-needed)
+    source "${HOMEBREW_LIBRARY}/Homebrew/cmd/update-if-needed.sh"
+    homebrew-update-if-needed
+    exit 0
+    ;;
+esac
+
 #####
 ##### Setup output so e.g. odie looks as nice as possible.
 #####

Library/Homebrew/cmd/update-if-needed.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "abstract_command"
+require "shell_command"
+
+module Homebrew
+  module Cmd
+    class UpdateIfNeeded < AbstractCommand
+      include ShellCommand
+
+      cmd_args do
+        description <<~EOS
+          Runs `brew update --auto-update` only if needed.
+          This is a good replacement for `brew update` in scripts where you want
+          the no-op case to be both possible and really fast.
+        EOS
+
+        named_args :none
+      end
+    end
+  end
+end

Library/Homebrew/cmd/update-if-needed.sh

@@ -0,0 +1,6 @@
+# Documentation defined in Library/Homebrew/cmd/update-if-needed.rb
+
+homebrew-update-if-needed() {
+  export HOMEBREW_AUTO_UPDATE_COMMAND="1"
+  auto-update "$@"
+}

completions/bash/brew

@@ -2798,6 +2798,22 @@ _brew_update() {
   esac
 }
 
+_brew_update_if_needed() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  case "${cur}" in
+    -*)
+      __brewcomp "
+      --debug
+      --help
+      --quiet
+      --verbose
+      "
+      return
+      ;;
+    *) ;;
+  esac
+}
+
 _brew_update_license_data() {
   local cur="${COMP_WORDS[COMP_CWORD]}"
   case "${cur}" in
@@ -3214,6 +3230,7 @@ _brew() {
     untap) _brew_untap ;;
     up) _brew_up ;;
     update) _brew_update ;;
+    update-if-needed) _brew_update_if_needed ;;
     update-license-data) _brew_update_license_data ;;
     update-maintainers) _brew_update_maintainers ;;
     update-python-resources) _brew_update_python_resources ;;

completions/fish/brew.fish

@@ -1800,6 +1800,13 @@ __fish_brew_complete_arg 'update' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'update' -l verbose -d 'Print the directories checked and `git` operations performed'
 
 
+__fish_brew_complete_cmd 'update-if-needed' 'Runs `brew update --auto-update` only if needed'
+__fish_brew_complete_arg 'update-if-needed' -l debug -d 'Display any debugging information'
+__fish_brew_complete_arg 'update-if-needed' -l help -d 'Show this message'
+__fish_brew_complete_arg 'update-if-needed' -l quiet -d 'Make some output more quiet'
+__fish_brew_complete_arg 'update-if-needed' -l verbose -d 'Make some output more verbose'
+
+
 __fish_brew_complete_cmd 'update-license-data' 'Update SPDX license data in the Homebrew repository'
 __fish_brew_complete_arg 'update-license-data' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'update-license-data' -l help -d 'Show this message'

completions/internal_commands_list.txt

@@ -114,6 +114,7 @@ unpin
 untap
 up
 update
+update-if-needed
 update-license-data
 update-maintainers
 update-python-resources

completions/zsh/_brew

@@ -232,6 +232,7 @@ __brew_internal_commands() {
     'unpin:Unpin formula, allowing them to be upgraded by `brew upgrade` formula'
     'untap:Remove a tapped formula repository'
     'update:Fetch the newest version of Homebrew and all formulae from GitHub using `git`(1) and perform any necessary migrations'
+    'update-if-needed:Runs `brew update --auto-update` only if needed'
     'update-license-data:Update SPDX license data in the Homebrew repository'
     'update-maintainers:Update the list of maintainers in the `Homebrew/brew` README'
     'update-python-resources:Update versions for PyPI resource blocks in formula'
@@ -2223,6 +2224,15 @@ _brew_update() {
     '--verbose[Print the directories checked and `git` operations performed]'
 }
 
+# brew update-if-needed
+_brew_update_if_needed() {
+  _arguments \
+    '--debug[Display any debugging information]' \
+    '--help[Show this message]' \
+    '--quiet[Make some output more quiet]' \
+    '--verbose[Make some output more verbose]'
+}
+
 # brew update-license-data
 _brew_update_license_data() {
   _arguments \

docs/Manpage.md

@@ -1610,6 +1610,12 @@ and perform any necessary migrations.
 
 : Display a trace of all shell commands as they are executed.
 
+### `update-if-needed`
+
+Runs `brew update --auto-update` only if needed. This is a good replacement for
+`brew update` in scripts where you want the no-op case to be both possible and
+really fast.
+
 ### `update-reset` \[*`repository`* ...\]
 
 Fetch and reset Homebrew and all tap repositories (or any specified

manpages/brew.1

@@ -1005,6 +1005,8 @@ Print the directories checked and \fBgit\fP operations performed\.
 .TP
 \fB\-d\fP, \fB\-\-debug\fP
 Display a trace of all shell commands as they are executed\.
+.SS "\fBupdate\-if\-needed\fP"
+Runs \fBbrew update \-\-auto\-update\fP only if needed\. This is a good replacement for \fBbrew update\fP in scripts where you want the no\-op case to be both possible and really fast\.
 .SS "\fBupdate\-reset\fP \fR[\fIrepository\fP \.\.\.]"
 Fetch and reset Homebrew and all tap repositories (or any specified \fIrepository\fP) using \fBgit\fP(1) to their latest \fBorigin/HEAD\fP\&\.
 .P