From 97cd91942ce4129191981460e75dcb5efabd3f2a Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Mon, 13 Jul 2026 11:04:29 -0500 Subject: [PATCH] [build] document Bazel worktree output-base cleanup --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 9ea6e75102659..81eed2098cefb 100644 --- a/README.md +++ b/README.md @@ -154,6 +154,25 @@ dependencies (e.g. `http_archive` tarballs). Both directories grow unbounded ove periodically if disk space matters. Keep the cache on the same filesystem as your checkouts so Bazel can hardlink instead of copy. +Bazel also creates a separate **output base** (compiled outputs, analysis cache, and the Bazel +server) per checkout path. Unlike the caches above, it is **not** removed when you delete a worktree — +so frequently created and discarded worktrees leak gigabytes of stale output. + +On macOS/Linux, make a worktree self-cleaning by pointing its output base inside the worktree. Add +this to that worktree's `.bazelrc.local`: + +``` +startup --output_base=.local/bazel-out +``` + +`.local/` is gitignored and excluded in `.bazelignore`, so removing the worktree removes its output +base with it. The shared `--disk_cache`/`--repository_cache` above still keep downloads and action +outputs shared across worktrees. + +(Windows users should instead keep `startup --output_user_root=C:/tmp` in `.bazelrc.windows.local` as +described above, to avoid path-length limits — do not nest the output base deeper inside the repo on +Windows.) + ## Building Selenium is built using a common build tool called [Bazel](https://bazel.build/), to