brew.rb: tell users to fix head issues with inreplace

Library/Homebrew/formula.rb

@@ -69,9 +69,6 @@ class Formula
   extend Cachable
   extend Predicable
 
-  # @!method inreplace(paths, before = nil, after = nil)
-  # @see Utils::Inreplace.inreplace
-
   # The name of this {Formula}.
   # e.g. `this-formula`
   attr_reader :name
@@ -2169,6 +2166,12 @@ class Formula
   # end</pre>
   def install; end
 
+  def inreplace(paths, before = nil, after = nil, audit_result = true) # rubocop:disable Style/OptionalBooleanParameter
+    super(paths, before, after, audit_result)
+  rescue Utils::Inreplace::Error
+    raise BuildError.new(self, "inreplace", paths, nil)
+  end
+
   protected
 
   def setup_home(home)

Library/Homebrew/test/formula_spec.rb

@@ -483,6 +483,16 @@ describe Formula do
     end
   end
 
+  describe "::inreplace" do
+    specify "raises build error on failure" do
+      f = formula do
+        url "https://brew.sh/test-1.0.tbz"
+      end
+
+      expect { f.inreplace([]) }.to raise_error(BuildError)
+    end
+  end
+
   describe "::installed_with_alias_path" do
     specify "with alias path with nil" do
       expect(described_class.installed_with_alias_path(nil)).to be_empty

Library/Homebrew/utils/inreplace.rb

@@ -10,7 +10,7 @@ module Utils
   module Inreplace
     extend T::Sig
 
-    # Error during replacement.
+    # Error during text replacement.
     class Error < RuntimeError
       def initialize(errors)
         formatted_errors = errors.reduce(+"inreplace failed\n") do |s, (path, errs)|
@@ -70,7 +70,7 @@ module Utils
         Pathname(path).atomic_write(s.inreplace_string)
       end
 
-      raise Error, errors unless errors.empty?
+      raise Utils::Inreplace::Error, errors unless errors.empty?
     end
 
     # @api private
@@ -86,7 +86,7 @@ module Utils
 
         contents.gsub!(old, new)
       end
-      raise Error, path => contents.errors unless contents.errors.empty?
+      raise Utils::Inreplace::Error, [path => contents.errors] unless contents.errors.empty?
 
       Pathname(path).atomic_write(contents.inreplace_string) unless read_only_run
       contents.inreplace_string