brew bundle dump: add --os-guards flag to wrap platform-specific entries with if OS.mac?/if OS.linux?

[levontumanyan]

Problem

brew bundle dump captures all installed formulae, casks, and extensions without any platform awareness. On a shared cross-platform dotfiles setup (macOS + Linux), running brew bundle install on a Linux machine will attempt — and fail — to install macOS-only formulae like container (which declares depends_on :macos in its formula), casks (which are macOS-only by nature), and mas entries (Mac App Store, macOS-only).

Brewfiles already support Ruby conditionals natively via if OS.mac? / if OS.linux? (since these are evaluated with instance_eval), and many users add these manually. The missing piece is that dump has no awareness of platform constraints, so the guards are lost on every dump.

Prior Art

This was raised in Homebrew/homebrew-bundle before bundle was merged into Homebrew/brew:

• homebrew-bundle#517 — Interest in Mac/Linux platform awareness in homebrew-bundle (closed as outdated)
• homebrew-bundle#533 — Linux support PR, which added the Skipper mechanism and noted that platform-specific formulae still require manual if OS.mac? guards

Proposed Solution

Add an opt-in --os-guards flag to brew bundle dump that wraps platform-specific entries with the appropriate guard:

# Without --os-guards (current behaviour)
brew "container"
cask "iterm2"
mas "Xcode", id: 497799835

# With --os-guards
if OS.mac?
  brew "container"
end
if OS.mac?
  cask "iterm2"
end
if OS.mac?
  mas "Xcode", id: 497799835
end
if OS.linux?
  flatpak "org.gnome.Calculator"
end

How It Would Work

The infrastructure for OS detection is already in place:

• Formulae: Formula#supports_linux? / Formula#supports_macos? check active_spec.depends_on_macos_set_top_level? and active_spec.depends_on_linux_set_top_level?
• Casks: Cask#supports_linux? checks depends_on declarations
• MAS: Always macOS-only by definition
• Flatpak: Always Linux-only by definition
• Skipper: Already uses this metadata at install time to skip incompatible entries

The --os-guards flag would thread through Dumper.build_brewfile → PackageType.dump_output → individual dump methods in Brew, Cask, and the Extension base class.

Why Opt-In?

Making it the default would change existing Brewfile output format for all users. An explicit flag lets users who maintain cross-platform dotfiles opt in, while leaving the current behaviour intact.

Notes

• Opened this issue as a feature request before submitting a PR to get maintainer feedback on the approach.
• This issue was explored with AI assistance (Claude Code / Anthropic), disclosed per the contributing guidelines.

[MikeMcQuaid]

brew bundle dump captures all installed formulae, casks, and extensions without any platform awareness. On a shared cross-platform dotfiles setup (macOS + Linux), running brew bundle install on a Linux machine will attempt — and fail — to install macOS-only formulae like container (which declares depends_on :macos in its formula), casks (which are macOS-only by nature), and mas entries (Mac App Store, macOS-only).

This is not correct. We have skip logic for both platform-specific extensions like mas and for individual formulae/casks.

If individual formulae or casks are not correctly detected: file an issue (by hand, not with AI) in homebrew/core or homebrew/cask to note this.

• This issue was explored with AI assistance (Claude Code / Anthropic), disclosed per the contributing guidelines.

Don't do this again. Always open issues using our issue template.

[levontumanyan]

@MikeMcQuaid what i meant is that brew bundle dump does not populate the dumped list of stuff with OS guards!

[levontumanyan]

I opened it with AI's help but i spent at least an hour researching on this. Sorry i skipped the template, i didn't know about it, but opening with AI is just one way of doing it doesn't mean it's necessarily slop.

[MikeMcQuaid]

MikeMcQuaid what i meant is that brew bundle dump does not populate the dumped list of stuff with OS guards!

Yes. We shouldn't do that.

I opened it with AI's help but i spent at least an hour researching on this. Sorry i skipped the template, i didn't know about it, but opening with AI is just one way of doing it doesn't mean it's necessarily slop.

Did you research it or did the AI? Given the inaccuracies here it's not clear.

I didn't say it was slop. Not following the issue template here is a waste of our time though as we specifically ask you to do that. Please don't do it this way next time, thanks.