brunch 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 668bcb5a607af2adcad5006541dc927be6e1c5277d4c79f57b46de725e96076b
-  data.tar.gz: c9a02342f703ce5546860760165f4e6b3226cbc6d686f1b5b12a3891e27ad85d
+  metadata.gz: c9e410a84d1fd30ba484345f2027d5253ed9596f0b5f26efa1add8d2b863a750
+  data.tar.gz: 75cf5154603bf83bf8a439f16a2489ff4bf5dda9ce9bb7dc6340e2591559458c
 SHA512:
-  metadata.gz: d47e2a2fa7a68de063d05696eadaac3e4e41939d4e9faac87c875752c0a4e83542a13dfe9a0171b17590f7208825088de95875c87e156c10b91be2fed7a43393
-  data.tar.gz: 94449f91dbaa4bbcb70ab6aca393068f4e25e0e92797487195de86ffd05f5d2c50ab7f3f50b6fe2837938f1da6d5e6cbca03f34ffe3309e4789e411854c0fa5f
+  metadata.gz: 7cfe235dfe3e43525d0a5fcaf6c8e9fa0e26d31816eec9dde3b57a2474b5b92624f069465a6b8f5b0be580ac97aeadccf44eb9441afeb54e99ea73f77d225316
+  data.tar.gz: 909b5e6ebb1f6cb14395dc68636db0e24cb26fe24acfedc45def14dd37ea0989b0500e07d8362fb04b92361d3b6d90f954df3edfa783b72fe1f7edcc23f3c49e

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## Unreleased
+## 1.0.0 - 2026-10-16
+
+- Recover automatically when a stopped Compose environment cannot resume: Brunch
+  recreates the failed environment instead of leaving its worktree unavailable.
+- Correctly reconcile forced branch renames such as `git branch -M source target`
+  when the destination already has an environment.
+- Keep the 100% line and branch coverage gate for the regular test suite while
+  allowing manager integration jobs to report functional failures directly.
+- Clarify the lifecycle of stopped Compose containers, Rails PID files, forced
+  branch renames, and `brunch cleanup`.
+
+## 0.9.2 - 2026-10-05
+
+- Settle branch deletions automatically after the Git process exits, preserving
+  environments across `git branch -m` without requiring another Brunch command.
+  Handle `git branch -M` when the destination already has an environment, and
+  keep pending state if the background worker cannot start.
 
 ## 0.9.1 - 2026-10-03
 

data/README.md

@@ -140,6 +140,15 @@ With Compose, each branch keeps its own Compose project and named volumes, so pe
 Returning to a previously activated branch starts its stopped containers again,
 preserving files written inside them. The branch keeps the same host port.
 
+If a resumed Compose application exits immediately, Brunch recreates that
+environment automatically. This recovers the worktree but discards files kept
+only in the container's writable layer; named volumes remain intact.
+
+Applications that write a PID file inside the container should remove it before
+starting. For example, a Rails Compose command can begin with
+`rm -f /tmp/rails-server.pid &&`. A stopped container keeps its writable layer,
+including a stale PID file, until it is recreated.
+
 To manually start the environment after `brunch stop`:
 
 ```bash
@@ -194,6 +203,10 @@ brunch watch
 
 Switching branches inside one worktree does not affect environments running in other worktrees.
 
+For reliable automatic handling of forced branch renames such as
+`git branch -M source target`, use a Git version supported by `ghe doctor` and
+run `brunch install` after upgrading git-hooks-ext.
+
 If you create a worktree with plain Git:
 
 ```bash
@@ -214,6 +227,9 @@ brunch cleanup
 ```
 
 Brunch never deletes the worktree source directory.
+It removes environments for worktrees that Git no longer reports; it does not
+act as a general-purpose command for deleting the current worktree's stopped
+containers or volumes.
 
 ## Managers
 
@@ -301,15 +317,20 @@ 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.
 
 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.
+environments for removal. A detached worker waits for the Git process that
+triggered the hook to exit, then checks the final refs and reflogs. A rename
+keeps its environment under the new name; a deletion removes the managed
+resources, including Compose containers and volumes. A Brunch command run
+while the identified Git process is still working leaves the queued environment
+alone. If the process cannot be identified or the worker cannot start, the next
+regular Brunch command after Git exits, such as `brunch status` or
+`brunch cleanup`, performs the check. Brunch also checks for
+missing branches when Git emits no deletion event, on the next regular command.
+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.
+For `git branch -M old target`, when `target` already has a Brunch environment,
+Brunch removes that overwritten environment and moves `old` to `target`.
 
 ## Commands
 

data/lib/brunch/branch_settlement.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "open3"
+require "securerandom"
+
+module Brunch
+  module BranchSettlement
+    module_function
+
+    def git_ancestor(pid = Process.ppid)
+      32.times do
+        process = process_info(pid)
+        break unless process
+
+        return { "pid" => pid, "started" => process.fetch(:started) } if File.basename(process.fetch(:command)) == "git"
+
+        pid = process.fetch(:parent)
+        break if pid <= 1
+      end
+      nil
+    end
+
+    def running?(identity)
+      return false unless identity.is_a?(Hash) && identity["pid"].is_a?(Integer) && identity["started"].is_a?(String)
+
+      process = process_info(identity.fetch("pid"))
+      return process_exists?(identity.fetch("pid")) unless process
+
+      process.fetch(:started) == identity.fetch("started") && !process.fetch(:state).start_with?("Z")
+    end
+
+    def process_exists?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    def token = SecureRandom.hex(16)
+
+    def spawn_worker(root, ref, token)
+      executable = File.expand_path("../../exe/brunch", __dir__)
+      pid = Process.spawn(Gem.ruby, executable, "branch-settled", ref, token,
+                          chdir: root, in: File::NULL, out: File::NULL, err: File::NULL,
+                          pgroup: true, close_others: true)
+      Process.detach(pid)
+    end
+
+    def wait_for(identity)
+      sleep 0.1 while running?(identity)
+    end
+
+    def process_info(pid)
+      output, status = Open3.capture2("ps", "-p", pid.to_s, "-o", "ppid=,lstart=,stat=,comm=", err: File::NULL)
+      return unless status.success?
+
+      fields = output.strip.split(/\s+/, 8)
+      return unless fields.length == 8 && fields[0].match?(/\A\d+\z/)
+
+      { parent: fields[0].to_i, started: fields[1, 5].join(" "), state: fields[6], command: fields[7] }
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

data/lib/brunch/cli.rb

@@ -24,7 +24,7 @@ module Brunch
       in ["install"] then Hooks.install
       in ["version"] | ["--version"] | ["-v"] then puts Brunch::VERSION
       else
-        unless arguments.first == "branch-deleted"
+        unless %w[branch-deleted branch-settled].include?(arguments.first)
           reconcile_deleted_branches
           reconcile_missing_branches
         end

data/lib/brunch/hooks.rb

@@ -27,7 +27,9 @@ module Brunch
       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)])
+        with_branch_deletion_hook do
+          CLI.start(["branch-deleted", arguments.fetch(0), arguments.fetch(2)])
+        end
       when "worktree-created", "worktree-removed", "worktree-moved", "worktree-pruned", "worktree-repaired"
         CLI.start(["worktree-event", event, *arguments])
       else
@@ -43,6 +45,15 @@ module Brunch
     end
     private_class_method :git_output
 
+    def with_branch_deletion_hook
+      previous = ENV.fetch("BRUNCH_BRANCH_DELETION_HOOK", nil)
+      ENV["BRUNCH_BRANCH_DELETION_HOOK"] = "1"
+      yield
+    ensure
+      previous ? ENV["BRUNCH_BRANCH_DELETION_HOOK"] = previous : ENV.delete("BRUNCH_BRANCH_DELETION_HOOK")
+    end
+    private_class_method :with_branch_deletion_hook
+
     def install_hook(path, event)
       contents = hook_contents(event)
       abort "Refusing to replace existing hook: #{path}" if File.exist?(path) && File.read(path) != contents && !brunch_hook?(path)

data/lib/brunch/version.rb

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

data/lib/brunch/worktree_mode.rb

@@ -21,6 +21,7 @@ module Brunch
         worktree_activate(repo_root)
       in ["stop"] then worktree_stop(repo_root)
       in ["branch-deleted", ref, oid] then record_deleted_branch(ref, oid)
+      in ["branch-settled", ref, token] then settle_deleted_branch(ref, token)
       in ["cleanup"] | ["register", _] then worktree_cleanup
       in ["status"] then worktree_status
       in ["list"] then worktree_ports
@@ -129,16 +130,16 @@ module Brunch
         end
         if existing && !force && existing["snapshot"] == path && existing["status"] != "starting"
           with_state_lock { |data| data.fetch("worktrees").fetch(id)["current"] = ref }
-          unless worktree_manager(existing).resume(existing)
-            abort "Could not resume environment for #{path}; the container may have exited. Check brunch logs. " \
-                  "If dependencies changed, rebuild with brunch restart (this replaces the container)."
+          if 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
 
-          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
+          warn "Could not resume #{ref}; recreating its environment."
+          force = true
         end
         abort "Could not reset environment for #{path}." if existing && !worktree_manager(existing).reset(existing)
 
@@ -261,27 +262,58 @@ module Brunch
     end
 
     def record_deleted_branch(ref, oid)
+      git = BranchSettlement.git_ancestor if ENV["BRUNCH_BRANCH_DELETION_HOOK"] == "1"
+      token = BranchSettlement.token if git
+      recorded = false
       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
+        (data["deleted_branches"] ||= {})[ref] = git ? { "oid" => oid, "git" => git, "token" => token } : oid
+        recorded = true
       end
+      BranchSettlement.spawn_worker(repo_root, ref, token) if recorded && git
+    rescue SystemCallError => e
+      warn "Could not start branch cleanup worker: #{e.message}; cleanup will run on the next Brunch command."
     end
 
     def reconcile_deleted_branches
       pending = state.fetch("deleted_branches", {})
       return if pending.empty?
 
-      refs = local_branch_refs
-      pending.each do |ref, oid|
+      pending.each_key { |ref| settle_deleted_branch(ref) }
+    end
+
+    def settle_deleted_branch(ref, expected_token = nil)
+      if expected_token
+        queued = state.fetch("deleted_branches", {})[ref]
+        return unless queued.is_a?(Hash) && queued["token"] == expected_token
+
+        BranchSettlement.wait_for(queued.fetch("git"))
+      end
+      directory = File.join(state_root, "branch-locks")
+      FileUtils.mkdir_p(directory)
+      File.open(File.join(directory, Digest::SHA256.hexdigest(ref)), "w") do |lock|
+        lock.flock(File::LOCK_EX)
+        pending = state.fetch("deleted_branches", {})[ref]
+        next unless pending
+        next if expected_token && (!pending.is_a?(Hash) || pending["token"] != expected_token)
+
+        identity = pending["git"] if pending.is_a?(Hash)
+        next if identity && BranchSettlement.running?(identity)
+
+        oid = pending.is_a?(Hash) ? pending.fetch("oid") : pending
+        refs = local_branch_refs
         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)
+          renamed ? rename_branch_environments(ref, renamed, replace_existing: pending.is_a?(Hash)) : remove_branch_environments(ref)
+        end
+        with_state_lock do |data|
+          current = data.fetch("deleted_branches", {})[ref]
+          data.fetch("deleted_branches").delete(ref) if current == pending
         end
-        with_state_lock { |data| data.fetch("deleted_branches").delete(ref) }
       end
     end
 
@@ -299,7 +331,7 @@ module Brunch
         renamed = renamed_branch(ref, nil, refs)
         next if renamed == :unknown
 
-        renamed ? rename_branch_environments(ref, renamed) : remove_branch_environments(ref)
+        renamed ? rename_branch_environments(ref, renamed, replace_existing: true) : remove_branch_environments(ref)
       end
     end
 
@@ -325,7 +357,11 @@ module Brunch
       :unknown if missing_reflog
     end
 
-    def rename_branch_environments(old_ref, new_ref)
+    def rename_branch_environments(old_ref, new_ref, replace_existing: false)
+      records = state.fetch("worktrees", {}).values
+      return unless records.any? { |record| record.fetch("environments", {}).key?(old_ref) }
+
+      remove_branch_environments(new_ref) if replace_existing
       state.fetch("worktrees", {}).each_key do |id|
         with_worktree_lock(id) do
           with_state_lock do |data|

data/lib/brunch.rb

@@ -2,6 +2,7 @@
 
 require_relative "brunch/version"
 require_relative "brunch/managers"
+require_relative "brunch/branch_settlement"
 require_relative "brunch/worktree_mode"
 require_relative "brunch/cli"
 require_relative "brunch/hooks"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brunch
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Maciej Ciemborowicz
@@ -92,6 +92,7 @@ files:
 - brunch.webp
 - exe/brunch
 - lib/brunch.rb
+- lib/brunch/branch_settlement.rb
 - lib/brunch/cli.rb
 - lib/brunch/hooks.rb
 - lib/brunch/managers.rb