git-trim 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14a8db7d9bf6cca92301a221f4e096d633882d103f9f7ea4b68e4ce5a6187ce5
-  data.tar.gz: 26a4e8614638c39d3692815c34aee4d4358088e62aa13ebb3d6ff0372d1ee3f7
+  metadata.gz: e0d7321c50f209f50a7aa16e40a26ecc655cc020af8338c4902661bf66260bd7
+  data.tar.gz: 48046ed58462e3ef2553e970c24ebcefb125c16b885f1ba942c4ef87d8d31ac1
 SHA512:
-  metadata.gz: a3915fb4d49379edebb0928cde8f4c7f2774c429f437ee67381edfd263b567c32b3d6f7ae5c922b7c1d963079859ea844b3916d62f7a3a5712a899f2e0a6d75e
-  data.tar.gz: 4e604a55e748caa6af8537b929d6bdde5d50b352c6e5a73cb38950133e9f796f0df855e620b45173928c5ef535b311f8dd28ae8a40d3b5e94c26239815cdbe44
+  metadata.gz: 07ae69e3dce7993df35a365fbe8845d0d516944213bb29ecd40f10ca660222d10c8205be3fa8c56f940bd016b26d5ac2f830433c00f5170b313767b309ff1b7d
+  data.tar.gz: ec29e5f712886391185e166bce3070d197097deb1bc9e8236a67a2d9d357ec07ece989e7db12337277a2f60fb35dbf21e63b8bf7ed0f54764103519a45ec4523

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    git-trim (0.2.0)
+    git-trim (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,6 @@
 # git trim
 
-Deletes local branches — and the [linked worktrees](https://git-scm.com/docs/git-worktree) that hold them — once they are fully merged into `main`. Run it after a round of PRs merge and it cleans up everything that's done, while refusing to touch anything that still has work in it.
+Deletes local branches — and the [linked worktrees](https://git-scm.com/docs/git-worktree) that hold them — once they are merged into `main`, including squash merges. Run it after a round of PRs merge and it cleans up everything that's done, while refusing to touch anything that still has work in it.
 
 ## Installation
 
@@ -20,14 +20,51 @@ Or install it yourself as:
 
 ## Usage
 
-Run `git trim` from anywhere inside a repository. It fetches (with prune), then removes every local branch that is fully merged into `main`, unless the branch is:
+Run `git trim` from anywhere inside a repository. It fetches (with prune), then removes every local branch that is merged into `main`, unless the branch is:
 
 - `main` itself,
-- the branch you currently have checked out, or
+- the branch you currently have checked out (or the one checked out in the main worktree), or
 - listed in a `.git-protected-branches` file.
 
 If no local `main` exists (common in bare-repo + worktrees layouts), it compares against `origin/main` instead.
 
+### Options
+
+| Flag | Effect |
+| --- | --- |
+| `-n`, `--dry-run` | Print exactly what would be removed and which signal proved it merged, without deleting anything. It still runs `git fetch -ap`, so the report reflects the current remote. |
+| `--no-gh` | Skip the GitHub check entirely and use git-only detection. |
+| `-h`, `--help` | Show usage. |
+
+### How merges are detected
+
+A branch is trimmed when **any** of these proves it is merged:
+
+1. **Regular merge.** The branch is in `git branch --merged main`. It is deleted with `git branch -d`.
+2. **Squash merge, offline.** git-trim builds a throwaway commit holding the branch's whole diff on top of its merge base (`git commit-tree <branch>^{tree} -p $(git merge-base main <branch>)`) and asks `git cherry main <tmp>` whether `main` already has an equivalent patch. No network needed.
+3. **Merged GitHub PR.** A merged PR whose head branch has the same name **and** whose head commit is exactly the local tip. All merged PRs are fetched in one `gh pr list --state merged` call (up to 1000, most recent first).
+
+Branches proven by (2) or (3) are deleted with `git branch -D`, since `-d` refuses squash-merged branches. `-D` is never used for anything else.
+
+Some cases are reported and left alone:
+
+- **Extra local commits.** If a merged PR exists for the branch but the local branch has commits the PR never had, the branch is kept:
+  `Skipping branch 'feature-x': it has commits that merged PR #42 never had`
+- **Gone upstream, no proof.** A branch whose upstream was deleted (`[gone]`) is **not** trimmed for that reason alone, because a PR closed without merging looks the same. It is reported as possibly stale:
+  `Keeping branch 'spike': its upstream is gone but nothing proves it was merged (possibly stale)`
+
+### The GitHub CLI is optional
+
+Signal (3) uses [`gh`](https://cli.github.com/) when it is available and is skipped otherwise. git-trim prints one warning naming the reason, carries on with git-only detection, and exits 0 as usual:
+
+```
+git-trim: gh not installed; skipping GitHub PR check, using git-only detection
+```
+
+The reasons are: `gh` is not installed, no remote points at GitHub, `gh` is not logged in, `gh` can't verify its login (GitHub unreachable or token rejected), GitHub is unreachable, the API rate limit was hit, `gh` timed out, or it returned output that couldn't be parsed. An error, empty output or malformed JSON never counts as evidence that a branch is merged.
+
+`gh` is consulted only when git alone can't prove some branch or detached worktree merged. It runs with `GH_PROMPT_DISABLED=1`, with no terminal on stdin, and under a 15-second timeout, so a hung auth prompt or network call can't stall the run.
+
 ### Worktrees
 
 If a merged branch is checked out in a linked worktree, `git trim` removes the worktree first and then deletes the branch. Worktrees with uncommitted changes or untracked files are left alone, along with their branch:
@@ -35,15 +72,25 @@ If a merged branch is checked out in a linked worktree, `git trim` removes the w
 ```
 $ git trim
 Removed worktree /Users/you/src/project/feature-a
-Deleted branch feature-a (was fa68cf94).
+Deleted branch feature-a (was fa68cf94). [merged into main]
+Deleted branch feature-c (was 1b2c3d4e). [squash-merged into main (patch already in main)]
 Skipping branch 'feature-b': worktree at /Users/you/src/project/feature-b has local changes
 ```
 
 Commit or stash the local changes and run `git trim` again to clean up the rest.
 
+**Detached worktrees** (detached HEAD, such as the ones agents create for read-only review) are removed when they are clean and their HEAD is contained in `main`, or equals the head commit of a merged PR:
+
+```
+Removed detached worktree /Users/you/src/project/review-42 [HEAD is the head of merged PR #42]
+Skipping detached worktree at /Users/you/src/project/review-43: it has local changes
+```
+
+The main worktree and the worktree you run `git trim` from are never removed.
+
 ### Protected branches
 
-The `.git-protected-branches` file can reside in the current directory or any parent directory. Branch names are each listed on a line in the file. For example:
+The `.git-protected-branches` file can reside in the current directory or any parent directory; the nearest one wins. Branch names are each listed on a line in the file. For example:
 
 ```
 main

data/lib/git-trim/version.rb

@@ -1,3 +1,3 @@
 class GitTrim
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/git-trim.rb

@@ -1,14 +1,65 @@
 require "git-trim/version"
+require "json"
+require "open3"
+require "optparse"
 require "shellwords"
 
 class GitTrim
+  GH_TIMEOUT = 15
+  GH_PR_LIMIT = 1000
+
+  # gh must never stop to ask a question: no prompts, no update notices,
+  # no spinner, no colour codes in the JSON.
+  GH_ENV = {
+    "GH_PROMPT_DISABLED" => "1",
+    "GH_NO_UPDATE_NOTIFIER" => "1",
+    "GH_SPINNER_DISABLED" => "1",
+    "NO_COLOR" => "1",
+  }.freeze
+
+  # Identity for the throwaway commit built by the offline squash check, so it
+  # works even when user.name/user.email aren't configured.
+  TMP_COMMIT_ENV = {
+    "GIT_AUTHOR_NAME" => "git-trim",
+    "GIT_AUTHOR_EMAIL" => "git-trim@localhost",
+    "GIT_COMMITTER_NAME" => "git-trim",
+    "GIT_COMMITTER_EMAIL" => "git-trim@localhost",
+  }.freeze
+
+  # Why a branch counts as merged. Only a regular merge can use `git branch
+  # -d`; git refuses -d for squash-merged branches, so the other proofs force.
+  Proof = Struct.new(:reason, :force)
+
+  def initialize(gh_timeout: GH_TIMEOUT)
+    @gh_timeout = gh_timeout
+  end
+
   def run(argv=nil)
+    @dry_run = false
+    @use_gh = true
+    help = false
+    parser = OptionParser.new do |opts|
+      opts.banner = "Usage: git trim [--dry-run] [--no-gh]"
+      opts.on("-n", "--dry-run", "Show what would be removed, and why, without changing anything") { @dry_run = true }
+      opts.on("--[no-]gh", "Use the GitHub CLI to detect merged PRs (default: on when available)") { |value| @use_gh = value }
+      opts.on("-h", "--help", "Show this help") { help = true }
+    end
+    begin
+      parser.parse(argv || [])
+    rescue OptionParser::ParseError => e
+      warn "git-trim: #{e.message}"
+      warn parser.banner
+      return 1
+    end
+    if help
+      puts parser
+      return 0
+    end
+    remove_instance_variable(:@merged_prs) if defined?(@merged_prs)
+
     %x{git fetch -ap}
 
-    if File.exist?(".git-protected-branches")
-      protected_branches = File.read(".git-protected-branches").split("\n")
-    end
-    protected_branches ||= []
+    protected_branches = read_protected_branches
     protected_branches << "main"
 
     base = base_ref
@@ -17,27 +68,28 @@ class GitTrim
       return 1
     end
 
-    branches = %x{git branch --merged #{Shellwords.escape(base)} --format='%(refname:short)'}.split("\n").collect(&:strip)
-    branches -= protected_branches
-    branches -= [current_branch]
-
     worktrees = linked_worktrees
+    branch_worktrees = worktrees.select { |wt| wt[:branch] }.to_h { |wt| [wt[:branch], wt[:path]] }
 
-    branches.each do |branch|
-      if (path = worktrees[branch])
-        output = %x{git worktree remove #{Shellwords.escape(path)} 2>&1}
-        unless $?.success?
-          if output.include?("contains modified or untracked files")
-            puts "Skipping branch '#{branch}': worktree at #{path} has local changes"
-          else
-            puts "Skipping branch '#{branch}': could not remove worktree at #{path}"
-            puts output
-          end
-          next
-        end
-        puts "Removed worktree #{path}"
+    merged = %x{git branch --merged #{Shellwords.escape(base)} --format='%(refname:short)'}.split("\n").collect(&:strip)
+    excluded = protected_branches + [current_branch, main_worktree_branch].compact
+
+    local_branches.each do |branch|
+      next if excluded.include?(branch[:name])
+
+      proof = merge_proof(branch, base, merged)
+      if proof.is_a?(Proof)
+        trim_branch(branch[:name], proof, branch_worktrees[branch[:name]])
+      elsif proof.nil? && branch[:gone]
+        puts "Keeping branch '#{branch[:name]}': its upstream is gone but nothing proves it was merged (possibly stale)"
       end
-      puts %x{git branch -d #{Shellwords.escape(branch)}}
+    end
+
+    here = current_worktree
+    worktrees.select { |wt| wt[:detached] }.each do |wt|
+      next if same_path?(wt[:path], here)
+      reason = detached_merge_reason(wt[:head], base)
+      trim_detached_worktree(wt[:path], reason) if reason
     end
 
     0
@@ -56,15 +108,10 @@ class GitTrim
     end
   end
 
-  # Maps branch name => worktree path for linked worktrees. The first entry
+  # Linked worktrees as {path:, branch:, head:, detached:}. The first entry
   # in `git worktree list` is the main worktree, which is never removable.
   def linked_worktrees
-    entries = %x{git worktree list --porcelain}.split("\n\n")
-    entries.drop(1).each_with_object({}) do |entry, map|
-      path = entry[/^worktree (.+)$/, 1]
-      branch = entry[/^branch refs\/heads\/(.+)$/, 1]
-      map[branch] = path if path && branch
-    end
+    worktree_entries.drop(1)
   end
 
   def find_file(filename, directory=Dir.pwd)
@@ -77,4 +124,268 @@ class GitTrim
       return find_file(filename, File.expand_path("..", directory))
     end
   end
+
+  private
+
+  def read_protected_branches
+    path = find_file(".git-protected-branches")
+    return [] unless path
+    File.read(path).split("\n").collect(&:strip).reject(&:empty?)
+  end
+
+  def worktree_entries
+    %x{git worktree list --porcelain}.split("\n\n").collect do |entry|
+      {
+        path: entry[/^worktree (.+)$/, 1],
+        branch: entry[/^branch refs\/heads\/(.+)$/, 1],
+        head: entry[/^HEAD (\h+)$/, 1],
+        detached: entry.match?(/^detached$/),
+      }
+    end.select { |wt| wt[:path] }
+  end
+
+  def main_worktree_branch
+    worktree_entries.first&.fetch(:branch)
+  end
+
+  def current_worktree
+    git("rev-parse", "--show-toplevel")
+  end
+
+  def same_path?(a, b)
+    return false unless a && b
+    File.realpath(a) == File.realpath(b)
+  rescue SystemCallError
+    a == b
+  end
+
+  def local_branches
+    format = "%(refname:short)%09%(objectname)%09%(upstream:track)"
+    %x{git for-each-ref refs/heads --format=#{Shellwords.escape(format)}}.split("\n").collect do |line|
+      name, tip, track = line.split("\t")
+      { name: name, tip: tip, gone: track.to_s.include?("gone") }
+    end
+  end
+
+  # A Proof when some signal shows the branch is merged into base; :mismatch
+  # when a merged PR exists but the local branch has moved on (already
+  # reported); nil when there's no evidence either way.
+  def merge_proof(branch, base, merged)
+    return Proof.new("merged into #{base}", false) if merged.include?(branch[:name])
+    return Proof.new("squash-merged into #{base} (patch already in #{base})", true) if squash_merged?(base, branch[:tip])
+    github_merge_proof(branch)
+  end
+
+  # Offline squash detection: collapse the branch into one commit on top of
+  # its merge base, then ask `git cherry` whether base already has an
+  # equivalent patch. A leading "-" means it does.
+  def squash_merged?(base, tip)
+    merge_base = git("merge-base", base, tip) or return false
+    tree = git("rev-parse", "#{tip}^{tree}") or return false
+    # Nothing to compare when the branch makes no net change.
+    return false if tree == git("rev-parse", "#{merge_base}^{tree}")
+    tmp = git("commit-tree", tree, "-p", merge_base, "-m", "_", env: TMP_COMMIT_ENV) or return false
+    cherry = git("cherry", base, tmp) or return false
+    cherry.start_with?("-")
+  end
+
+  # Proof from GitHub: a merged PR for this branch name whose head is exactly
+  # the local tip. A merged PR at a different commit is not proof.
+  def github_merge_proof(branch)
+    prs = merged_prs or return nil
+    matching = prs.select { |pr| pr["headRefName"] == branch[:name] }
+    return nil if matching.empty?
+
+    if (pr = matching.find { |candidate| candidate["headRefOid"] == branch[:tip] })
+      return Proof.new("merged PR ##{pr["number"]}", true)
+    end
+
+    pr = matching.first
+    if ancestor?(pr["headRefOid"], branch[:tip])
+      puts "Skipping branch '#{branch[:name]}': it has commits that merged PR ##{pr["number"]} never had"
+    else
+      puts "Skipping branch '#{branch[:name]}': its tip doesn't match the head of merged PR ##{pr["number"]}"
+    end
+    :mismatch
+  end
+
+  def detached_merge_reason(head, base)
+    return nil unless head
+    return "HEAD is in #{base}" if ancestor?(head, base)
+    pr = merged_prs&.find { |candidate| candidate["headRefOid"] == head }
+    "HEAD is the head of merged PR ##{pr["number"]}" if pr
+  end
+
+  def trim_branch(name, proof, worktree_path)
+    if @dry_run
+      if worktree_path && dirty?(worktree_path)
+        puts "Would skip branch '#{name}': worktree at #{worktree_path} has local changes"
+        return
+      end
+      puts "Would remove worktree #{worktree_path} (#{proof.reason})" if worktree_path
+      puts "Would delete branch #{name} (#{proof.reason})"
+      return
+    end
+
+    if worktree_path
+      output = %x{git worktree remove #{Shellwords.escape(worktree_path)} 2>&1}
+      unless $?.success?
+        if output.include?("contains modified or untracked files")
+          puts "Skipping branch '#{name}': worktree at #{worktree_path} has local changes"
+        else
+          puts "Skipping branch '#{name}': could not remove worktree at #{worktree_path}"
+          puts output
+        end
+        return
+      end
+      puts "Removed worktree #{worktree_path}"
+    end
+
+    flag = proof.force ? "-D" : "-d"
+    output = %x{git branch #{flag} #{Shellwords.escape(name)} 2>&1}
+    if $?.success?
+      puts "#{output.strip} [#{proof.reason}]"
+    else
+      puts "Skipping branch '#{name}': could not delete it"
+      puts output
+    end
+  end
+
+  def trim_detached_worktree(path, reason)
+    if @dry_run
+      if dirty?(path)
+        puts "Would skip detached worktree at #{path}: it has local changes"
+      else
+        puts "Would remove detached worktree #{path} (#{reason})"
+      end
+      return
+    end
+
+    output = %x{git worktree remove #{Shellwords.escape(path)} 2>&1}
+    if $?.success?
+      puts "Removed detached worktree #{path} [#{reason}]"
+    elsif output.include?("contains modified or untracked files")
+      puts "Skipping detached worktree at #{path}: it has local changes"
+    else
+      puts "Skipping detached worktree at #{path}: could not remove it"
+      puts output
+    end
+  end
+
+  def dirty?(path)
+    status = git("-C", path, "status", "--porcelain")
+    status.nil? || !status.empty?
+  end
+
+  def ancestor?(commit, descendant)
+    _, _, status = Open3.capture3("git", "merge-base", "--is-ancestor", commit, descendant)
+    status.success?
+  end
+
+  # Stripped stdout of a git command, or nil if it failed.
+  def git(*args, env: {})
+    out, _, status = Open3.capture3(env, "git", *args)
+    out.strip if status.success?
+  end
+
+  # Merged PRs from GitHub as [{"number", "headRefName", "headRefOid"}], or
+  # nil when gh can't give a trustworthy answer. Fetched at most once, and
+  # only if some branch or worktree actually needs it.
+  def merged_prs
+    return @merged_prs if defined?(@merged_prs)
+    @merged_prs = fetch_merged_prs
+  end
+
+  def fetch_merged_prs
+    return nil unless @use_gh
+    return gh_unavailable("gh not installed") unless system("command -v gh >/dev/null 2>&1")
+    return gh_unavailable("no GitHub remote") unless github_remote?
+
+    status, = gh("auth", "status")
+    return gh_unavailable("gh timed out after #{@gh_timeout}s") if status == :timeout
+    unless status&.success?
+      # `auth status` checks the token online and reports a network failure
+      # as an invalid token. `auth token` is offline, so it tells "never
+      # logged in" apart from "logged in but couldn't verify".
+      token_status, = gh("auth", "token")
+      return gh_unavailable("gh not logged in") unless token_status.is_a?(Process::Status) && token_status.success?
+      return gh_unavailable("gh couldn't verify its login (GitHub unreachable or token rejected)")
+    end
+
+    status, out, err = gh("pr", "list", "--state", "merged", "--limit", GH_PR_LIMIT.to_s,
+                          "--json", "number,headRefName,headRefOid")
+    return gh_unavailable("gh timed out after #{@gh_timeout}s") if status == :timeout
+    return gh_unavailable(gh_failure(err)) unless status&.success?
+
+    parse_prs(out) || gh_unavailable("gh returned unparseable output")
+  end
+
+  def gh_unavailable(reason)
+    warn "git-trim: #{reason}; skipping GitHub PR check, using git-only detection"
+    nil
+  end
+
+  def gh_failure(stderr)
+    case stderr
+    when /rate limit/i then "GitHub API rate limit hit"
+    when /could not resolve|no such host|dial tcp|connection refused|network is unreachable|i\/o timeout|tls/i
+      "can't reach GitHub"
+    else "gh pr list failed"
+    end
+  end
+
+  # Raw remote URLs (not insteadOf-rewritten), since gh resolves the repo
+  # from those too.
+  def github_remote?
+    hosts = ["github.com", ENV["GH_HOST"]].compact.reject(&:empty?)
+    urls = git("config", "--get-regexp", '^remote\..*\.url$').to_s.split("\n")
+    urls.any? { |line| hosts.any? { |host| line.include?(host) } }
+  end
+
+  # An error, empty output or a malformed payload is never evidence.
+  def parse_prs(json)
+    prs = JSON.parse(json)
+    return nil unless prs.is_a?(Array)
+    valid = prs.all? do |pr|
+      pr.is_a?(Hash) && pr["headRefName"].is_a?(String) && !pr["headRefName"].empty? &&
+        pr["headRefOid"].is_a?(String) && pr["headRefOid"].match?(/\A(\h{40}|\h{64})\z/)
+    end
+    prs if valid
+  rescue JSON::ParserError
+    nil
+  end
+
+  # Runs gh with no TTY and a hard deadline. Returns [status, stdout, stderr],
+  # with status :timeout if gh was killed, or nil if it couldn't start.
+  def gh(*args)
+    out_r, out_w = IO.pipe
+    err_r, err_w = IO.pipe
+    begin
+      pid = Process.spawn(GH_ENV, "gh", *args, in: File::NULL, out: out_w, err: err_w, pgroup: true)
+    rescue SystemCallError
+      return [nil, "", ""]
+    ensure
+      out_w.close
+      err_w.close
+    end
+
+    readers = [out_r, err_r].collect { |io| Thread.new { io.read } }
+    waiter = Thread.new { Process.wait2(pid).last }
+    status = if waiter.join(@gh_timeout)
+      waiter.value
+    else
+      # Kill the whole process group so children holding the pipes die too.
+      begin
+        Process.kill("KILL", -pid)
+      rescue SystemCallError
+        nil
+      end
+      waiter.join
+      :timeout
+    end
+    [status, *readers.collect(&:value)]
+  ensure
+    out_r&.close
+    err_r&.close
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: git-trim
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Christopher Petersen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 2026-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler