brew-bundle: update usage info and move to --help function

Follow-up to 6697ff6c9d0d4301adfbb7c76628808a63f1324b

Closes Homebrew/homebrew#25130.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>

1 files changed, 29 insertions, 15 deletions

diff --git a/Library/Contributions/cmd/brew-bundle.rb b/Library/Contributions/cmd/brew-bundle.rb
index 0a9ce1ebc..ec1898e09 100755
--- a/Library/Contributions/cmd/brew-bundle.rb
+++ b/Library/Contributions/cmd/brew-bundle.rb
@@ -1,19 +1,33 @@
 # brew-bundle.rb
-#
-# Usage: brew bundle [path]
-#
-# Looks for a Brewfile and runs each line as a brew command.
-#
-# brew bundle              # Looks for "./Brewfile"
-# brew bundle path/to/dir  # Looks for "path/to/dir/Brewfile"
-# brew bundle path/to/file # Looks for "path/to/file"
-#
-# For example, given a Brewfile with the following contents:
-# tap foo/bar
-# install spark
-#
-# Running `brew bundle` will run the commands `brew tap foo/bar`
-# and `brew install spark`.
+
+def usage
+  puts <<-EOS.undent
+  Usage: brew bundle [path]
+
+  Looks for a Brewfile and runs each line as a brew command.
+
+  brew bundle              # Looks for "./Brewfile"
+  brew bundle path/to/dir  # Looks for "path/to/dir/Brewfile"
+  brew bundle path/to/file # Looks for "path/to/file"
+
+  For example, given a Brewfile with the following content:
+    install formula
+
+  Running `brew bundle` will run the command `brew install formula`.
+
+  NOTE: Not all brew commands will work consistently in a Brewfile.
+  Some commands will raise errors which will stop execution of the Brewfile.
+
+  Example that outputs an error:
+    tap my/tap  # fails when my/tap has already been tapped
+
+  In this case use the full formula path in the Brewfile instead:
+    install my/tap/formula  # succeeds even when my/tap has already been tapped
+  EOS
+  exit
+end
+
+usage if ARGV.include?('--help') || ARGV.include?('-h')
 
 path = 'Brewfile'
 error = ' in current directory'