diff --git a/AGENTS.md b/AGENTS.md index bd03391c95b72..6d85aa9ba894a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,8 +38,13 @@ 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 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. ## 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