brunch 0.8.3 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e566d43380555cbea682f52dbbedc64bf1e4a95b681a7c60b266c98aedd5f28e
-  data.tar.gz: 212f72d4aa56f57d4ca878a9da515fbdb8730317f2e61ac8b55b33128f679b0c
+  metadata.gz: 668bcb5a607af2adcad5006541dc927be6e1c5277d4c79f57b46de725e96076b
+  data.tar.gz: c9a02342f703ce5546860760165f4e6b3226cbc6d686f1b5b12a3891e27ad85d
 SHA512:
-  metadata.gz: 5c3a334e07d02110511e678b252880bbf3c7ac8028377611c72d275d7018d89adeba270377f4a6f325c53783c34a674f23af5e374ccefc8b54e09ac07602ccb7
-  data.tar.gz: a5f2857d35bb150e3adc613eb731636b43a286ba74ec4e2afd29a3e75ca9c9433dda5e174fa092db8b179ec9840fcf7ecf3bfd198a6e9104eb0272e017e9eaa3
+  metadata.gz: d47e2a2fa7a68de063d05696eadaac3e4e41939d4e9faac87c875752c0a4e83542a13dfe9a0171b17590f7208825088de95875c87e156c10b91be2fed7a43393
+  data.tar.gz: 94449f91dbaa4bbcb70ab6aca393068f4e25e0e92797487195de86ffd05f5d2c50ab7f3f50b6fe2837938f1da6d5e6cbca03f34ffe3309e4789e411854c0fa5f

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.9.1 - 2026-10-03
+
+- Replace `brunch ports` with `brunch list` and add `brunch watch` for a
+  continuously refreshed interactive view of branch environments.
+
+## 0.9.0 - 2026-10-02
+
+- Remove environments for deleted local branches after the next Brunch command,
+  while preserving them across branch renames, including reftable renames that
+  do not emit a deletion event. Run `brunch install` again to install the new
+  `branch-deleted` hook.
+- Keep the same Compose project and named volumes when restarting after a branch rename.
+- Exercise the config-based git-hooks-ext bridge with Git 2.55 in CI.
+
+## 0.8.4 - 2026-10-01
+
+- Test against git-hooks-ext 0.6.0 in CI and clarify bridge upgrades and
+  worktree Git requirements.
+- Document a minimal Rails setup and update the Brunch artwork.
+
 ## 0.8.3 - 2026-09-29
 
 - Detect containers that exit immediately after a Compose resume and report the

data/README.md

@@ -1,6 +1,6 @@
 # Brunch
 
-![Brunch — container per branch and worktree](brunch.webp)
+![Brunch logo — container per worktree and branch](brunch.webp)
 
 Brunch runs isolated development environments for Git branches and worktrees.
 
@@ -11,9 +11,9 @@ Docker Compose is the default manager. Podman Compose, local processes, and cust
 ## Requirements
 
 - Ruby 3.1+
-- Git 2.28+
+- Git 2.28+ (2.39.3+ for `ghe worktree` lifecycle events)
 - Docker Compose, Podman Compose, or another supported manager
-- [git-hooks-ext](https://github.com/ciembor/git-hooks-ext)
+- [git-hooks-ext](https://github.com/ciembor/git-hooks-ext) 0.6.0+ for reliable branch deletion events
 
 ## Installation
 
@@ -29,7 +29,8 @@ Inside each repository you want Brunch to manage:
 brunch install
 ```
 
-Brunch installs its hooks through `git-hooks-ext` and will not overwrite hooks owned by another tool.
+Brunch installs the `git-hooks-ext` bridge and its own event hooks without overwriting hooks owned by another tool.
+After upgrading Brunch or `git-hooks-ext`, run `brunch install` again in each managed repository to refresh its hooks and bridge.
 
 ## Configuration
 
@@ -41,15 +42,50 @@ For Docker Compose:
 compose_file: compose.yaml
 ```
 
-Expose the application through `BRUNCH_PORT`:
+For a Rails app with SQLite databases in `storage/`, add `Dockerfile.dev`:
+
+```dockerfile
+FROM ruby:3.4-slim
+
+WORKDIR /rails
+
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y build-essential git libsqlite3-dev libvips libyaml-dev pkg-config && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY Gemfile Gemfile.lock ./
+RUN bundle install
+COPY . .
+```
+
+Use the Ruby version required by your application. Then add `compose.yaml`:
 
 ```yaml
 services:
   web:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    command: sh -c 'bin/rails db:prepare && exec bin/rails server -b 0.0.0.0 -p 3000'
+    environment:
+      RAILS_ENV: development
+    volumes:
+      - .:/rails
+      - storage:/rails/storage
     ports:
       - "127.0.0.1:${BRUNCH_PORT}:3000"
+
+volumes:
+  storage:
 ```
 
+The bind mount makes source edits visible to Rails. The named volume keeps the
+SQLite database separate for each branch and preserves it across container
+rebuilds. If your app stores its database elsewhere, mount that location instead.
+Brunch runs on the host, so it does not need to be in the Rails `Gemfile`.
+After changing `Gemfile` or `Gemfile.lock`, run `brunch restart` to rebuild the
+image with the new gems; the named volume remains intact.
+
 The first activated worktree prefers port `3000`. Additional worktrees receive another free port.
 
 To prefer a different starting port:
@@ -140,15 +176,22 @@ Then:
 cd ../feature-a
 
 brunch port
-brunch ports
+brunch list
 ```
 
 `brunch port` prints the current worktree's port.
 
-`brunch ports` groups the current and previously activated branches under each
+`brunch list` 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.
 
+```bash
+brunch watch
+```
+
+`brunch watch` shows the same view and refreshes it every second. Press
+`Ctrl-C` to stop watching.
+
 Switching branches inside one worktree does not affect environments running in other worktrees.
 
 If you create a worktree with plain Git:
@@ -257,7 +300,16 @@ If a custom `remove` command depends on project files, those files must be commi
 
 `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.
+With `git-hooks-ext` 0.6.0+, deleting a local branch queues its Brunch
+environments for removal. On the next regular Brunch command, such as
+`brunch status` or `brunch cleanup`, Brunch checks the current refs and removes
+the branch's managed resources, including Compose containers and volumes.
+It also checks for missing branches when Git emits no deletion event. This
+delay protects environments when `git branch -m` reports a deletion before
+creating the renamed branch. A renamed branch keeps its environment under the
+new name. If Git reflogs are unavailable and Brunch cannot distinguish a
+rename from a deletion, it keeps the environment. A later `brunch restart`
+recreates the container in the same Compose project, preserving named volumes.
 
 ## Commands
 
@@ -286,11 +338,17 @@ brunch port
 Print the current worktree's port.
 
 ```bash
-brunch ports
+brunch list
 ```
 
 List current and stopped branch environments grouped by worktree.
 
+```bash
+brunch watch
+```
+
+Continuously refresh the branch-environment list in an interactive terminal.
+
 ```bash
 brunch stop
 ```
@@ -326,7 +384,7 @@ Check Git, installed hooks, configuration, manager availability, and ports.
 brunch cleanup
 ```
 
-Remove environments belonging to deleted worktrees.
+Remove environments belonging to deleted worktrees and process pending branch deletions.
 
 ## Upgrading from older configurations
 

data/lib/brunch/cli.rb

@@ -23,7 +23,12 @@ module Brunch
       case arguments
       in ["install"] then Hooks.install
       in ["version"] | ["--version"] | ["-v"] then puts Brunch::VERSION
-      else return worktree_command(arguments)
+      else
+        unless arguments.first == "branch-deleted"
+          reconcile_deleted_branches
+          reconcile_missing_branches
+        end
+        return worktree_command(arguments)
       end
       0
     rescue ConfigurationError => e

data/lib/brunch/hooks.rb

@@ -5,7 +5,7 @@ require "open3"
 
 module Brunch
   module Hooks
-    EVENTS = %w[branch-created remote-branch-created remote-branch-updated post-checkout worktree-created
+    EVENTS = %w[branch-created branch-deleted remote-branch-created remote-branch-updated post-checkout worktree-created
                 worktree-removed worktree-moved worktree-pruned worktree-repaired].freeze
 
     module_function
@@ -26,6 +26,8 @@ module Brunch
         CLI.start(["activate"]) if arguments.fetch(2, "0") == "1"
       when "branch-created", "remote-branch-created", "remote-branch-updated"
         CLI.start(["register", arguments.fetch(0)])
+      when "branch-deleted"
+        CLI.start(["branch-deleted", arguments.fetch(0), arguments.fetch(2)])
       when "worktree-created", "worktree-removed", "worktree-moved", "worktree-pruned", "worktree-repaired"
         CLI.start(["worktree-event", event, *arguments])
       else

data/lib/brunch/version.rb

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

data/lib/brunch/worktree_mode.rb

@@ -20,15 +20,17 @@ module Brunch
         abort "Start the checked-out branch from its worktree." unless ref == worktree_ref(repo_root).first
         worktree_activate(repo_root)
       in ["stop"] then worktree_stop(repo_root)
+      in ["branch-deleted", ref, oid] then record_deleted_branch(ref, oid)
       in ["cleanup"] | ["register", _] then worktree_cleanup
       in ["status"] then worktree_status
-      in ["ports"] then worktree_ports
+      in ["list"] then worktree_ports
+      in ["watch"] then worktree_watch
       in ["port"] then worktree_port
       in ["logs", *arguments] then worktree_logs(arguments)
       in ["run", "--", *command] if !command.empty? then worktree_run(command)
       in ["doctor"] then worktree_doctor
       else
-        warn "Usage: brunch {activate|start <current-ref>|stop|restart|status|ports|port|logs [args]|run -- <cmd>|doctor|cleanup}"
+        warn "Usage: brunch {activate|start <current-ref>|stop|restart|status|list|watch|port|logs [args]|run -- <cmd>|doctor|cleanup}"
         return 64
       end
       0
@@ -140,8 +142,8 @@ module Brunch
         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]}"
-        control = File.join(state_root, "controls", project)
+        project = existing ? existing.fetch("project") : "brunch-#{id[0, 12]}-#{Digest::SHA256.hexdigest(ref)[0, 12]}"
+        control = existing ? existing.fetch("control") : File.join(state_root, "controls", project)
         archive_ref(head, control)
         compose_file = config.fetch("compose_file")
         if %w[docker_compose podman_compose].include?(config.fetch("manager"))
@@ -258,6 +260,110 @@ module Brunch
       end
     end
 
+    def record_deleted_branch(ref, oid)
+      with_state_lock do |data|
+        records = data.fetch("worktrees", {}).values
+        next unless records.any? { |record| record.fetch("environments", {}).key?(ref) }
+
+        (data["deleted_branches"] ||= {})[ref] = oid
+      end
+    end
+
+    def reconcile_deleted_branches
+      pending = state.fetch("deleted_branches", {})
+      return if pending.empty?
+
+      refs = local_branch_refs
+      pending.each do |ref, oid|
+        unless refs.include?("refs/heads/#{ref}")
+          renamed = renamed_branch(ref, oid, refs)
+          next if renamed == :unknown
+
+          renamed ? rename_branch_environments(ref, renamed) : remove_branch_environments(ref)
+        end
+        with_state_lock { |data| data.fetch("deleted_branches").delete(ref) }
+      end
+    end
+
+    def reconcile_missing_branches
+      data = state
+      names = data.fetch("worktrees", {}).values.flat_map { |record| record.fetch("environments", {}).keys }.uniq
+      names -= data.fetch("deleted_branches", {}).keys
+      names.reject! { |ref| ref.start_with?("detached-") }
+      return if names.empty?
+
+      refs = local_branch_refs
+      names.each do |ref|
+        next if refs.include?("refs/heads/#{ref}")
+
+        renamed = renamed_branch(ref, nil, refs)
+        next if renamed == :unknown
+
+        renamed ? rename_branch_environments(ref, renamed) : remove_branch_environments(ref)
+      end
+    end
+
+    def local_branch_refs
+      output, status = Open3.capture2("git", "for-each-ref", "--format=%(refname)", "refs/heads")
+      abort "Could not inspect local branches." unless status.success?
+
+      output.lines.map(&:strip)
+    end
+
+    def renamed_branch(old_ref, old_oid, refs)
+      missing_reflog = false
+      full_ref = refs.find do |new_ref|
+        output, status = Open3.capture2("git", "reflog", "show", "--format=%H %gs", new_ref)
+        missing_reflog ||= !status.success?
+        status.success? && output.lines.any? do |line|
+          oid, message = line.split(" ", 2)
+          (old_oid.nil? || oid == old_oid) && message.to_s.strip == "Branch: renamed refs/heads/#{old_ref} to #{new_ref}"
+        end
+      end
+      return full_ref.delete_prefix("refs/heads/") if full_ref
+
+      :unknown if missing_reflog
+    end
+
+    def rename_branch_environments(old_ref, new_ref)
+      state.fetch("worktrees", {}).each_key do |id|
+        with_worktree_lock(id) do
+          with_state_lock do |data|
+            record = data.fetch("worktrees", {})[id]
+            next unless record
+
+            environments = record.fetch("environments", {})
+            next unless environments.key?(old_ref) && !environments.key?(new_ref)
+
+            entry = environments.delete(old_ref)
+            entry["ref"] = new_ref
+            environments[new_ref] = entry
+            record["current"] = new_ref if record["current"] == old_ref
+          end
+        end
+      end
+    end
+
+    def remove_branch_environments(ref)
+      state.fetch("worktrees", {}).each_key do |id|
+        with_worktree_lock(id) do
+          record = state.fetch("worktrees", {})[id]
+          entry = record&.fetch("environments", {})&.[](ref)
+          next unless entry
+
+          abort "Could not remove environment #{ref}." unless worktree_manager(entry).remove(entry)
+
+          with_state_lock do |data|
+            record = data.fetch("worktrees").fetch(id)
+            record.fetch("environments").delete(ref)
+            record["current"] = nil if record["current"] == ref
+            data.fetch("worktrees").delete(id) if record.fetch("environments").empty?
+          end
+          puts "Removed Brunch environment for deleted branch #{ref}."
+        end
+      end
+    end
+
     def worktree_status
       data = state
       record, current = current_worktree_entry(data)
@@ -289,6 +395,20 @@ module Brunch
       end
     end
 
+    def worktree_watch
+      raise CLI::OperationError, "brunch watch requires an interactive terminal." unless $stdout.tty?
+
+      loop do
+        print "\e[2J\e[H"
+        worktree_ports
+        puts "\nRefreshing every second. Press Ctrl-C to stop."
+        $stdout.flush
+        sleep 1
+      end
+    rescue Interrupt
+      puts "\nStopped watching."
+    end
+
     def worktree_port
       record, = current_worktree_entry(state)
       raise CLI::OperationError, "No Brunch environment in this worktree." unless record

metadata

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