aspect output-bases - Aspect Build

aspect output-bases lists every Bazel output base on the machine: whose it is, when it was last used, how much memory its Bazel server holds, and how much disk it takes. It changes nothing.

aspect output-bases                   # every base, grouped by state
aspect output-bases --sort=size       # largest first, with sizes
aspect output-bases --measure-sizes   # add per-base and shared-cache sizes
aspect output-bases --output=json     # scriptable output

$ aspect output-bases
INFO: Bazel output user root: ~/Library/Caches/bazel/_bazel_me
  scanning Bazel output bases…
  5 Bazel output bases: 2 live, 1 idle, 1 orphaned, 1 undetermined
    orphaned: the base's workspace directory no longer exists, e.g. a deleted worktree.
      `aspect gc` removes one 1h after last use (--orphan-grace-hours=N to change, 0 for immediately).
    undetermined: nothing in the base names its workspace, so it cannot be orphaned.
      `aspect gc` removes one 30d after last use (--base-max-idle-days=N to change, 0 to keep), or now with `aspect gc <hash>`.
    1 Bazel server running, holding 1.2 GB of memory.

  live — workspace still exists (2):
    last used  bazel server  output base                       repository  branch     workspace
       4m ago        1.2 GB  78693e1e0ae2e0c93e73fdbc67634023  acme/web    fix/login  ~/src/web/.claude/worktrees/fix-login
       2d ago                7be04d4157db78a08f3eefb89b8bc53b  acme/web    main       ~/src/web

  idle — unused past the maximum idle time (1):
    last used  output base                       repository  branch  workspace
      45d ago  557089df67d989f705a1cf9794dcb086  acme/api    main    ~/src/api

  orphaned — workspace gone (1):
    last used  output base                       workspace
       2d ago  7f18ea0edb2474de1526d9aa847f0ab9  ~/src/web/.claude/worktrees/feat-search

  undetermined — no workspace recorded in it (1):
    last used  output base                       workspace
       3d ago  d41d8cd98f00b204e9800998ecf8427e  (Bazel run outside any workspace)

  Run `aspect gc --dry-run` to preview removing the 2 removable Bazel output bases — idle, orphaned; `aspect gc` to remove them.
  Add --measure-sizes to see how much disk each base holds (walks every base; can take a minute).

It ends with what to run next: aspect gc when anything is removable, --measure-sizes when sizes were not measured.

States

Each base has a lifecycle state, and the listing groups bases by it. aspect gc removes bases by the same states; the periods below are its defaults.

State	`state` in JSON	Meaning	Removed by `aspect gc`
live	`live`	Its workspace exists, and it was used within the maximum idle time or a Bazel server is still running in it.	—
idle	`idle`	Unused past the maximum idle time (30 days).	✓
orphaned	`orphan`	Its workspace directory no longer exists, e.g. a deleted worktree.	✓ after the grace period (1 hour)
orphaned within the grace period	`grace`	Orphaned, but used within the last hour.	—
in a worktree pool	`pooled`	An `aspect worktree` slot, kept so its next lease starts warm. A free slot has no worktree on purpose, so it is not treated as orphaned — unless its directory is gone and its pool has no record of it.	✓ once idle, when it is listed as idle
undetermined	`unknown`	Nothing in the base records its workspace.	✓ once idle, when it is listed as idle
left from an interrupted gc	`trash`	A `.gc-trash-` directory an earlier `gc` could not finish removing.	✓

Columns

Column
last used	When a Bazel server last started or ran a command in the base.
size	Disk the base holds. Only with `--measure-sizes` or `--sort=size`.
bazel server	Resident memory of the base’s running Bazel server; blank when none is running.
output base	The base’s directory name, an md5 of its workspace path.
repository, branch	The git repository and branch the workspace is checked out on, read from `.git`. For a pool slot, the repository is the pool and the branch column says what the slot holds — `leased · fix/login · <agent>` or `free · last main`, with `· owner gone` after the branch when the owning clone is no longer at its path, plain `free` for a slot that has held nothing, and blank for a slot its pool has no record of — clipped to 40 columns.
workspace	The workspace path.

A column with no value for any base in a group is left out of that group.

Sorting

--sort orders the bases within each state:

`--sort`	Order
`last-used` (default)	Most recently used first.
`size`	Largest first. Measures sizes.
`workspace`, `repository`, `branch`	Alphabetical, blanks last.

Sizes

Sizes are opt-in: --measure-sizes takes a du of every base, which can take a minute on a machine with tens of gigabytes of them. It adds a size to each state’s count and each listed base, and a table of the Bazel caches shared between bases: the download cache, the repository contents cache and install bases.

$ aspect output-bases --sort=size
  …
  5 Bazel output bases, 7.9 GB: 2 live (4.6 GB), 1 idle (1.1 GB), 1 orphaned (2.2 GB), 1 undetermined (12 MB)
  …
  live — workspace still exists (2):
    last used    size  bazel server  output base                       repository  branch     workspace
       2d ago  2.8 GB                7be04d4157db78a08f3eefb89b8bc53b  acme/web    main       ~/src/web
       4m ago  1.8 GB        1.2 GB  78693e1e0ae2e0c93e73fdbc67634023  acme/web    fix/login  ~/src/web/.claude/worktrees/fix-login
  …

  Bazel shared caches:
    cache/repos/v1/content_addressable  3.9 GB   (pruned by `aspect gc` after 30d unused; --download-cache-max-idle-days=N to change, 0 to keep)
    cache/repos/v1/contents             2.1 GB   (collected by Bazel while a server sits idle)
    install                             706 MB   (collected by Bazel's --experimental_install_base_gc_max_age)

  Run `aspect gc --dry-run` to preview removing the 2 removable Bazel output bases (3.3 GB) — idle, orphaned; `aspect gc` to remove them.

JSON

--output=json writes one document to stdout. Its top-level keys are schema_version, sort, policy, counts, servers (running and rss_kb), output_bases, and, with sizes measured, kb and caches (download_cache_kb, repo_contents_cache_kb and install_bases_kb). output_bases is ordered by state, and each entry carries its state (the values in the table above), path, workspace, last_used_ms, and, when known, repository, branch, pid, server_rss_kb and kb. counts and kb key the states as live, idle, orphaned, orphaned_within_grace, pooled, undetermined and trash.

Flags

Flag	Default
`--sort`	`last-used`	`last-used`, `size`, `workspace`, `repository` or `branch`.
`--measure-sizes`	`false`	Measure every base and the shared caches.
`--output-user-root`	rc, then platform default	The output user root to list.
`--output`	`text`	`text` or `json`.

​States

​Columns

​Sorting

​Sizes

​JSON

​Flags