extract: Add the --revision argument

When pinning formula alongside its dependencies it's important to limit
the search scope.

Library/Homebrew/dev-cmd/extract.rb

@@ -22,6 +22,8 @@ class Extract < AbstractCommand
           a formula from a tap that is not `homebrew/core` use its fully-qualified form of
           <user>`/`<repo>`/`<formula>.
         EOS
+        flag   "--revision=",
+               description: "Search for the specified <version> of <formula> starting at <revision> instead of HEAD."
         flag   "--version=",
                description: "Extract the specified <version> of <formula> instead of the most recent."
         switch "-f", "--force",
@@ -49,6 +51,7 @@ def run
         destination_tap.install unless destination_tap.installed?
 
         repo = source_tap.path
+        default_revision = args.revision || "HEAD"
         pattern = if source_tap.core_tap?
           [source_tap.new_formula_path(name), repo/"Formula/#{name}.rb"].uniq
         else
@@ -64,7 +67,7 @@ def run
           test_formula = T.let(nil, T.nilable(Formula))
           result = ""
           loop do
-            rev = rev.nil? ? "HEAD" : "#{rev}~1"
+            rev = rev.nil? ? default_revision : "#{rev}~1"
             rev, (path,) = Utils::Git.last_revision_commit_of_files(repo, pattern, before_commit: rev)
             if rev.nil? && source_tap.shallow?
               odie <<~EOS
@@ -112,7 +115,7 @@ def run
             result = Utils::Git.last_revision_of_file(repo, file)
           else
             file = files.fetch(0).realpath
-            rev = T.let("HEAD", T.nilable(String))
+            rev = T.let(default_revision, T.nilable(String))
             version = Formulary.factory(file).version
             result = File.read(file)
           end

Library/Homebrew/test/dev-cmd/extract_spec.rb

@@ -44,6 +44,16 @@
       expect(Formulary.factory(path).version).to eq "0.2"
     end
 
+    it "retrieves the most recent version of formula starting at the specified revision", :integration_test do
+      path = target[:path]/"Formula/[email protected]"
+      expect { brew "extract", "testball", target[:name], "--revision=HEAD~1" }
+        .to output(/^#{path}$/).to_stdout
+        .and not_to_output.to_stderr
+        .and be_a_success
+      expect(path).to exist
+      expect(Formulary.factory(path).version).to eq "0.1"
+    end
+
     it "retrieves the specified version of formula", :integration_test do
       path = target[:path]/"Formula/[email protected]"
       expect { brew "extract", "testball", target[:name], "--version=0.1" }