Skip to content

Add a managed worktree build cache - #10

Merged
Kuret merged 3 commits into
mainfrom
rick/warm-worktree-cache
Aug 28, 2026
Merged

Add a managed worktree build cache#10
Kuret merged 3 commits into
mainfrom
rick/warm-worktree-cache

Conversation

@Kuret

@Kuret Kuret commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator

Problem

Werksfeer can reuse build artifacts from the visible main checkout, but that checkout is often stale, dirty, on another branch, or simply not compiled. New worktrees then fall back to dependency installation and compilation even when the remote default branch could have been prepared once and reused.

Solution

  • Add an isolated managed cache clone under the user's XDG cache directory.
  • Follow the repository's remote default branch without switching, fast-forwarding, or writing generated files into the visible main checkout.
  • Warm framework-appropriate dependencies/builds for Elixir, Rails, Python, and Node projects using the repository's Mise/asdf environment.
  • Build both dev and test artifacts for Elixir, including a separate dependency compilation step for native dependencies such as fast_html.
  • Retain Node dependencies when their committed inputs are unchanged.
  • Automatically refresh and prefer a compatible managed cache during worktree setup, with explicit repository, local, and environment opt-outs.
  • Copy mutable cache directories with copy-on-write support instead of symlinking them back to the managed source.
  • Isolate cache commands to the target ref's committed configuration plus main-checkout local overrides.
  • Keep one in-place cache per repository, record its last use, and automatically prune caches unused for 30 days.
  • Prevent concurrent warmers, recover stale locks, and add a guarded werksfeer cache clean command.
  • Keep database setup out of the build cache; PostgreSQL continues to use its separate seeded-template cache.

Compatibility

Existing worktree setup remains the fallback if automatic cache warming fails or no compatible cache exists. Automatic warming is enabled by default; repositories can set cache.auto_warm = false or WERKSFEER_CACHE_AUTO_WARM=false. Automatic pruning can likewise be adjusted or disabled with cache.retention_days or WERKSFEER_CACHE_RETENTION_DAYS.

Verification

  • bash -n for the executable, installer, and modules
  • ShellCheck for the executable, installer, and modules
  • 38 Bats integration tests
  • Real Detroit smoke test using Elixir 1.20/OTP 29: dev/test dependencies compiled successfully (including fast_html), dev/test application builds completed, and Node dependencies installed
  • A subsequent current-cache warm fetched the remote and exited as a no-op in about two seconds
  • Verified the managed checkout remained clean and the visible Detroit main checkout was not changed
  • Verified default-on warming, explicit opt-out, last-used tracking, automatic stale-cache pruning, and isolated XDG cache state in integration tests

The Detroit cache measured about 6.7 GB with both Mix environments and Node dependencies; the README documents this tradeoff and the cleanup command.

@Kuret
Kuret marked this pull request as ready for review August 28, 2026 08:33
@Kuret
Kuret merged commit e6506ba into main Aug 28, 2026
@Kuret
Kuret deleted the rick/warm-worktree-cache branch August 28, 2026 09:39
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.

1 participant