brunch 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f77dd24e00604eea2485dff005164094eb6f6e8633d81e96616df5bf25420ef2
-  data.tar.gz: 578505da516fbd81dfdd6c54e397ac0d4861e25e7af5b482a6e4f8fcf2aa4043
+  metadata.gz: 954abfa5f0f95a57eb872a2f140b0eed41d06ccbc7ff5ed5961e12ff73b371fd
+  data.tar.gz: 650c7a5a55c2557191e35cd94da369e6d89708623963e9c2721f04664c9ecbe7
 SHA512:
-  metadata.gz: c80c84a7078a91a71c69517d68d9b5093d13c6e97b8662e5ec98aecf2b2d2b07daaa49713da6046c51ca16c41c63cc58b50c2e6c286f1c5ede0ed0c3f2ce5ab2
-  data.tar.gz: 759c3e32ad7957cdec4b3babe27ad211262ce4f177b0ce6a2f4a0f9d3db26ed81ed332c930e2690e7cc3f9195f7528a5fa80b5ddf8cd4aa7063c32f9e0c18648
+  metadata.gz: 422d99f190dc07133f0517690a21ec2fda19f17a909b58437374bd49b982625cee2738f5fbe5ab6095898cadd758abdb83df4e21ea856f91270abe4cd16d42be
+  data.tar.gz: c328e3b0a2ba453afd8dd5beb073a221ca5d5b1ba33caafcf59ee1a5396591d5c5b374ef85999511c9b0b8dd558fe963289c2098f76aca42ed650e3ac8e43c61

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.8.2 - 2026-09-29
+
+- Resume stopped branch containers without rebuilding or replacing them when
+  switching back, preserving files in their writable layers.
+- Group `brunch ports` by worktree and show stopped branch environments in gray.
+
+## 0.8.1 - 2026-09-29
+
+- Reorganize the README into a step-by-step guide for branches, parallel
+  worktrees, managers, and everyday commands.
+
 ## 0.8.0 - 2026-09-29
 
 - Use one worktree-based lifecycle for both branch switches and parallel

data/README.md

@@ -2,51 +2,46 @@
 
 ![Brunch — container per branch and worktree](brunch.webp)
 
-Brunch runs isolated development environments for Git worktrees. The main
-checkout is a worktree too: switching branches there reuses its port, while
-additional worktrees run in parallel on different host ports. Docker Compose
-is the default manager; Podman
-Compose, local processes, and project commands are also supported.
+Brunch runs isolated development environments for Git branches and worktrees.
 
-Each branch environment has a distinct Compose project name, network, and
-named volumes. The active environment runs from its live worktree directory,
-including uncommitted changes when the manager rebuilds or reloads the app.
+Each branch gets its own environment. With Compose, that means a separate project, network, containers, and named volumes. Branches checked out in the same worktree share its host port, while additional worktrees get different ports and can run in parallel.
+
+Docker Compose is the default manager. Podman Compose, local processes, and custom project commands are also supported.
 
 ## Requirements
 
-- Ruby 3.1 or newer
-- Git 2.28 or newer
-- A supported environment manager: Docker Compose, Podman Compose, or project commands
-- [`git-hooks-ext`](https://github.com/ciembor/git-hooks-ext)
+- Ruby 3.1+
+- Git 2.28+
+- Docker Compose, Podman Compose, or another supported manager
+- [git-hooks-ext](https://github.com/ciembor/git-hooks-ext)
 
 ## Installation
 
-Install [`git-hooks-ext`](https://github.com/ciembor/git-hooks-ext) so that
-`ghe` is on your `PATH`, then install Brunch:
+Install [git-hooks-ext](https://github.com/ciembor/git-hooks-ext) so that `ghe` is available on your `PATH`, then install Brunch:
 
-```sh
+```bash
 gem install brunch
 ```
 
-Run `brunch install` inside each Git repository you want Brunch to manage.
-It installs the `git-hooks-ext` bridge and project-local hooks, and refuses
-to replace an existing hook owned by another tool.
+Inside each repository you want Brunch to manage:
+
+```bash
+brunch install
+```
+
+Brunch installs its hooks through `git-hooks-ext` and will not overwrite hooks owned by another tool.
 
-## Project configuration
+## Configuration
 
-Add `brunch.yml` to the project root. Docker Compose is the default, so the
-following remains sufficient for Compose projects:
+Add `brunch.yml` to the repository root.
+
+For Docker Compose:
 
 ```yaml
 compose_file: compose.yaml
 ```
 
-The referenced Compose file belongs to the application. Brunch does not impose
-a database or service stack: applications may define PostgreSQL, MySQL, Redis,
-Sidekiq, Elasticsearch, or any other services they need.
-Unknown `brunch.yml` fields are errors, so configuration typos are not ignored.
-
-Expose the application port with `BRUNCH_PORT`:
+Expose the application through `BRUNCH_PORT`:
 
 ```yaml
 services:
@@ -55,121 +50,141 @@ services:
       - "127.0.0.1:${BRUNCH_PORT}:3000"
 ```
 
-The first activated worktree prefers `127.0.0.1:3000`. Every worktree keeps
-its assigned host port while its branches take turns using it. Other worktrees
-receive a different free port; running containers can never bind the same host
-address and port. To prefer another starting port, set `preferred_port: 4000`.
-Brunch persists assignments privately in `.git/brunch/state.json`.
+The first activated worktree prefers port `3000`. Additional worktrees receive another free port.
 
-## Using Brunch
+To prefer a different starting port:
 
-First, commit `brunch.yml` and your Compose file (or the configuration for
-another manager). The repository needs at least one commit before Brunch can
-start an environment. Install the hooks once per repository, then activate
-the checked-out branch:
+```yaml
+preferred_port: 4000
+```
 
-```sh
+Port assignments are persisted per worktree in `.git/brunch/state.json`.
+
+## Getting started
+
+Commit `brunch.yml` and the application configuration first. The repository must contain at least one commit.
+
+Then run:
+
+```bash
 brunch install
 brunch doctor
 brunch activate
 brunch status
+```
+
+`brunch activate` starts the environment for the currently checked-out branch.
+
+To print only the current worktree's port:
+
+```bash
 brunch port
 ```
 
-Open `http://127.0.0.1:3000` if port 3000 is free, or use the port printed by
-`brunch activate` / `brunch port`. Brunch starts the application in the
-background. With Compose, the app must listen on the container port mapped in
-`compose.yaml`.
+Open the application on the printed port, for example:
 
-### Branches in one checkout
+```text
+http://127.0.0.1:3000
+```
+
+With Compose, the application must listen on the container port mapped in the Compose file.
+
+## Branch switching
 
-Once the hooks are installed, ordinary Git branch switches stop the old
-environment and start the new one automatically:
+Once the hooks are installed, normal Git branch switches automatically stop the previous branch environment and start the new one:
 
-```sh
+```bash
 git switch -c feature/login
-brunch status
 git switch main
 ```
 
-Both branches use this checkout's assigned host port. With Compose, they keep
-separate projects and volumes. To start the checked-out branch manually (for
-example, after `brunch stop`), run `brunch activate`. Run `brunch restart` to
-rebuild it after changing files that are copied into the image.
+Branches checked out in the same worktree reuse that worktree's host port.
 
-### Parallel worktrees
+With Compose, each branch keeps its own Compose project and named volumes, so persistent resources remain isolated between branches.
+Returning to a previously activated branch starts its stopped containers again,
+preserving files written inside them. The branch keeps the same host port.
 
-There is no mode switch. Commit the same `brunch.yml` in your repository, then
-create additional worktrees. Run `brunch install` again after upgrading Brunch
-to install its worktree hooks.
+To manually start the environment after `brunch stop`:
 
-```sh
+```bash
+brunch activate
+```
+
+To rebuild and recreate its containers explicitly:
+
+```bash
+brunch restart
+```
+
+`brunch restart` may discard data stored only in a container's writable layer.
+Put important data, such as databases, in named volumes.
+
+Compose builds use files from the live worktree, including uncommitted changes.
+
+If you want source edits to appear in an already running container without rebuilding, configure a bind mount or another reload mechanism in your Compose setup.
+
+## Parallel worktrees
+
+Additional worktrees run independently on different host ports.
+
+Create them with `git-hooks-ext`:
+
+```bash
 ghe worktree add -b feature-a ../feature-a
 ghe worktree add -b feature-b ../feature-b
+```
+
+Then:
+
+```bash
 cd ../feature-a
-brunch port        # port for this worktree
-brunch ports       # ports for all worktrees
-```
-
-Each worktree runs independently on a different host port, so `feature-a` and
-`feature-b` can be used at the same time. Run `brunch status` or `brunch port`
-inside each worktree to find its address. Switching branches inside one
-worktree does not stop the others.
-
-`ghe worktree add`, `move`, and `remove` emit lifecycle events. Git's
-`post-checkout` hook handles branch changes inside any worktree, including the
-main checkout. If you use plain `git worktree add`, run `brunch activate` in the
-new worktree; after a plain move or removal, run `brunch cleanup` from a
-remaining worktree.
-
-The source directory is never deleted by Brunch. It keeps a separate control
-copy under `.git/brunch/controls` so it can shut down Compose or run a custom
-`remove` command after a worktree has been removed. Switching branches within
-one worktree keeps the old branch's environment stopped, with its own named
-volumes. Removing the worktree removes all of its Brunch environments. The
-`local_process` manager also writes its log to the control directory, keeping
-the worktree clean. Custom `remove` commands that depend on project files must
-be committed, because the control copy is based on the worktree's last commit.
-
-Docker builds read uncommitted files from the live worktree. To see edits in
-an already running container without rebuilding, configure a source bind
-mount or another reload mechanism in the project's Compose file.
-`brunch restart` rebuilds the current environment.
-
-Before upgrading from an older branch-only configuration, stop its running
-environment and clean up its legacy state. Brunch refuses to reinterpret an
-old non-empty branch state as worktree state, preventing orphaned containers.
-
-### Custom manager commands
-
-Use the `command` manager when the project is started by another tool. Brunch
-runs commands from the live worktree with these variables: `BRUNCH_REF`,
-`BRUNCH_PORT`, `BRUNCH_PROJECT`, and `BRUNCH_SNAPSHOT`. The last variable points
-to the live worktree for compatibility with manager adapters.
 
-```yaml
-manager: command
-commands:
-  create: bin/environment create
-  start: bin/environment start
-  stop: bin/environment stop
-  remove: bin/environment remove
+brunch port
+brunch ports
+```
+
+`brunch port` prints the current worktree's port.
+
+`brunch ports` groups the current and previously activated branches under each
+worktree. Stopped branches appear in gray and retain their worktree's port for
+the next activation.
+
+Switching branches inside one worktree does not affect environments running in other worktrees.
+
+If you create a worktree with plain Git:
+
+```bash
+git worktree add -b feature-c ../feature-c
+```
+
+activate Brunch manually inside it:
+
+```bash
+cd ../feature-c
+brunch activate
 ```
 
-`create` provisions manager-owned resources; it is optional for the `command`
-manager. `start` must return after
-it has launched the environment (for example, by delegating to a daemon or
-supervisor). `stop` is used when switching branches; `remove` is used when
-a worktree is deleted and should remove any manager-owned persistent
-resources. This makes the adapter suitable for Podman, Kubernetes wrappers,
-Foreman/Overmind wrappers, or a project-specific script.
+After moving or removing worktrees with plain Git, run:
+
+```bash
+brunch cleanup
+```
 
-Optional `status`, `health`, and `logs` commands power the corresponding Brunch
-commands. A successful `health` command reports a healthy environment.
+Brunch never deletes the worktree source directory.
+
+## Managers
+
+### Docker Compose
+
+Docker Compose is the default manager:
+
+```yaml
+compose_file: compose.yaml
+```
 
 ### Podman Compose
 
-Podman Compose uses the same Compose file contract as Docker Compose:
+Podman Compose uses the same Compose file contract:
 
 ```yaml
 manager: podman_compose
@@ -178,66 +193,170 @@ compose_file: compose.yaml
 
 ### Local process
 
-Use `local_process` for a development command such as `bin/dev`.
-Brunch starts it in a dedicated process group, records its PID, stops that
-group on a branch switch, and saves its output under `.git/brunch/controls`.
+Use `local_process` for a development command such as `bin/dev`:
 
 ```yaml
 manager: local_process
 command: bin/dev
 ```
 
-## Lifecycle
+Brunch starts and stops the process together with the branch environment and stores its output under `.git/brunch/controls`.
 
-- A branch checkout stops the previous environment in that worktree, then
-  creates and starts the new one on the same port.
-- Each worktree keeps its own current environment and port. Other worktrees
-  continue running during branch switches.
-- Checking out a remote branch into a new local tracking branch works through
-  the same `post-checkout` hook.
-- `brunch cleanup` removes environments belonging to deleted worktrees.
+### Custom commands
 
-Git 2.39 cannot reliably report a normal `git branch -d` operation to a hook.
-Stopped branch environments remain until their worktree is removed.
+Use the `command` manager to integrate Brunch with project-specific tooling:
 
-## Operations
+```yaml
+manager: command
+commands:
+  create: bin/environment create
+  start: bin/environment start
+  stop: bin/environment stop
+  remove: bin/environment remove
+```
+
+Brunch runs these commands from the live worktree with:
+
+```text
+BRUNCH_REF
+BRUNCH_PORT
+BRUNCH_PROJECT
+BRUNCH_SNAPSHOT
+```
+
+`BRUNCH_SNAPSHOT` points to the live worktree for compatibility with manager adapters.
+
+`create` is optional.
+
+`start` must return after launching the environment.
+
+`stop` is called when switching away from the active branch.
+
+`remove` is called when the corresponding worktree environment is deleted and should remove manager-owned persistent resources.
+
+Optional commands:
+
+```yaml
+commands:
+  status: bin/environment status
+  health: bin/environment health
+  logs: bin/environment logs
+```
+
+These power the corresponding Brunch operations.
 
-```sh
-brunch status    # current worktree environment, manager status and port
-brunch ports     # worktree-to-port list; current worktree is marked in green
-brunch port      # only the current worktree's port, suitable for scripts
-brunch stop      # stop the active environment without deleting it
-brunch restart   # recreate and start the active environment
-brunch logs      # show the last 100 logs (or run commands.logs)
+## Worktree lifecycle
+
+A branch checkout stops the previous environment in that worktree and starts the new one on the same host port.
+
+Other worktrees continue running.
+
+Removing a worktree removes its Brunch environments. Brunch keeps the information needed to shut down manager resources under `.git/brunch/controls`, so cleanup can still run after the worktree itself is gone.
+
+If a custom `remove` command depends on project files, those files must be committed because cleanup after worktree removal uses the last committed state.
+
+`brunch cleanup` removes environments belonging to worktrees that no longer exist.
+
+Git does not expose every branch deletion workflow reliably to hooks, so stopped branch environments may remain until their worktree is removed.
+
+## Commands
+
+```bash
+brunch install
+```
+
+Install Brunch hooks for the repository.
+
+```bash
+brunch activate
+```
+
+Start the environment for the current branch.
+
+```bash
+brunch status
+```
+
+Show the current environment, manager status, and port.
+
+```bash
+brunch port
+```
+
+Print the current worktree's port.
+
+```bash
+brunch ports
+```
+
+List current and stopped branch environments grouped by worktree.
+
+```bash
+brunch stop
+```
+
+Stop the active environment without removing it.
+
+```bash
+brunch restart
+```
+
+Recreate and start the active environment.
+
+```bash
+brunch logs
 brunch logs --follow
-brunch run -- bin/rails console  # runs on the host in the live worktree, not in a container
-brunch doctor    # verify Git, installed hooks, configuration, manager and ports
-brunch cleanup   # delete environments for removed worktrees
 ```
 
-Brunch coordinates commands with locks under `.git/brunch`, writes `state.json`
-atomically, and retries interrupted environment setup on the next activation.
+Show environment logs.
+
+```bash
+brunch run -- bin/rails console
+```
+
+Run a command on the host from the live worktree.
+
+```bash
+brunch doctor
+```
+
+Check Git, installed hooks, configuration, manager availability, and ports.
+
+```bash
+brunch cleanup
+```
+
+Remove environments belonging to deleted worktrees.
+
+## Upgrading from older configurations
+
+Before upgrading from an older branch-only configuration, stop its running environment and clean up its legacy state.
+
+Brunch will not reinterpret an existing non-empty branch-only state as worktree state.
 
 ## Development
 
-```sh
+```bash
 bundle install
 bin/install-pre-commit
 bundle exec rake quality
 gem build brunch.gemspec
 ```
 
-Container E2E tests use real temporary Git repositories, Compose containers,
-and HTTP requests. Run them with Docker or Podman:
+Run container integration tests with Docker Compose:
 
-```sh
+```bash
 BRUNCH_INTEGRATION_MANAGER=docker_compose bundle exec rake test
+```
+
+Or Podman Compose:
+
+```bash
 BRUNCH_INTEGRATION_MANAGER=podman_compose bundle exec rake test
 ```
 
-CI runs both managers on pushes and pull requests. Without the environment
-variable, container tests are skipped by the local quality check.
+Without `BRUNCH_INTEGRATION_MANAGER`, container integration tests are skipped by the local quality check.
+
+The pre-commit hook runs RuboCop with automatic corrections, Reek, and the full test suite. SimpleCov requires 100% line and branch coverage for `lib/**/*.rb`.
 
-The pre-commit hook runs RuboCop with automatic corrections, Reek, and the full
-test suite. SimpleCov requires 100% line and branch coverage of `lib/**/*.rb`. When
-RuboCop changes a file, review and stage the correction before committing.
+If RuboCop modifies a file, review and stage the changes before committing.

data/lib/brunch/managers.rb

@@ -15,6 +15,8 @@ module Brunch
 
       def create(_entry) = true
 
+      def resume(entry) = start(entry)
+
       def environment(entry)
         {
           "BRUNCH_REF" => entry.fetch("ref", ""),
@@ -66,6 +68,7 @@ module Brunch
       end
 
       def start(entry) = compose(entry, "up", "--detach", "--build", "--remove-orphans")
+      def resume(entry) = compose(entry, "start")
 
       def status(entry)
         return "unavailable" unless available?

data/lib/brunch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brunch
-  VERSION = "0.8.0"
+  VERSION = "0.8.2"
 end

data/lib/brunch/worktree_mode.rb

@@ -100,11 +100,13 @@ module Brunch
         abort "#{config.fetch('manager')} is unavailable." unless manager.available?
 
         existing = nil
+        current_ref = nil
         with_state_lock do |data|
           record = data.fetch("worktrees", {})[id]
           existing = record&.fetch("environments", {})&.[](ref)
+          current_ref = record&.[]("current")
         end
-        return if existing && !force && existing["snapshot"] == path && existing["head"] == head && existing["status"] == "running"
+        return if existing && !force && existing["snapshot"] == path && existing["status"] == "running" && current_ref == ref
 
         previous = nil
         port = nil
@@ -120,6 +122,16 @@ module Brunch
             data.fetch("worktrees").fetch(id).fetch("environments").fetch(previous.fetch("ref"))["status"] = "stopped"
           end
         end
+        if existing && !force && existing["snapshot"] == path && existing["status"] != "starting"
+          with_state_lock { |data| data.fetch("worktrees").fetch(id)["current"] = ref }
+          abort "Could not resume environment for #{path}. Run brunch restart to rebuild it." unless worktree_manager(existing).resume(existing)
+
+          with_state_lock do |data|
+            data.fetch("worktrees").fetch(id).fetch("environments").fetch(ref)["status"] = "running"
+          end
+          puts "Resumed #{ref} in #{path} at http://127.0.0.1:#{existing.fetch('port')}"
+          return
+        end
         abort "Could not reset environment for #{path}." if existing && !worktree_manager(existing).reset(existing)
 
         project = "brunch-#{id[0, 12]}-#{Digest::SHA256.hexdigest(ref)[0, 12]}"
@@ -252,12 +264,22 @@ module Brunch
       data = state
       current_id = worktree_identity(repo_root)
       data.fetch("worktrees", {}).sort_by { |_id, record| record.fetch("path") }.each do |id, record|
-        entry = record.fetch("environments", {})[record["current"]]
-        next unless entry
+        environments = record.fetch("environments", {})
+        next if environments.empty?
 
-        marker = id == current_id ? color("●", 32) : "○"
-        name = id == current_id ? color(entry.fetch("ref"), 32) : entry.fetch("ref")
-        puts "#{marker} #{name}  #{record.fetch('port')}  #{record.fetch('path')}"
+        path = record.fetch("path")
+        puts(id == current_id ? color("● #{path}", 32) : "○ #{path}")
+        branches = environments.sort_by { |ref, _entry| [ref == record["current"] ? 0 : 1, ref] }
+        branches.each_with_index do |(ref, entry), index|
+          prefix = index == branches.length - 1 ? "  └─" : "  ├─"
+          running = ref == record["current"] && entry["status"] == "running"
+          unless running
+            puts color("#{prefix} ○ #{ref}  #{entry.fetch('port')}", 90)
+            next
+          end
+
+          puts "#{prefix} #{color("● #{ref}", 32)}  #{entry.fetch('port')}"
+        end
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brunch
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Maciej Ciemborowicz