Brunch Gem: Isolated Development Environments for Git Branches and Worktrees

Git branches change the code instantly, but they do not change the development environment. This can lead to discrepancies between the code and its runtime state. A tool called Brunch aims to address this issue by creating isolated development environments for each Git branch and worktree.

In 2018, the author wanted each Git feature branch to have its own database for a Rails application. However, they struggled to detect when branches were created, deleted, or switched. After abandoning the idea for eight years, Brunch emerged as a solution.

Brunch runs isolated development environments for Git branches and worktrees. Users can create multiple worktrees, each representing a different branch. For instance, worktrees for "main," "feature/login," and "feature/payments" can all be checked out simultaneously. Each worktree requires its own development environment, such as a separate Docker Compose project, containers, network, and named volumes.

To switch between environments, users can use Git commands like "git switch." When Brunch detects a branch switch, it stops the current environment and starts the new one associated with the selected branch. This ensures each branch has its own runtime state, including databases, containers, and persistent volumes.

Brunch supports Docker Compose, allowing each branch to have its own Compose project. For example, if the user is on the "main" branch, its environment runs while other branches are stopped. Switching to "feature/login" stops the "main" environment and starts the "feature/login" environment. Brunch maintains the previous environment's persistent volumes, enabling seamless transitions between branches.

The concept of worktrees becomes more interesting with Brunch. With multiple worktrees, each branch can run independently, even if they share the same host port. For example, worktree 1 can run "main" on localhost:3000, worktree 2 can run "feature/search" on localhost:3001, and worktree 3 can run "feature/payments" on localhost:3002. By separating the environment and host port, Brunch allows multiple branches to coexist without conflicts.

This isolation becomes crucial when using coding agents or IDEs for parallel development. Each task can have its own worktree, database, containers, and ports, ensuring proper isolation and preventing conflicts. Brunch takes care of assigning ports to worktrees, enabling multiple tasks to run simultaneously without interfering with each other.

In summary, Brunch simplifies the process of maintaining isolated development environments for Git branches and worktrees. It ensures that the development environment follows Git branches, allowing developers to switch between branches and instantly have their runtime state updated accordingly.