ctree 0.5.3

data/lib/ctree/delete.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+module Ctree
+  module Delete
+    module_function
+
+    def run(name:, force: false)
+      source_root = Pathname.pwd
+      toplevel_out, _, status = Sh.capture3("git", "-C", source_root.to_s, "rev-parse", "--show-toplevel")
+      Log.die "not inside a git repository" unless status.success?
+      git_top = Pathname.new(toplevel_out.strip)
+      unless source_root.realpath == git_top.realpath
+        Log.die "must be invoked from project top-level (cwd=#{source_root}, top=#{git_top})"
+      end
+
+      if source_root.basename.to_s == name
+        Log.die "refusing to remove '#{name}' — that's the current source project itself"
+      end
+
+      parent_dir = source_root.parent
+      target_project = Naming.sanitize_compose_project_name(name)
+
+      # Resolve the actual worktree path from git's registration first — the
+      # registered absolute path may differ from parent_dir/name if the
+      # worktree was created from a different pwd or via a symlinked directory.
+      # Fall back to constructing the path if git has no matching entry.
+      worktree_list_out, _, _ = Sh.capture3("git", "-C", source_root.to_s, "worktree", "list", "--porcelain")
+      wt_records = worktree_list_out.split(/\n\n+/).filter_map do |block|
+        record = {}
+        block.each_line do |line|
+          line = line.chomp
+          record[:path]   = line.delete_prefix("worktree ")          if line.start_with?("worktree ")
+          record[:branch] = line.delete_prefix("branch refs/heads/") if line.start_with?("branch refs/heads/")
+        end
+        record unless record.empty?
+      end
+      matching_record   = wt_records.find { |r| r[:path] && File.basename(r[:path]) == name }
+      registered_wt_path = matching_record&.fetch(:path, nil)
+      worktree_branch    = matching_record&.fetch(:branch, nil)
+      target_path = registered_wt_path ? Pathname.new(registered_wt_path) : (parent_dir / name)
+
+      # Discover what currently exists for this name.
+      docker_ok = Sh.system("docker", "info", out: File::NULL, err: File::NULL)
+      Log.warn_ "docker not reachable — volumes and compose stack will not be touched" unless docker_ok
+
+      # Read the worktree's compose override file (if present) to find any
+      # `external: true` volumes whose explicit `name:` is NOT under the
+      # target project prefix. Those are source-shared (e.g. yarn-cache
+      # mounted from the source project) and must be preserved during removal.
+      config = Config.load(source_root)
+      Log.log_prefix = config[:log_prefix]
+      override_rel = config[:compose_override_file].to_s
+      shared_external_vols = []
+      override_path = override_rel.empty? ? nil : (target_path / override_rel)
+      if override_path&.file?
+        begin
+          override_doc = YAML.safe_load(File.read(override_path.to_s), aliases: true)
+          if override_doc.is_a?(Hash) && override_doc["volumes"].is_a?(Hash)
+            override_doc["volumes"].each_value do |v|
+              next unless v.is_a?(Hash) && v["external"]
+              nm = v["name"]
+              next unless nm.is_a?(String) && !nm.empty?
+              next if nm.start_with?("#{target_project}_")
+              shared_external_vols << nm
+            end
+          end
+        rescue Psych::SyntaxError => e
+          Log.warn_ "could not parse #{override_path}: #{e.message}; cannot identify shared volumes for preservation"
+        end
+        shared_external_vols.uniq!
+      end
+
+      vols = []
+      if docker_ok
+        vols_out, _, st = Sh.capture3("docker", "volume", "ls", "--format", "{{.Name}}")
+        Log.die "docker volume ls failed" unless st.success?
+        prefix_re = /\A#{Regexp.escape(target_project)}_/
+        vols = vols_out.lines.map(&:strip).reject(&:empty?).select { |v| v =~ prefix_re }.sort
+        # Belt-and-suspenders: explicitly drop any source-shared volume even
+        # though the prefix filter above should already exclude them.
+        vols -= shared_external_vols
+      end
+
+      containers = []
+      if docker_ok
+        ps_out, _, st = Sh.capture3(
+          "docker", "ps", "--all",
+          "--filter", "label=com.docker.compose.project=#{target_project}",
+          "--format", "{{.Names}}"
+        )
+        containers = ps_out.lines.map(&:strip).reject(&:empty?).sort if st.success?
+      end
+
+      tagged_images = []
+      if docker_ok
+        imgs_out, _, st = Sh.capture3("docker", "images",
+                                       "--format", "{{.Repository}}",
+                                       "--filter", "reference=#{target_project}-*")
+        tagged_images = imgs_out.lines.map(&:strip).reject(&:empty?).sort if st.success?
+      end
+
+      branch_to_check = worktree_branch || name
+      _, _, st = Sh.capture3("git", "-C", source_root.to_s, "show-ref", "--verify", "--quiet", "refs/heads/#{branch_to_check}")
+      branch_exists = st.success?
+
+      target_real = target_path.exist? ? target_path.realpath.to_s : target_path.to_s
+      worktree_registered = !registered_wt_path.nil?
+
+      # Branches are never deleted by remove (see below), so the presence
+      # of a same-named branch alone is not a reason to do work.
+      nothing_to_do = vols.empty? && containers.empty? && tagged_images.empty? && !worktree_registered && !target_path.exist?
+      if nothing_to_do
+        Log.info "nothing to remove for '#{name}' — no worktree, branch, containers, or volumes found"
+        exit 0
+      end
+
+      # Show the user exactly what will happen.
+      summary = []
+      summary << ""
+      summary << "[#{PROG}] About to delete '#{name}':"
+      summary << ""
+      summary << "  worktree path:  #{target_path}"
+      summary << "    - dir:        #{target_path.exist? ? "EXISTS — will be deleted" : "absent"}"
+      summary << "    - registered: #{worktree_registered ? "YES — will run `git worktree remove --force`" : "no"}"
+      summary << ""
+      if branch_exists
+        summary << "  git branch:     #{branch_to_check}  — preserved (run `git branch -D #{branch_to_check}` manually to delete)"
+      else
+        summary << "  git branch:     #{branch_to_check}  — not found"
+      end
+      summary << ""
+      summary << "  compose stack:  -p #{target_project}"
+      if containers.empty?
+        summary << "    - containers: none running for this project"
+      else
+        summary << "    - containers (will be stopped and removed via `docker compose down`):"
+        containers.each { |c| summary << "        #{c}" }
+      end
+      summary << ""
+      if vols.empty?
+        summary << "  docker volumes: none matching ^#{target_project}_"
+      else
+        summary << "  docker volumes (#{vols.size}, all will be PERMANENTLY deleted):"
+        vols.each { |v| summary << "        #{v}" }
+      end
+      summary << ""
+      unless shared_external_vols.empty?
+        summary << "  shared volumes (mounted from source via override yml; will NOT be touched):"
+        shared_external_vols.sort.each { |v| summary << "        #{v}" }
+        summary << ""
+      end
+      if tagged_images.empty?
+        summary << "  docker images:  no tags matching #{target_project}-*"
+      else
+        summary << "  docker image tags (#{tagged_images.size}, tags will be deleted — image layers preserved):"
+        tagged_images.each { |img| summary << "        #{img}" }
+      end
+      summary << ""
+      summary << "  Source project (#{source_root}) will NOT be touched."
+      summary << ""
+
+      Log.section(summary.join("\n"), interactive: true, force: force)
+
+      unless Prompt.confirm("Type 'yes' to confirm deletion of '#{name}':", default: nil, force: force)
+        warn "[#{PROG}] aborted: confirmation not given. No changes made."
+        exit 1
+      end
+
+      # === execute ===
+
+      failures = []
+
+      if docker_ok && !containers.empty?
+        _, err, st = Spinner.with_spinner("stopping compose stack -p #{target_project}") do
+          Sh.capture3("docker", "compose", "-p", target_project, "down", chdir: target_path.to_s)
+        end
+        if st.success?
+          Log.info "compose stack stopped"
+        else
+          Log.warn_ "compose down returned non-zero: #{err.strip}"
+          failures << "compose down"
+        end
+      end
+
+      if docker_ok && !tagged_images.empty?
+        _, rmi_err, rmi_st = Spinner.with_spinner("removing #{tagged_images.size} image tag(s)") do
+          Sh.capture3("docker", "rmi", *tagged_images)
+        end
+        if rmi_st.success?
+          Log.info "deleted #{tagged_images.size} image tag(s): #{tagged_images.join(", ")}"
+        else
+          Log.warn_ "docker rmi returned non-zero: #{rmi_err.strip}"
+          failures << "image rmi"
+        end
+      end
+
+      if docker_ok && !vols.empty?
+        # Batch removal: single subprocess call, single round-trip to the
+        # docker daemon. Falls back to per-volume on partial failure so
+        # error messages remain attributable.
+        _, batch_err, batch_st = Spinner.with_spinner("removing #{vols.size} volume(s)") do
+          Sh.capture3("docker", "volume", "rm", *vols)
+        end
+        if batch_st.success?
+          Log.info "deleted #{vols.size} volume(s): #{vols.join(", ")}"
+        else
+          Log.warn_ "batch volume removal failed; retrying one at a time: #{batch_err.strip}"
+          vols.each do |v|
+            _, _, exists_st = Sh.capture3("docker", "volume", "inspect", v)
+            unless exists_st.success?
+              Log.info "deleted volume #{v} (already gone)"
+              next
+            end
+            _, err, st = Spinner.with_spinner("removing volume #{v}") do
+              Sh.capture3("docker", "volume", "rm", v)
+            end
+            if st.success?
+              Log.info "deleted volume #{v}"
+            else
+              Log.warn_ "failed to remove volume #{v}: #{err.strip}"
+              failures << "volume rm #{v}"
+            end
+          end
+        end
+      end
+
+      # Worktree directory removal: rename + background-detached rm -rf.
+      # On the same filesystem, rename(2) is O(1) so remove returns in
+      # seconds regardless of how many files are in the worktree. The
+      # detached rm survives shell exit via Process.spawn's pgroup: true.
+      # On cross-filesystem rename (EXDEV) or rename failure for any other
+      # reason, we fall back to synchronous `git worktree remove --force`.
+      if worktree_registered || target_path.exist?
+        remove_failed = false
+
+        if target_path.exist?
+          quarantine = quarantine_path_for(target_path)
+
+          begin
+            File.rename(target_path.to_s, quarantine.to_s)
+            Log.info "worktree dir renamed -> #{quarantine.basename}"
+
+            bg_pid = Sh.spawn(
+              "rm", "-rf", quarantine.to_s,
+              out: File::NULL, err: File::NULL, in: File::NULL,
+              pgroup: true
+            )
+            Sh.detach(bg_pid)
+            Log.info "queued background worktree dir delete job (pid #{bg_pid})"
+          rescue Errno::EXDEV, Errno::EACCES, Errno::EPERM, SystemCallError => e
+            Log.warn_ "rename failed (#{e.class}: #{e.message}); falling back to synchronous removal"
+            _, fallback_err, fallback_st = Spinner.with_spinner("removing worktree #{target_path}") do
+              Sh.capture3("git", "-C", source_root.to_s, "worktree", "remove", "--force", target_path.to_s)
+            end
+            unless fallback_st.success?
+              Log.warn_ "git worktree remove failed: #{fallback_err.strip}"
+              begin
+                FileUtils.rm_rf(target_path.to_s, secure: true)
+                if target_path.exist?
+                  Log.warn_ "fallback rm_rf left #{target_path} behind"
+                  remove_failed = true
+                else
+                  Log.info "removed directory #{target_path} (fallback)"
+                end
+              rescue StandardError => rmerr
+                Log.warn_ "fallback rm_rf failed for #{target_path}: #{rmerr.message}"
+                remove_failed = true
+              end
+            end
+          end
+        end
+
+        # Prune always — cleans up the dangling registration after the
+        # rename, or any leftover from a prior failed removal.
+        _, prune_err, prune_st = Sh.capture3("git", "-C", source_root.to_s, "worktree", "prune")
+        if prune_st.success?
+          Log.info "pruned worktree registration"
+        else
+          Log.warn_ "git worktree prune failed: #{prune_err.strip}"
+          failures << "worktree prune"
+        end
+
+        failures << "worktree remove" if remove_failed
+      end
+
+      # Branches are intentionally preserved — see the README "remove"
+      # section for rationale. Even an auto-derived branch (created when
+      # `ctree add` is called without an explicit branch name) can carry
+      # commits the user wants to keep, push, or merge later. To clean up
+      # an orphan, run `git branch -D <name>` manually.
+
+      puts unless LogFile.enabled?
+      if failures.empty?
+        exit 0
+      else
+        Log.warn_ "removal completed with failures: #{failures.join(", ")}"
+        exit 2
+      end
+    end
+
+    # Builds a unique sibling path adjacent to target_path used as the
+    # rename destination. Includes the destroying process's pid and a
+    # short random suffix so concurrent destroys of distinct worktrees
+    # never collide and a re-run after a stuck prior attempt doesn't
+    # either.
+    def quarantine_path_for(target_path)
+      base = target_path.basename.to_s
+      parent = target_path.parent
+      suffix = ".ctree-destroying-#{Process.pid}-#{rand(2**32).to_s(36)}"
+      parent / "#{base}#{suffix}"
+    end
+  end
+end

data/lib/ctree/domain.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Ctree
+  module Domain
+    module_function
+
+    RESOLVER_DIR = "/etc/resolver"
+
+    def macos?
+      RUBY_PLATFORM.include?("darwin")
+    end
+
+    def apply_config_log_prefix!
+      config = Config.load(Pathname.pwd)
+      Log.log_prefix = config[:log_prefix]
+    end
+
+    def add(tld:)
+      Log.die "ctree domain is only supported on macOS" unless macos?
+      apply_config_log_prefix!
+      container, conf_path, port = find_dnsmasq!
+
+      entry = "address=/.#{tld}/127.0.0.1"
+      lines = read_conf(conf_path)
+      if lines.any? { |l| l.strip == entry }
+        Log.info "dnsmasq already has entry for .#{tld}; skipping"
+      else
+        File.write(conf_path, (lines + ["#{entry}\n"]).join)
+        Log.info "added #{entry} to #{conf_path}"
+        restart_container(container)
+      end
+
+      write_resolver(tld, port)
+    end
+
+    def remove(tld:)
+      Log.die "ctree domain is only supported on macOS" unless macos?
+      apply_config_log_prefix!
+      container, conf_path, _ = find_dnsmasq!
+
+      entry = "address=/.#{tld}/127.0.0.1"
+      lines = read_conf(conf_path)
+      filtered = lines.reject { |l| l.strip == entry }
+      if filtered.size == lines.size
+        Log.info "no dnsmasq entry found for .#{tld}"
+      else
+        File.write(conf_path, filtered.join)
+        Log.info "removed #{entry} from #{conf_path}"
+        restart_container(container)
+      end
+
+      remove_resolver(tld)
+    end
+
+    def list
+      Log.die "ctree domain is only supported on macOS" unless macos?
+      apply_config_log_prefix!
+      _, conf_path, _ = find_dnsmasq!
+      lines = read_conf(conf_path)
+      tlds = lines.filter_map do |line|
+        m = line.strip.match(/\Aaddress=\/\.(\S+)\/127\.0\.0\.1\z/)
+        m[1] if m
+      end
+
+      if tlds.empty?
+        puts "no domains configured in #{conf_path}"
+        return
+      end
+
+      tlds.each do |tld|
+        resolver_path = File.join(RESOLVER_DIR, tld)
+        status = File.exist?(resolver_path) ? "ok" : "missing"
+        puts "#{tld}   (resolver: #{status})"
+      end
+    end
+
+    def find_dnsmasq!
+      out, _, st = Sh.capture3("docker", "ps", "--quiet", "--filter", "status=running")
+      Log.die "docker not available" unless st.success?
+
+      ids = out.lines.map(&:strip).reject(&:empty?)
+      Log.die "no running containers found; is Docker running?" if ids.empty?
+
+      ids.each do |id|
+        inspect, _, ist = Sh.capture3("docker", "inspect", id,
+                                      "--format",
+                                      "{{.Name}}\t{{.Config.Image}}\t{{json .HostConfig.Binds}}\t{{json .HostConfig.PortBindings}}")
+        next unless ist.success?
+
+        name, image, binds_json, ports_json = inspect.strip.split("\t", 4)
+        next unless image&.include?("dnsmasq")
+
+        binds = JSON.parse(binds_json || "[]")
+        conf_path = binds.filter_map { |b| b.split(":").first if b.include?("/etc/dnsmasq.conf") }.first
+        Log.die "found dnsmasq container #{name} but cannot locate config file via volume mounts" unless conf_path
+
+        ports = JSON.parse(ports_json || "{}")
+        port = ports.values.flatten.first&.dig("HostPort") || "53"
+
+        return [name.delete_prefix("/"), conf_path, port]
+      end
+
+      Log.die "no running dnsmasq container found; is traefik-dns running?"
+    end
+
+    def read_conf(path)
+      File.exist?(path) ? File.readlines(path) : []
+    end
+
+    def restart_container(name)
+      _, err, st = Spinner.with_spinner("restarting #{name}") do
+        Sh.capture3("docker", "restart", name)
+      end
+      if st.success?
+        Log.info "restarted #{name}"
+      else
+        Log.warn_ "docker restart #{name} failed: #{err.strip}"
+      end
+    end
+
+    def write_resolver(tld, port)
+      path = File.join(RESOLVER_DIR, tld)
+      content = "nameserver 127.0.0.1\nport #{port}\n"
+
+      if File.exist?(path) && File.read(path) == content
+        Log.info "#{path} already configured; skipping"
+        return
+      end
+
+      _, err, st = Sh.capture3("sudo", "tee", path, stdin_data: content)
+      if st.success?
+        Log.info "wrote #{path}"
+      else
+        Log.warn_ "could not write #{path} (#{err.strip})"
+        Log.warn_ "run manually: sudo bash -c 'printf \"nameserver 127.0.0.1\\nport #{port}\\n\" > #{path}'"
+      end
+    end
+
+    def remove_resolver(tld)
+      path = File.join(RESOLVER_DIR, tld)
+      unless File.exist?(path)
+        Log.info "#{path} does not exist; skipping"
+        return
+      end
+
+      _, err, st = Sh.capture3("sudo", "rm", path)
+      if st.success?
+        Log.info "removed #{path}"
+      else
+        Log.warn_ "could not remove #{path} (#{err.strip})"
+        Log.warn_ "run manually: sudo rm #{path}"
+      end
+    end
+
+    private_class_method :find_dnsmasq!, :read_conf, :restart_container,
+                         :write_resolver, :remove_resolver, :apply_config_log_prefix!
+  end
+end

data/lib/ctree/env_cmd.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Ctree
+  module EnvCmd
+    module_function
+
+    def run(subcommand, force: false)
+      target_path, source_root = resolve_worktree!
+      config    = Config.load(source_root)
+      Log.log_prefix = config[:log_prefix]
+      skip_keys = config[:skip_env_keys]
+
+      case subcommand
+      when "list"  then cmd_list(target_path, source_root, skip_keys, config[:env_filename])
+      when "check" then cmd_check(target_path, source_root, config)
+      when "fix"   then cmd_fix(target_path, source_root, config, force: force)
+      else Log.die "unknown subcommand '#{subcommand}'; use: list, check, or fix"
+      end
+    end
+
+    def resolve_worktree!
+      target_path = Pathname.pwd
+      toplevel_out, _, st = Sh.capture3("git", "-C", target_path.to_s, "rev-parse", "--show-toplevel")
+      Log.die "not inside a git repository" unless st.success?
+      git_top = Pathname.new(toplevel_out.strip)
+      unless target_path.realpath == git_top.realpath
+        Log.die "must be invoked from the worktree top-level"
+      end
+      common_out, _, c_st = Sh.capture3("git", "-C", target_path.to_s, "rev-parse", "--git-common-dir")
+      Log.die "could not resolve git common dir" unless c_st.success?
+      common = Pathname.new(common_out.strip)
+      common = (target_path / common) unless common.absolute?
+      source_root = common.parent.realpath
+      if source_root == target_path.realpath
+        Log.die "already in the source project; run ctree env from inside a worktree"
+      end
+      [target_path.realpath, source_root]
+    end
+
+    def ctree_managed_keys(config)
+      keys = ["COMPOSE_PROJECT_NAME"]
+      host_name_key = config[:host_name].to_s.strip
+      keys << host_name_key unless host_name_key.empty?
+      keys << "HOST_NAME_SUFFIX" unless config[:host_name_suffix].to_s.strip.empty?
+      domain_key = config[:host_domain_env_key].to_s.strip
+      keys << domain_key unless domain_key.empty?
+      keys.uniq
+    end
+
+    def cmd_list(target_path, source_root, skip_keys, env_filename)
+      tgt_env_path = target_path / env_filename
+      Log.die "no #{env_filename} found at #{tgt_env_path}" unless tgt_env_path.file?
+      src_env_path = source_root / env_filename
+      Log.die "no #{env_filename} found in source repo at #{src_env_path}" unless src_env_path.file?
+
+      tgt_env = EnvFile.parse(tgt_env_path.to_s)
+      tgt_env.each { |k, v| puts "#{k}=#{v}" }
+      exit 0
+    end
+
+    def cmd_check(target_path, source_root, config)
+      env_filename = config[:env_filename]
+      tgt_env_path = target_path / env_filename
+      Log.die "no #{env_filename} found at #{tgt_env_path}" unless tgt_env_path.file?
+      src_env_path = source_root / env_filename
+      Log.die "no #{env_filename} found in source repo at #{src_env_path}" unless src_env_path.file?
+
+      tgt_env = EnvFile.parse(tgt_env_path.to_s)
+      src_env = EnvFile.parse(src_env_path.to_s)
+
+      managed   = ctree_managed_keys(config)
+      missing   = src_env.keys - tgt_env.keys
+      extra     = tgt_env.keys - src_env.keys - managed - config[:skip_env_keys]
+
+      if missing.empty? && extra.empty?
+        Log.info "env is in sync"
+        exit 0
+      else
+        missing.each { |k| puts "[missing] #{k}" }
+        extra.each   { |k| puts "[extra] #{k}" }
+        exit 1
+      end
+    end
+
+    def cmd_fix(target_path, source_root, config, force: false)
+      env_filename = config[:env_filename]
+      tgt_env_path = target_path / env_filename
+      Log.die "no #{env_filename} found at #{tgt_env_path}" unless tgt_env_path.file?
+      src_env_path = source_root / env_filename
+      Log.die "no #{env_filename} found in source repo at #{src_env_path}" unless src_env_path.file?
+
+      tgt_env = EnvFile.parse(tgt_env_path.to_s)
+      src_env = EnvFile.parse(src_env_path.to_s)
+
+      managed        = ctree_managed_keys(config)
+      effective_skip = (config[:skip_env_keys] + managed).uniq
+      missing        = src_env.keys - tgt_env.keys - managed
+      orphaned       = tgt_env.keys - src_env.keys - effective_skip
+
+      if missing.empty? && orphaned.empty?
+        Log.info "env is in sync; nothing to fix"
+        exit 0
+      end
+
+      missing.each do |key|
+        new_value = Prompt.for_env_var_change(key, src_env[key], force: force)
+        EnvFile.upsert(tgt_env_path.to_s, key, new_value)
+      end
+
+      orphaned.each do |key|
+        if Prompt.confirm("#{key}=#{tgt_env[key]} (not in source #{env_filename}, delete? [y/N]):", default: :no, force: force)
+          EnvFile.delete(tgt_env_path.to_s, key)
+        end
+      end
+
+      Log.info "updated #{env_filename}"
+      exit 0
+    end
+
+    private_class_method :resolve_worktree!, :ctree_managed_keys,
+                         :cmd_list, :cmd_check, :cmd_fix
+  end
+end

data/lib/ctree/free.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Ctree
+  module Free
+    module_function
+
+    def run
+      target_path = Pathname.pwd
+      toplevel_out, _, status = Sh.capture3("git", "-C", target_path.to_s, "rev-parse", "--show-toplevel")
+      Log.die "not inside a git repository" unless status.success?
+      git_top = Pathname.new(toplevel_out.strip)
+      unless target_path.realpath == git_top.realpath
+        Log.die "must be invoked from the worktree top-level (cwd=#{target_path}, top=#{git_top})"
+      end
+
+      common_out, _, c_st = Sh.capture3("git", "-C", target_path.to_s, "rev-parse", "--git-common-dir")
+      Log.die "could not resolve git common dir" unless c_st.success?
+      common = Pathname.new(common_out.strip)
+      common = (target_path / common) unless common.absolute?
+      source_root = common.parent.realpath
+
+      if source_root == target_path.realpath
+        Log.die "already in the source project; run ctree free from inside a worktree"
+      end
+
+      config = Config.load(source_root)
+      Log.log_prefix = config[:log_prefix]
+      prefix = config[:free_branch_prefix]
+
+      current_branch_out, _, cb_st = Sh.capture3("git", "-C", target_path.to_s, "rev-parse", "--abbrev-ref", "HEAD")
+      Log.die "could not resolve current branch" unless cb_st.success?
+      current_branch = current_branch_out.strip
+      if !prefix.empty? && current_branch.start_with?(prefix)
+        Log.info "already on a free branch (#{current_branch}); nothing to do"
+        exit 0
+      end
+
+      branches_out, _, branches_st = Sh.capture3("git", "-C", source_root.to_s, "branch", "--list", "#{prefix}*")
+      Log.die "git branch --list failed" unless branches_st.success?
+      all_free = branches_out.lines.map { |l| l.sub(/\A[*+ ] /, "").strip }.reject(&:empty?).sort
+
+      worktree_raw, _, wt_st = Sh.capture3("git", "-C", source_root.to_s, "worktree", "list", "--porcelain")
+      Log.die "git worktree list failed" unless wt_st.success?
+      occupied = List.parse_worktree_porcelain(worktree_raw).filter_map { |e| e[:branch] }.to_set
+
+      branch = first_available_branch(all_free, occupied)
+      if branch
+        _, err, st = Spinner.with_spinner("checking out #{branch}") do
+          Sh.capture3("git", "-C", target_path.to_s, "checkout", branch)
+        end
+        Log.die "git checkout #{branch} failed: #{err.strip}" unless st.success?
+      else
+        branch = next_sequential_branch(prefix, all_free)
+        _, err, st = Spinner.with_spinner("checking out #{branch}") do
+          Sh.capture3("git", "-C", target_path.to_s, "checkout", "-b", branch)
+        end
+        Log.die "git checkout -b #{branch} failed: #{err.strip}" unless st.success?
+      end
+      Log.info "checked out #{branch}"
+
+      default_branch = Git.detect_default_branch(source_root)
+      Rebase.rebase_branch_onto_default(target_path, branch, default_branch)
+    end
+
+    def first_available_branch(all_free, occupied)
+      all_free.sort.find { |b| !occupied.include?(b) }
+    end
+
+    def next_sequential_branch(prefix, all_free)
+      numeric_pattern = /\A#{Regexp.escape(prefix)}(\d+)\z/
+      numbers = all_free.filter_map { |b| b.match(numeric_pattern)&.then { |m| m[1].to_i } }.to_set
+      n = 1
+      n += 1 while numbers.include?(n)
+      "#{prefix}#{n.to_s.rjust(3, "0")}"
+    end
+  end
+end