Skip to content

feat(skills): let clean-branches-and-worktrees delete build directories from the worktrees it keeps - #4258

Merged
bbondy merged 1 commit into
mainfrom
prune-build-dirs
Nov 16, 2026
Merged

bbondy merged 1 commit into
mainfrom
prune-build-dirs

Conversation

@chrislacy

Copy link
Copy Markdown
Collaborator

A follow up to PR 4046: feat(skills): add a skill that cleans merged branches and worktrees.

User impact: none -- a contributor skill and its selftest; bravebot itself is unchanged.

The problem

People run the clean-branches-and-worktrees skill to reclaim disk space, but it only frees the space of worktrees it removes. A worktree it keeps, because its branch is unmerged, has commits past the merged head, or is dirty, still holds gigabytes of target/ and node_modules. On a working clone of this repository, the kept worktrees held 32.8 GiB of build output that the skill had no way to delete.

Reproduce

  1. In a direct clone of brave/bravebot with gh signed in, have at least one linked worktree under .worktrees/ whose branch is not merged and that has been built (target/ or a node_modules directory present).
  2. From the main checkout, run python3 agents/skills/clean-branches-and-worktrees/clean-branches-and-worktrees.py --dry-run --prune-build-dirs.

Observed before this change: the script has no --prune-build-dirs option, and kept worktrees keep their build output.
Expected: the dry run lists each ignored target, node_modules and dist directory in kept linked worktrees with its size and deletes nothing. The same command without --dry-run deletes them.

Real run on a working clone of this repository (branch skip list trimmed):

Deleted 2 branch(es).
...
Removed 2 linked worktree(s).
...
Deleted 11 build directories in kept worktrees, 32.8 GiB.
Build directories:
- /Users/.../bravebot/.worktrees/add-client-attach-and-takeover/docs/website/node_modules (367.1 MiB)
- /Users/.../bravebot/.worktrees/add-client-attach-and-takeover/target (8.9 GiB)
- /Users/.../bravebot/.worktrees/bound-retained-view-bytes/target (9.5 GiB)
- /Users/.../bravebot/.worktrees/test-u1-mcp-and-bridge-descriptors/target (13.2 GiB)
...
Build directories kept:
- /Users/.../bravebot/.worktrees/prune-build-dirs: the checkout this runs from

It matched the preceding dry run. Free space on the volume went from 22 GiB to 59 GiB. Afterwards the three worktrees had no target, node_modules or dist directory, git status --porcelain was empty in each, and their other ignored files (__pycache__/, docs/website/build/, .docusaurus/) were still present. The main checkout's target/ and node_modules were untouched.

The fix

A new --prune-build-dirs option runs after the branch cleanup. For each linked worktree still in place, merged or not, it asks Git for wholly ignored directories (git ls-files --others --ignored --exclude-standard --directory) and deletes those named target, node_modules or dist. Git lists a directory that holds a tracked file, or a symlink, differently, so neither is deleted. Other ignored files, such as a local .env, are never deleted. The main checkout, the checkout the script runs from, and locked worktrees are skipped and reported. The dry run reports each directory and its size. The skill tells the agent to warn the person that the next build in those worktrees starts from nothing and that a build running in one of them will fail.

Test plan

  • python3 agents/skills/clean-branches-and-worktrees/selftest.py - passed, 26 tests
  • make check-clean-branches-selftest - passed
  • python3 contrib/check-all-selftest.py - passed
  • Dry run, then real run with --prune-build-dirs, on a working clone of this repository - 11 build directories (32.8 GiB) deleted, matching the dry run
  • CI passes cleanly
Which regressions the tests reject

Each test drives the script against real Git repositories with a fake gh on PATH. Each guard below was removed from the script in turn, and the named test was observed failing:

  • Without the name filter, test_keeps_ignored_files_that_are_not_build_directories fails: an ignored cache/ directory is deleted.
  • Without skipping the main checkout, test_keeps_build_directories_of_the_main_checkout_and_the_running_worktree fails.
  • Without skipping the checkout the script runs from, the same test fails.
  • Without skipping worktrees the run removes, test_does_not_count_build_directories_of_a_worktree_it_removes fails: the dry run counts directories in a worktree it is about to remove.
  • Without the locked check, test_keeps_build_directories_of_a_locked_worktree fails.
  • Without the dry-run guard, test_dry_run_reports_build_directories_and_deletes_none fails.
  • With pruning always on, test_keeps_build_directories_without_the_flag fails.

test_keeps_a_build_directory_that_holds_a_tracked_file and test_keeps_what_a_build_directory_symlink_points_to pin behaviour that comes from how Git lists these entries. No guard in the script can be removed to make them fail. The other new tests cover a dirty kept worktree with a nested node_modules and a detached worktree.

Not tested: Windows, and a deletion that fails partway (the script reports the path and continues, but no test forces the failure).

User facing changes

None for people using bravebot. Contributors can pass --prune-build-dirs to the clean-branches-and-worktrees skill to reclaim disk space from the worktrees it keeps.

…es from the worktrees it keeps

A worktree kept for unmerged or uncommitted work still holds gigabytes of target/ and node_modules, so a cleanup run could recover little space. --prune-build-dirs deletes ignored target, node_modules and dist directories that hold no tracked file from each linked worktree left in place, except the main checkout, the running checkout and locked worktrees. Other ignored files, such as .env, are kept.
@chrislacy
chrislacy marked this pull request as ready for review November 16, 2026 01:54
@bbondy
bbondy added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 8b13bb5 Nov 16, 2026
30 checks passed
@bbondy
bbondy deleted the prune-build-dirs branch November 16, 2026 02:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants