From cb953467dee3ebf30c24984713c7fb1d43f05232 Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Thu, 18 Jun 2026 08:07:04 -0500 Subject: [PATCH 1/2] [build] document Bazel worktree output-base cleanup --- AGENTS.md | 8 ++++++-- README.md | 19 +++++++++++++++++++ 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bd03391c95b72..6ed27784f798a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,8 +38,12 @@ Shared/high-risk areas: - `bazel-*/` treat as generated output ### Agent workspace -The `.local/` directory (gitignored) is available for generated artifacts or temporary files: -- Use `--output_base=.local/bazel-out` if bazel output directory restricted +The `.local/` directory (gitignored) is available for generated artifacts or temporary files. +- When building in a git worktree, put Bazel's output base inside the worktree so it is reclaimed when + the worktree is removed: add `startup --output_base=.local/bazel-out` to the worktree's + `.bazelrc.local`, or pass `--output_base=.local/bazel-out`. By default Bazel keys the output base on + the checkout path and never deletes it when the worktree is removed, leaking several GB per discarded + worktree. See "Using Worktrees" in README.md for the shared cache setup. ## Cross-binding consistency checks When changing user-visible behavior, compare with at least one other binding: diff --git a/README.md b/README.md index 8bf3a2ae8dbee..869c7d624dd1e 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 From a9b4d831f56c8c0f90cf9be1bcc81cbd7929574f Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Thu, 18 Jun 2026 09:01:17 -0500 Subject: [PATCH 2/2] [build] clarify output_base is a startup option --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 6ed27784f798a..6d85aa9ba894a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,7 +41,8 @@ Shared/high-risk areas: The `.local/` directory (gitignored) is available for generated artifacts or temporary files. - When building in a git worktree, put Bazel's output base inside the worktree so it is reclaimed when the worktree is removed: add `startup --output_base=.local/bazel-out` to the worktree's - `.bazelrc.local`, or pass `--output_base=.local/bazel-out`. By default Bazel keys the output base on + `.bazelrc.local`, or pass it as a startup option before the command + (`bazel --output_base=.local/bazel-out build //...`). By default Bazel keys the output base on the checkout path and never deletes it when the worktree is removed, leaking several GB per discarded worktree. See "Using Worktrees" in README.md for the shared cache setup.