Skip to content

[build] document Bazel worktree output-base cleanup #17689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
titusfortner merged 1 commit into from
Jul 13, 2026
Merged

[build] document Bazel worktree output-base cleanup #17689

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Comment on lines +161 to +166

@qodo-code-review qodo-code-review Bot Jul 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

1. Unanchored output_base path 🐞 Bug ≡ Correctness

README recommends startup --output_base=.local/bazel-out, which is a relative path and can resolve
differently depending on where Bazel is invoked from (e.g., from a subdirectory), creating multiple
output bases and breaking the stated “output base lives under root .local/” cleanup behavior. This
also means the output directory may not be covered by the repo’s .bazelignore entry (which only
ignores the root .local).
Agent Prompt 
## Issue description
`README.md` documents `startup --output_base=.local/bazel-out` for per-worktree cleanup. Because it’s a relative path, it may not consistently point at the workspace-root `.local/` directory, undermining the stated cleanup behavior and the repo’s `.bazelignore` assumptions.

## Issue Context
The repo already uses Bazel’s `%workspace%` expansion in `.bazelrc*` files, which provides a stable, workspace-root anchored path.

## Fix Focus Areas
- README.md[161-174]

## Proposed fix
Update the README snippet to use an anchored path, e.g.:

```
startup --output_base=%workspace%/.local/bazel-out
```

(Alternatively, explicitly state that Bazel must be invoked from the repo root for the relative path to work as intended, but the anchored form is more robust.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


`.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
Expand Down