From 577aec3f60a96bac7ea44247184ace5e8a0e8c28 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issylong.com>
Date: Tue, 26 Aug 2025 14:25:39 +0200
Subject: [PATCH] Encourage using a default branch for HEAD core formulae

- We don't mind if third-party taps have non-default HEAD branches - they have their reasons.
- But we want -core to be consistent, hence why there's the allowlist file.
- https://github.com/Homebrew/brew/pull/20402#discussion_r2292366323
---
 Library/Homebrew/formula_auditor.rb           |  2 +-
 Library/Homebrew/resource_auditor.rb          | 12 +++++++++---
 Library/Homebrew/test/formula_auditor_spec.rb |  6 +++---
 3 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/Library/Homebrew/formula_auditor.rb b/Library/Homebrew/formula_auditor.rb
index 2017a4e34f..237be61965 100644
--- a/Library/Homebrew/formula_auditor.rb
+++ b/Library/Homebrew/formula_auditor.rb
@@ -763,7 +763,7 @@ module Homebrew
 
         ra = ResourceAuditor.new(
           spec, spec_name,
-          online: @online, strict: @strict, only: @only, except:,
+          online: @online, strict: @strict, only: @only, core_tap: @core_tap, except:,
           use_homebrew_curl: spec.using == :homebrew_curl
         ).audit
         ra.problems.each do |message|
diff --git a/Library/Homebrew/resource_auditor.rb b/Library/Homebrew/resource_auditor.rb
index bb0d5e81fe..05f078b152 100644
--- a/Library/Homebrew/resource_auditor.rb
+++ b/Library/Homebrew/resource_auditor.rb
@@ -24,6 +24,7 @@ module Homebrew
       @strict    = options[:strict]
       @only      = options[:only]
       @except    = options[:except]
+      @core_tap  = options[:core_tap]
       @use_homebrew_curl = options[:use_homebrew_curl]
       @problems = []
     end
@@ -190,10 +191,15 @@ module Homebrew
       detected_branch = Utils.popen_read("git", "ls-remote", "--symref", url, "HEAD")
                              .match(%r{ref: refs/heads/(.*?)\s+HEAD})&.to_a&.second
 
-      message = "Git `head` URL must specify a branch name"
-      message += " - try `branch: \"#{detected_branch}\"`" if detected_branch.present?
+      if specs[:branch].blank?
+        problem "Git `head` URL must specify a branch name"
+        return
+      end
 
-      problem message if specs[:branch].blank? || detected_branch != specs[:branch]
+      return unless @core_tap
+      return if specs[:branch] == detected_branch
+
+      problem "To use a non-default HEAD branch, add the formula to `head_non_default_branch_allowlist.json`."
     end
 
     def problem(text)
diff --git a/Library/Homebrew/test/formula_auditor_spec.rb b/Library/Homebrew/test/formula_auditor_spec.rb
index 9c5253ac1a..abee6896f7 100644
--- a/Library/Homebrew/test/formula_auditor_spec.rb
+++ b/Library/Homebrew/test/formula_auditor_spec.rb
@@ -729,7 +729,7 @@ RSpec.describe Homebrew::FormulaAuditor do
     end
 
     it "suggests a detected default branch for Git head URLs" do
-      fa = formula_auditor "foo", <<~RUBY, online: true
+      fa = formula_auditor "foo", <<~RUBY, online: true, core_tap: true
         class Foo < Formula
           url "https://brew.sh/foo-1.0.tgz"
           sha256 "31cccfc6630528db1c8e3a06f6decf2a370060b982841cfab2b8677400a5092e"
@@ -737,13 +737,13 @@ RSpec.describe Homebrew::FormulaAuditor do
         end
       RUBY
 
-      message = "Git `head` URL must specify a branch name - try `branch: \"main\"`"
+      message = "To use a non-default HEAD branch, add the formula to `head_non_default_branch_allowlist.json`."
       fa.audit_specs
       # This is `.last` because the first problem is the unreachable stable URL.
       expect(fa.problems.last[:message]).to match(message)
     end
 
-    it "ignores a pre-existing correct HEAD branch name" do
+    it "can specify a default branch without an allowlist if not in a core tap" do
       fa = formula_auditor "foo", <<~RUBY, online: true
         class Foo < Formula
           url "https://brew.sh/foo-1.0.tgz"