Bug: initial brew bundle dump --global ignores XDG_CONFIG_HOME

[texastoland]

brew doctor output

Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: You are using macOS 26.
We do not provide support for this pre-release version.

This is a Tier 2 configuration:
  https://docs.brew.sh/Support-Tiers#tier-2
You can report Tier 2 unrelated issues to Homebrew/* repositories!
Read the above document instead before opening any issues or PRs.

Verification

• I ran brew update twice and am still able to reproduce my issue.
• My "brew doctor output" above says Your system is ready to brew or a definitely unrelated Tier message.
• This issue's title and/or description do not reference a single formula e.g. brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.

brew config output

HOMEBREW_VERSION: 4.6.8
ORIGIN: https://github.com/Homebrew/brew
HEAD: 9da27e1ac280ce720dfcbe6d5dac0dab2dcfc508
Last commit: 24 hours ago
Branch: stable
Core tap JSON: 03 Sep 08:03 UTC
Core cask tap JSON: 03 Sep 08:03 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_EDITOR: edit
HOMEBREW_FORBID_PACKAGES_FROM_PATHS: set
HOMEBREW_MAKE_JOBS: 10
Homebrew Ruby: 3.4.5 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/3.4.5/bin/ruby
CPU: deca-core 64-bit arm_firestorm_icestorm
Clang: 17.0.0 build 1700
Git: 2.50.1 => /Library/Developer/CommandLineTools/usr/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 26.0-arm64
CLT: 26.0.0.0.1.1755155385
Xcode: N/A
Rosetta 2: false

What were you trying to do (and why)?

brew bundle dump --global

What happened (include all command output)?

Successfully creates a new $HOME/.Brewfile.

What did you expect to happen?

Creates $XDG_CONFIG_HOME/homebrew/Brewfile (defined in my .zprofile).

Step-by-step reproduction instructions (by running brew commands)

The issue (bug?) appears to be the following code requires a Brewfile already exists:

brew/Library/Homebrew/bundle/brewfile.rb

Lines 27 to 33 in ab980dc

	if user_config_home && File.exist?("#{user_config_home}/Brewfile")
	"#{user_config_home}/Brewfile"
	else
	Bundle.exchange_uid_if_needed! do
	"#{Dir.home}/.Brewfile"
	end
	end

Where I assume:

brew/Library/Homebrew/bundle/brewfile.rb

Line 19 in ab980dc

user_config_home = ENV.fetch("HOMEBREW_USER_CONFIG_HOME", nil)

Comes from:

brew/bin/brew

Lines 152 to 157 in ab980dc

	if [[ -n "${XDG_CONFIG_HOME-}" ]]
	then
	HOMEBREW_USER_CONFIG_HOME="${XDG_CONFIG_HOME}/homebrew"
	else
	HOMEBREW_USER_CONFIG_HOME="${HOME}/.homebrew"
	fi

I'm not sure what the fix should be. If either environment variable was explicitly defined I'd expect it to be used or else follow the current behavior. Alternatively checking for the existence of $HOMEBREW_USER_CONFIG_HOME would be preferable to the Brewfile itself.

[MikeMcQuaid]

Thanks for the report @texastoland This is a bit of a tricky backwards compatibility issue because we want to keep the default as ~/.Brewfile for people who have already set it and for new Brewfiles being dumped (at least until we note a "breaking" change of changing this default).

I agree in your case, however, when XDG_CONFIG_HOME is already set that it should be used here.

[texastoland]

Yes I understand.

Alternatively checking for the existence of $HOMEBREW_USER_CONFIG_HOME would be preferable to the Brewfile itself.

This idea wasn't right. The documented ways to change the global Brewfile are implicitly using $XDG_CONFIG_HOME or explicitly using $HOMEBREW_BUNDLE_FILE_GLOBAL. I believe the solution would be to set $HOMEBREW_BUNDLE_FILE_GLOBAL (if empty) in bin/brew and remove the existence check in bundle/brewfile.rb.

Can PR if satisfactory?

[MikeMcQuaid]

@texastoland Yeh, a PR is the best way to discuss a possible implementation. Thanks!