upgrade: announce usage of --all.HEADmaster

Tell users that we will soon be migrating `--all` so it is required if
you wish to upgrade all formulae.

Closes #38572.

2 files changed, 19 insertions, 3 deletions

diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb
index 10d323b14..8ba3eb8fc 100644
--- a/Library/Homebrew/cmd/upgrade.rb
+++ b/Library/Homebrew/cmd/upgrade.rb
@@ -5,10 +5,17 @@ module Homebrew
   def upgrade
     Homebrew.perform_preinstall_checks
 
-    if ARGV.named.empty?
+    if ARGV.include?("--all") || ARGV.named.empty?
+      unless ARGV.include? "--all"
+        opoo <<-EOS.undent
+          brew upgrade with no arguments will change behaviour soon!
+          It currently upgrades all formula but this will soon change to require '--all'.
+          Please update any workflows, documentation and scripts!
+        EOS
+      end
       outdated = Homebrew.outdated_brews(Formula.installed)
       exit 0 if outdated.empty?
-    else
+    elsif ARGV.named.any?
       outdated = Homebrew.outdated_brews(ARGV.formulae)
 
       (ARGV.formulae - outdated).each do |f|
@@ -20,6 +27,11 @@ module Homebrew
         end
       end
       exit 1 if outdated.empty?
+    else
+      # This will currently never be reached but is implemented to make the
+      # migration to --all easier in the future (as just the ARGV.named.empty?
+      # will need removed above).
+      odie "Either --all or one or more formulae must be specified!"
     end
 
     unless upgrade_pinned?
diff --git a/Library/Homebrew/manpages/brew.1.md b/Library/Homebrew/manpages/brew.1.md
index 8f1f2b161..57c49cae9 100644
--- a/Library/Homebrew/manpages/brew.1.md
+++ b/Library/Homebrew/manpages/brew.1.md
@@ -390,11 +390,15 @@ Note that these flags should only appear after a command.
 
     If `--rebase` is specified then `git pull --rebase` is used.
 
-  * `upgrade [install-options]` [<formulae>]:
+  * `upgrade [--all] [install-options]` [<formulae>]:
     Upgrade outdated, unpinned brews.
 
     Options for the `install` command are also valid here.
 
+    If `--all` is passed, upgrade all formulae. This is currently the same
+    behaviour as without `--all` but soon `--all` will be required to upgrade
+    all formulae.
+
     If <formulae> are given, upgrade only the specified brews (but do so even
     if they are pinned; see `pin`, `unpin`).