docs/Brew-Bundle-and-Brewfile: improve docs.

The `brew bundle` documentation isn't great at explaining what the tool is and why you should care. Let's improve that.
2025-07-14 16:09:03 +08:00 · 2025-04-25 10:59:32 +01:00 · 2025-04-25 10:59:32 +01:00 · 5f29ab8c89
commit 5f29ab8c89
parent 04e77dd43d
3 changed files with 286 additions and 48 deletions
--- a/Library/.rubocop.yml
+++ b/Library/.rubocop.yml
@ -417,12 +417,10 @@ Style/MutableConstant:
 Style/NumericLiteralPrefix:
  EnforcedOctalStyle: zero_only

-# Only use this for numbers >= `1_000_000`.
+# Only require this for numbers >= `10_000_000_000`.
 Style/NumericLiterals:
-  MinDigits: 7
+  MinDigits: 11
  Strict: true
-  Exclude:
-    - "**/Brewfile"

 Style/OpenStructUse:
  Exclude:
--- a/docs/Brew-Bundle-and-Brewfile.md
+++ b/docs/Brew-Bundle-and-Brewfile.md
@ -2,71 +2,307 @@
 last_review_date: "2025-03-19"
 ---

-# `brew bundle` and `Brewfile`
+# Homebrew Bundle, `brew bundle` and `Brewfile`

-Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store and Visual Studio Code (and forks/variants).
+Homebrew Bundle is run with the `brew bundle` command.

-## Requirements
+It uses `Brewfile`s to provide a declarative interface for installing/upgrading packages with Homebrew and starting services with `brew services`.

-[Homebrew Cask](https://github.com/Homebrew/homebrew-cask) is optional and used for installing Mac applications.
+Rather than specifying the `brew` commands you wish to run, you can specify the state you wish to reach.

-[`mas`](https://github.com/mas-cli/mas) is optional and used for installing Mac App Store applications.
+See also the [`brew bundle` section of `man brew`](https://docs.brew.sh/Manpage#bundle-subcommand) or `brew bundle --help`.

-[Visual Studio Code](https://code.visualstudio.com/) (or a fork/variant) is optional and used for installing Visual Studio Code extensions.
+## Basic Usage

-## Usage
+### `brew bundle`

-See [`brew bundle` section of `man brew`](https://docs.brew.sh/Manpage#bundle-subcommand) or `brew bundle --help`.
-
-An example `Brewfile`:
+A simple `Brewfile` might contain a formula:

 ```ruby
-# 'brew tap'
-tap "homebrew/cask"
-# 'brew tap' with custom Git URL
-tap "user/tap-repo", "https://user@bitbucket.org/user/homebrew-tap-repo.git"
-# 'brew tap' with arguments
-tap "user/tap-repo", "https://user@bitbucket.org/user/homebrew-tap-repo.git", force_auto_update: true
+brew "ruby"
+```

-# set arguments for all 'brew install --cask' commands
+When you run `brew bundle install` (or: just `brew bundle` for short), this will run `brew install ruby` to install Ruby if needed.
+
+```console
+$ brew bundle
+Installing ruby
+`brew bundle` complete! 1 Brewfile dependency now installed.
+```
+
+If it's outdated, this will run `brew upgrade ruby`.
+If it's already installed, this will be a no-op.
+
+```console
+$ brew bundle install
+Using ruby
+`brew bundle` complete! 1 Brewfile dependency now installed.
+```
+
+### `brew bundle check`
+
+You can check if a `brew bundle install` will do anything by running:
+
+```console
+$ brew bundle check
+The Brewfile's dependencies are satisfied.
+```
+
+You can use this behaviour in scripts like so:
+
+```bash
+brew bundle check || brew bundle install
+```
+
+### Types
+
+As well as supporting formulae (`brew "..."`), you can also use `brew bundle` with casks, taps, Mac App Store apps, VSCode extensions and to start background services with `brew services`.
+
+```ruby
+tap "apple/apple"
+brew "apple/apple/game-porting-toolkit"
+brew "postgresql@16", restart_service: true
+cask "firefox"
+mas "Refined GitHub", id: 1519867270
+vscode "editorconfig.editorconfig"
+```
+
+Run `brew bundle` again and this outputs:
+
+```console
+$ brew bundle
+Using apple/apple
+Using apple/apple/game-porting-toolkit
+Using postgresql@16
+Using firefox
+Using Refined GitHub
+Using editorconfig.editorconfig
+`brew bundle` complete! 6 Brewfile dependencies now installed.
+```
+
+### Projects
+
+Adding a `Brewfile` to a project's repository (like you might a `package.json`, `Gemfile` or `requirements.txt`) is a nicer way of encoding project dependencies.
+
+It allows you to tell users to run a single command to install all dependencies for a project and start any services.
+
+As Homebrew supports both macOS, Linux and WSL: you can have this single command setup project dependencies on three operating systems and in continuous integration services like GitHub Actions (where it's installed by default on macOS and easily on Linux with [`Homebrew/actions/setup-homebrew`](https://github.com/Homebrew/actions/tree/master/setup-homebrew)).
+
+### `brew bundle dump`
+
+`Brewfile`s can also be used as a way of saving all supported packages into a single file.
+
+You can do this with `brew bundle dump --global --force` to write to e.g. `~/.Brewfile` (check `man brew` for the exact path used in your configuration):
+
+```console
+brew bundle dump --global --force
+```
+
+If you also pass `--describe`, you can also get the `Brewfile` to contain descriptions of each of the packages:
+
+```console
+brew bundle dump --global --force --describe
+```
+
+might add something like the following:
+
+```ruby
+# Powerful, clean, object-oriented scripting language
+brew "ruby"
+```
+
+You can then reinstall (and, by default, upgrade) all of these with:
+
+```console
+brew bundle --global
+````
+
+## Advanced Usage
+
+### `brew bundle cleanup`
+
+If you've used `brew bundle dump` to store all the software you use, you can quickly cleanup anything else with:
+
+```console
+$ brew bundle cleanup --global --force
+Uninstalling gcc... (1,914 files, 459.8MB)
+Uninstalled 1 formula
+```
+
+### `brew bundle list`
+
+If you want to get a list of all the formulae in your `Brewfile`, you can use:
+
+```console
+$ brew bundle list
+apple/apple/game-porting-toolkit
+postgresql@16
+```
+
+You can get other types with e.g.:
+
+```console
+$ brew bundle list --cask
+firefox
+```
+
+### `brew bundle edit`
+
+To open your `Brewfile` in your text editor, run:
+
+```console
+$ brew bundle edit
+Editing /some/project/Brewfile
+```
+
+### `brew bundle add` and `brew bundle remove`
+
+You can add and remove entries to your `Brewfile` by running `brew bundle add` or `brew bundle remove`:
+
+```console
+brew bundle add wget
+brew bundle remove wget
+```
+
+### `brew bundle exec`
+
+`brew bundle exec` allows you to run a command in an environment customised by your `Brewfile`.
+
+For example, with a `Brewfile` like:
+
+```ruby
+brew "node"
+```
+
+This will ensure you are always running the correct `node`:
+
+```console
+$ brew bundle exec which node
+/opt/homebrew/opt/node/bin/node
+```
+
+This can be particularly useful when building software that depends on other software in your `Brewfile`.
+`brew bundle exec` will ensure that all the necessary paths are setup to find everything in your `Brewfile`, linked or unlinked, keg-only or not.
+This avoids dealing with issues around individual user or machine `PATH` configuration.
+
+If you want to avoid explicitly having to run `brew bundle check` or `brew bundle install` before `brew bundle exec`, you can use:
+
+```console
+brew bundle exec --check
+brew bundle exec --install
+```
+
+If you want to start all the services in your `Brewfile` just during the execution of `brew bundle exec`, use:
+
+```console
+brew bundle exec --services
+```
+
+### `brew bundle sh`
+
+`brew bundle sh` is like `brew bundle exec` but it runs your interactive shell of choice, like `brew sh`:
+
+```console
+$ brew bundle sh
+brew bundle $ which node
+/opt/homebrew/opt/node/bin/node
+```
+
+It's got the same backbone as `brew bundle exec` so the same arguments (e.g. `--check`, `--install`, `--services`) apply.
+
+### `brew bundle env`
+
+`brew bundle env` dumps out all the environment variables in a form suitable for adding to a shell.
+
+```console
+$ brew bundle env | grep node
+export PATH="/opt/homebrew/opt/node/bin:${PATH:-}"
+```
+
+You can use this with `eval` to turn your current shell environment into a `brew bundle exec` or `brew bundle sh` one:
+
+```console
+$ eval "$(brew bundle env)"
+$ echo "${PATH}" | grep node
+/opt/homebrew/opt/node/bin:/opt/homebrew/bin:/usr/bin:/bin
+```
+
+It's also got the same backbone as `brew bundle exec` so the same arguments (e.g. `--check`, `--install`) apply.
+
+### `brew bundle upgrade` and `HOMEBREW_BUNDLE_NO_UPGRADE=1`
+
+By default, `brew bundle` will attempt to upgrade all software.
+You can disable this behaviour by passing `--no-upgrade` or with `export HOMEBREW_BUNDLE_NO_UPGRADE=1` in your environment.
+
+If you do this, you can upgrade everything with:
+
+```console
+brew bundle upgrade
+```
+
+or selective formulae with e.g.:
+
+```console
+brew bundle --upgrade-formulae ruby
+```
+
+## Advanced Brewfiles
+
+`Brewfile`s support many other small bits of functionality.
+
+`Brewfile`s are evaluated as Ruby so you can use Ruby logic in them.
+
+Note that some logic may result in different output or behaviour per-machine, though.
+
+Rather than all `Brewfile` functionality one-by-one: here's a commented example of some useful cases:
+
+```ruby
+# Run `brew tap` with a custom URL
+tap "user/tap-repo", "https://user@bitbucket.org/user/homebrew-tap-repo.git"
+
+# Set arguments passed to all `brew install --cask` commands for `cask "..."`
+# In this example, pass `--appdir=~/Applications` and `--require_sha`
 cask_args appdir: "~/Applications", require_sha: true

-# 'brew install'
-brew "imagemagick"
-# 'brew install --with-rmtp', 'brew link --overwrite', 'brew services restart' even if no install/upgrade
+# Pass options to non-Homebrew/core formulae e.g. `brew install denji/nginx/nginx-full --with-rmtp`
+# This also runs `brew link --overwrite nginx-full` and `brew services restart nginx-full` afterwards.
 brew "denji/nginx/nginx-full", link: :overwrite, args: ["with-rmtp"], restart_service: :always
-# 'brew install', always 'brew services restart', 'brew link', 'brew unlink mysql' (if it is installed)
+
+# Runs `brew install mysql@5.6`, `brew services restart mysql@5.6` only if it was was installed or upgraded,
+# `brew link mysql@5.6` and `brew unlink mysql` (if `mysql` is installed)
 brew "mysql@5.6", restart_service: :changed, link: true, conflicts_with: ["mysql"]
-# 'brew install' and run a command if installer or upgraded.
+
+# Runs `brew install postgresql@16` and then runs a postinstall command if `postgresql@16` was installed or upgraded.
 brew "postgresql@16",
     postinstall: "${HOMEBREW_PREFIX}/opt/postgresql@16/bin/postgres -D ${HOMEBREW_PREFIX}/var/postgresql@16"
-# 'brew install' and write the installed version to the '.ruby-version' file.
+
+# Runs `brew install ruby` and, afterwards, writes the installed version to the '.ruby-version` file.
 brew "ruby", version_file: ".ruby-version"
-# install only on specified OS
+
+# Runs `brew install gnupg` or `brew install glibc` only on the specified OS.
+# Note: `brew bundle list` will not output `gnupg` on Linux or `glibc` on macOS` in this case:
+# the Ruby logic means they are "hidden" on other platforms.
 brew "gnupg" if OS.mac?
 brew "glibc" if OS.linux?

-# 'brew install --cask'
-cask "google-chrome"
-# 'brew install --cask --appdir=~/my-apps/Applications'
+# Runs `brew install --cask --appdir=~/my-apps/Applications`
 cask "firefox", args: { appdir: "~/my-apps/Applications" }
-# bypass Gatekeeper protections (NOT RECOMMENDED)
-cask "firefox", args: { no_quarantine: true }
-# always upgrade auto-updated or unversioned cask to latest version even if already installed
+
+# Runs `brew upgrade opera` to upgrade an auto-updated or unversioned Opera cask
+# to the latest version even if already installed.
+# This is used to force an upgrade in software that would typically update itself.
 cask "opera", greedy: true
-# 'brew install --cask' only if '/usr/libexec/java_home --failfast' fails
+
+# Runs `brew install --cask java` only if '/usr/libexec/java_home --failfast` fails (i.e there is no Java)
+# Note: `brew bundle list` will not output `java` if this `system` command succeeds and
+# this `system` command will be run even on `brew bundle check`, not just `brew bundle install`.
 cask "java" unless system "/usr/libexec/java_home", "--failfast"
-# 'brew install --cask' and run a command if installer or upgraded.
+
+# Runs `brew install --cask` and runs the command if the Google Cloud cask was installed or upgraded.
 cask "google-cloud-sdk", postinstall: "${HOMEBREW_PREFIX}/bin/gcloud components update"

-# 'mas install'
-mas "1Password", id: 443_987_910
-
-# 'code --install-extension' or equivalent command for a VS Code fork/variant
-vscode "GitHub.codespaces"
-
-# Set an environment variable to be used e.g. inside `brew bundle exec`
-# Mostly only `HOMEBREW_*` variables are passed through to other `brew` commands.
+# Sets an environment variable to be used e.g. inside `brew bundle exec` or `system` commands in the `Brewfile`.
+# Note: HOMEBREW_PREFIX/bin is _not_ in the `PATH` by default so you can set it this way.
 ENV["SOME_ENV_VAR"] = "some_value"
 ```

@ -74,16 +310,20 @@ ENV["SOME_ENV_VAR"] = "some_value"

 Homebrew is a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) package manager so it does not support installing arbitrary older versions of software.

-## New Installers/Checkers/Dumpers
+`brew bundle` does not have a concept of a "`Brewfile` lock file" that can be used to pin versions like e.g. `package-lock.json` or `Gemfile.lock`.
+
+This must be done with solutions outside or built on top of `brew bundle` instead.
+
+## Adding New Packages Support

 `brew bundle` currently supports Homebrew, Homebrew Cask, Mac App Store and Visual Studio Code (and forks/variants).

-We are interested in contributions for other installers/checkers/dumpers but they must:
+We are interested in contributions for other packages' installers/checkers/dumpers but they must:

 - be able to install software without user interaction
 - be able to check if software is installed
 - be able to dump the installed software to a format that can be stored in a `Brewfile`
- not require `sudo` to install
+- not require `sudo` to install (casks are an exception here)
 - be extremely widely used

 Note: based on these criteria, we would not accept e.g. Whalebrew today.
--- a/docs/index.md
+++ b/docs/index.md
@ -15,7 +15,7 @@ last_review_date: "2025-02-08"
 - [Common Issues](Common-Issues.md)
 - [`brew` Shell Completion](Shell-Completion.md)
 - [Homebrew on Linux](Homebrew-on-Linux.md)
- [`brew bundle` and `Brewfile`](Brew-Bundle-and-Brewfile.md)
+- [Homebrew Bundle, `brew bundle` and `Brewfile`](Brew-Bundle-and-Brewfile.md)

 - [Bottles (binary packages)](Bottles.md)
 - [Taps (third-party repositories)](Taps.md)