gitflash 0.6.0 → 0.7.0.beta2

data/lib/gitflash/hook/rules.rb

@@ -41,9 +41,9 @@ module Gitflash
       def clean(args, _dir)
         flags = args.select { |arg| arg.start_with?('-') }
         short = short_flags(args)
-        force = flags.include?('--force') || short.include?('f')
-        dry_run = any?(flags, %w[--dry-run --interactive]) || short.match?(/[ni]/)
-        force && !dry_run ? { scope: %w[worktree] } : nil
+        removes = any?(flags, %w[--force --interactive]) || short.match?(/[fi]/)
+        dry_run = flags.include?('--dry-run') || short.include?('n')
+        removes && !dry_run ? { scope: %w[worktree] } : nil
       end
 
       def switch(args, _dir)
@@ -59,7 +59,9 @@ module Gitflash
       end
 
       def branch(args, _dir)
-        return nil unless any?(args, %w[-d -D --delete -f --force -m -M --move -C --copy])
+        changes = any?(args, %w[--delete --force --move --copy]) ||
+                  short_flags(args).match?(/[dDfmMcC]/)
+        return nil unless changes
 
         { scope: %w[branches], branches: args.reject { |arg| arg.start_with?('-') } }
       end

data/lib/gitflash/hook/settings.rb

@@ -49,11 +49,24 @@ module Gitflash
         raise Error.new("#{path} is not valid JSON: #{e.message}", code: 'invalid_settings')
       end
 
-      # The gitflash hook entry in parsed settings, or nil
-      def entry(settings)
-        groups = Array(settings.dig('hooks', 'PreToolUse'))
-        groups.flat_map { |group| Array(group['hooks']) }
-              .find { |hook| hook['command'].to_s.match?(PATTERN) }
+      # The gitflash hook entry for an event (PreToolUse by default) in parsed settings, or nil.
+      # Only groups whose matcher covers the Bash tool count: a gitflash command under another
+      # matcher (Edit, say) never runs for Bash commands.
+      def entry(settings, event = 'PreToolUse')
+        groups = Array(settings.dig('hooks', event))
+        bash = groups.select { |group| bash_matcher?(group['matcher']) }
+        bash.flat_map { |group| Array(group['hooks']) }
+            .find { |hook| hook['command'].to_s.match?(PATTERN) }
+      end
+
+      # Claude Code matches `matcher` against the tool name: empty or `*` is every tool, anything
+      # else is a pattern such as `Bash` or `Bash|Edit`
+      def bash_matcher?(matcher)
+        return true if matcher.to_s.empty? || matcher == '*'
+
+        'Bash'.match?(/\A(?:#{matcher})\z/)
+      rescue RegexpError
+        false
       end
     end
   end

data/lib/gitflash/hook_cli.rb

@@ -14,7 +14,12 @@ module Gitflash
       true
     end
 
-    desc 'claude', 'Run as a Claude Code PreToolUse hook (reads the hook input on stdin)'
+    TERMINAL_NOTE = 'gitflash hook claude is run by Claude Code, not by hand. Use ' \
+                    '`gitflash hook install` to set it up and `gitflash hook status` to check it.'
+
+    desc 'claude',
+         'Run as a Claude Code hook (PreToolUse and PostToolUse; reads the input on stdin)',
+         hide: true
     long_desc <<~TEXT
       Reads the Claude Code hook input on stdin. When the Bash command can discard work git
       cannot restore (for example reset --hard, clean -f, checkout -- ., branch -D, stash drop),
@@ -24,10 +29,17 @@ module Gitflash
       --mode ask       save a snapshot and ask the user to approve the command
       --mode deny      block the command and point to the gitflash equivalent
 
-      Errors never block the command: they are printed to stderr and the hook exits with 0.
+      As a PostToolUse hook it marks the branches the command created (git checkout -b, switch -c,
+      branch NAME, worktree add) as agent work, so `gitflash clean --agent` can find them. A branch
+      is only marked when it is new (its reflog says it was created a moment ago) and unmarked.
+
+      Not meant to be run by hand: in a terminal it only prints a note. Errors never block the
+      command: they are printed to stderr and the hook exits with 0.
     TEXT
     option :mode, type: :string, default: 'snapshot', enum: Hook::Claude::MODES
     def claude
+      return puts(TERMINAL_NOTE) if $stdin.tty?
+
       output = Hook::Claude.new(mode: options[:mode]).call($stdin.read)
       puts JSON.generate(output) if output
     rescue StandardError => e
@@ -36,8 +48,10 @@ module Gitflash
 
     desc 'install', 'Register the gitflash hook in Claude Code settings'
     long_desc <<~TEXT
-      Adds `gitflash hook claude` as a PreToolUse hook for Bash commands. Keeps the rest of the
-      settings file unchanged and does nothing when the hook is already installed.
+      Adds `gitflash hook claude` as a PreToolUse hook (snapshots before destructive commands) and
+      as a PostToolUse hook (marks branches an agent creates) for Bash commands. Keeps the rest of
+      the settings file unchanged and does nothing when both are already installed. Run it again
+      to add the PostToolUse hook to an older install.
 
       --scope local    .claude/settings.local.json at the repository root (default, not
                        committed); applies to sessions anywhere in the repository and its worktrees
@@ -59,7 +73,8 @@ module Gitflash
     desc 'status', 'Show whether the gitflash hook protects Claude Code sessions here'
     long_desc <<~TEXT
       Lists the Claude Code settings files that apply to the current directory, whether each
-      holds the gitflash hook and which sessions it applies to, and whether the gitflash
+      holds the gitflash hooks (and whether branch marking is on) and which sessions it applies to,
+      and whether the gitflash
       executable the hook runs is on PATH. Works outside a git repository (user scope only).
     TEXT
     def status

data/lib/gitflash/ownership.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Who created a branch: `agent` or `human`. Stored in git config as
+  # `branch.<name>.gitflash-owner`, which git removes together with the branch.
+  # A branch without a mark counts as human work and is never selected for automatic cleanup.
+  class Ownership
+    OWNERS = %w[agent human].freeze
+    SUFFIX = '.gitflash-owner'
+    PREFIX = 'branch.'
+
+    def initialize(bash: Git::BashCommand)
+      @bash = bash
+    end
+
+    # { branch name => owner } for every marked branch
+    def all
+      stdout, _stderr, success = @bash.capture('git', 'config', '--local', '-z', '--get-regexp',
+                                               '^branch\..+\.gitflash-owner$')
+      return {} unless success
+
+      stdout.split("\0").filter_map { |entry| parse(entry) }.to_h
+    end
+
+    # The branches with their `owner` set from the marks
+    def annotate(branches)
+      owners = all
+      branches.map { |branch| branch.with(owner: owners[branch.name]) }
+    end
+
+    def mark(branch, owner)
+      unless OWNERS.include?(owner)
+        raise UsageError.new("Unknown owner '#{owner}' (use #{OWNERS.join(' or ')})",
+                             code: 'invalid_usage')
+      end
+
+      @bash.exec('git', 'config', '--local', key(branch), owner)
+    end
+
+    # Removes the mark; a branch without a mark is already unmarked
+    def clear(branch)
+      @bash.capture('git', 'config', '--local', '--unset', key(branch))
+    end
+
+    private
+
+    def key(branch)
+      "#{PREFIX}#{branch}#{SUFFIX}"
+    end
+
+    # Entry from `-z`: "branch.<name>.gitflash-owner\nvalue". Branch names may contain dots.
+    def parse(entry)
+      full_key, value = entry.split("\n", 2)
+      return nil unless full_key.start_with?(PREFIX) && full_key.end_with?(SUFFIX)
+
+      [full_key.delete_prefix(PREFIX).delete_suffix(SUFFIX), value.to_s.strip]
+    end
+  end
+end

data/lib/gitflash/protection.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Branches gitflash never deletes: the current and default branch, `main`, `master`, names
+  # matching `protected` in the settings, and any branch checked out in a worktree.
+  class Protection
+    NAMES = %w[main master].freeze
+
+    def initialize(config:, checked_out: [])
+      @config = config
+      @checked_out = checked_out
+    end
+
+    def protected?(branch)
+      branch.current? || branch.default? || NAMES.include?(branch.name) ||
+        @config.protected?(branch.name) || @checked_out.include?(branch.name)
+    end
+  end
+end

data/lib/gitflash/repo.rb

@@ -30,9 +30,8 @@ module Gitflash
     # merged into the default branch (one extra git call).
     def branches(merged_status: false)
       merged_names = merged_status ? merged_branch_names : nil
-      branch_lines.map do |line|
-        Branch.parse(line, default_branch: default_branch, merged_names: merged_names)
-      end
+      list = branch_lines.map { |line| Branch.parse(line, default_branch:, merged_names:) }
+      Ownership.new(bash: @bash).annotate(list)
     end
 
     def current_branch
@@ -40,12 +39,13 @@ module Gitflash
     end
 
     def toplevel
-      @bash.exec('git', 'rev-parse', '--show-toplevel').strip
+      @bash.exec('git', 'rev-parse', '--show-toplevel').delete_suffix("\n")
     end
 
     # Root of the main checkout; differs from toplevel inside a linked worktree
     def main_root
-      common = @bash.exec('git', 'rev-parse', '--path-format=absolute', '--git-common-dir').strip
+      common = @bash.exec('git', 'rev-parse', '--path-format=absolute',
+                          '--git-common-dir').delete_suffix("\n")
       File.basename(common) == '.git' ? File.dirname(common) : toplevel
     end
 

data/lib/gitflash/restore.rb

@@ -20,17 +20,18 @@ module Gitflash
       }
     end
 
+    # Parts of the state this restore changes; the state before an undo is saved with the same
+    def scope = @snapshot.scope
+
     def empty?
       plan[:branches].empty? && plan[:head].nil? && !plan[:worktree] && plan[:stashes].empty?
     end
 
-    # Applies the plan; returns nil on success or the failed step's Result
-    def apply
-      steps.each do |args|
-        result = run(*args)
-        return result unless result.success?
-      end
-      nil
+    # Applies the plan (`only: :branches` just the branch tips); returns nil on success or the
+    # failed step's Result
+    def apply(only: nil)
+      (only == :branches ? branch_steps : steps).lazy.map { |args| run(*args) }
+                                                .find { |result| !result.success? }
     end
 
     private

data/lib/gitflash/state_capture.rb

@@ -48,13 +48,15 @@ module Gitflash
     private
 
     def git(*, env: {})
-      @bash.exec('git', *, env: env).strip
+      # Only git's final newline goes: a path may start or end with whitespace, even a carriage
+      # return, which `chomp` would take together with the newline
+      @bash.exec('git', *, env: env).delete_suffix("\n")
     end
 
     # Stripped stdout, or nil when the command fails
     def try(*)
       stdout, _stderr, success = @bash.capture('git', *)
-      success ? stdout.strip : nil
+      success ? stdout.delete_suffix("\n") : nil
     end
 
     def rev(ref)
@@ -93,9 +95,9 @@ module Gitflash
     # Tree of the working tree, built in a temporary copy of the index so the real one is untouched
     def worktree_tree
       top = git('rev-parse', '--show-toplevel')
-      Tempfile.create('gitflash-index', File.expand_path(git('rev-parse', '--git-dir'))) do |file|
+      Tempfile.create('gitflash-index', git('rev-parse', '--absolute-git-dir')) do |file|
         file.close
-        real_index = File.expand_path(git('rev-parse', '--git-path', 'index'))
+        real_index = git('rev-parse', '--path-format=absolute', '--git-path', 'index')
         FileUtils.cp(real_index, file.path) if File.exist?(real_index)
         env = { 'GIT_INDEX_FILE' => file.path }
 
@@ -122,7 +124,10 @@ module Gitflash
       sizes = file_sizes(top, paths)
       small, large = sizes.partition { |_path, size| size <= MAX_UNTRACKED_FILE_BYTES }
                           .map { |group| group.map(&:first) }
-      small.each_slice(ADD_BATCH_SIZE) { |batch| git('-C', top, 'add', '--', *batch, env: env) }
+      # File names are literal paths, never pathspec magic such as `:(exclude)*`
+      small.each_slice(ADD_BATCH_SIZE) do |batch|
+        git('--literal-pathspecs', '-C', top, 'add', '--', *batch, env: env)
+      end
       large
     end
   end

data/lib/gitflash/terminal_text.rb

@@ -15,5 +15,14 @@ module Gitflash
         format(char.ord > 0xFF ? '\\u%04X' : '\\x%02X', char.ord)
       end
     end
+
+    # Text that must stay on one line, such as a path inside a bullet list: as `safe`, and a
+    # newline or tab in it is shown as an escape too, so it cannot start a fake row. A literal
+    # backslash is doubled first, so two different texts never look the same (a real newline
+    # shows as `\n`, the two characters backslash and n as `\\n`); that keeps menu labels unique.
+    def line(text)
+      doubled = text.to_s.scrub.gsub('\\') { '\\\\' }
+      safe(doubled).gsub("\n") { '\\n' }.gsub("\t") { '\\t' }
+    end
   end
 end

data/lib/gitflash/ui.rb

@@ -69,7 +69,7 @@ module Gitflash
       message = "#{summary}\nRe-run with --yes to confirm."
       raise ConfirmationRequired.new(message, plan: plan) unless interactive?
 
-      prompt.proceed_with_warning(summary) { true } == true
+      prompt.proceed_with_warning(TerminalText.safe(summary)) { true } == true
     end
 
     private

data/lib/gitflash/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gitflash
-  VERSION = '0.6.0'
+  VERSION = '0.7.0.beta2'
 end

data/lib/gitflash/worktree.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # A checkout of the repository as reported by `git worktree list --porcelain`.
+  # `branch` is nil for a detached HEAD. `missing` means the directory is gone (git calls it
+  # prunable). `dirty` is nil when it cannot be known (missing directory or bare repository).
+  # ahead, behind, merged and owner are those of the branch, nil without a branch.
+  Worktree = Data.define(
+    :path, :head, :branch, :main, :bare, :locked, :lock_reason, :missing,
+    :dirty, :ahead, :behind, :merged, :owner
+  ) do
+    alias_method :main?, :main
+    alias_method :locked?, :locked
+    alias_method :missing?, :missing
+    alias_method :dirty?, :dirty
+
+    # Why this worktree must not be removed, nil when it can go. `current` is true for the
+    # worktree gitflash runs in. The main checkout and the current one are never removable.
+    def removal_blocker(force:, current:)
+      return "#{TerminalText.line(path)} is the main checkout" if main?
+      return "#{TerminalText.line(path)} is the current worktree" if current
+
+      in_use_blocker unless force || (missing? && !locked?)
+    end
+
+    def in_use_blocker
+      return "#{TerminalText.line(path)} is locked (use --force)" if locked?
+
+      "#{TerminalText.line(path)} has uncommitted changes (use --force)" if dirty? != false
+    end
+  end
+end

data/lib/gitflash/worktree_cli.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Gitflash
+  # `gitflash worktree ...` (alias `wt`): worktrees for parallel agent work
+  class WorktreeCli < Thor
+    extend Configuration::Descriptions
+    include CommandRunner
+
+    namespace 'worktree'
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'list', 'List worktrees with branch, dirty and merge state'
+    long_desc <<~TEXT
+      Lists every worktree of the repository: absolute path, branch, HEAD, whether it has
+      uncommitted changes, ahead/behind counts, whether its branch is merged into the default
+      branch, lock state and whether its directory is missing.
+
+      Agents use the absolute paths from `--json`; no directory switching is needed.
+
+      Accepts the global --json option after the subcommand: gitflash wt list --json
+    TEXT
+    def list
+      run_command('worktree list', Commands::WorktreeList)
+    end
+
+    desc 'add BRANCH', 'Add a worktree for a branch (existing, remote or new)'
+    long_desc <<~TEXT
+      Adds a worktree for BRANCH. An existing local branch is checked out; a branch that exists
+      only on origin is created to track it; any other name creates a new branch from HEAD
+      (or from --from). New branches are marked as agent work so `gitflash clean` can find them.
+
+      The directory defaults to ../<repo>.worktrees/<branch> (setting `worktree_dir` in
+      .gitflash.yml changes it). The result lists the absolute path: use it, no directory
+      switching is needed.
+
+      Needs no confirmation. Accepts the global --json and --dry-run options after the
+      subcommand: gitflash wt add feature --json
+    TEXT
+    option :path, type: :string, banner: 'DIR', desc: 'Directory for the worktree'
+    option :from, type: :string, banner: 'REF', desc: 'Start a new branch from REF (default HEAD)'
+    option :owner, type: :string, enum: Ownership::OWNERS,
+                   desc: 'Mark a new branch as agent (default) or human work'
+    def add(branch = nil)
+      run_command('worktree add', Commands::WorktreeAdd, *[branch].compact)
+    end
+
+    desc 'lock WORKTREE', 'Lock a worktree so prune, remove and clean leave it alone'
+    long_desc 'Locks the worktree given as a path or branch. Add --reason to say why.'
+    option :reason, type: :string, desc: 'Why the worktree is locked'
+    def lock(worktree = nil)
+      run_command('worktree lock', Commands::WorktreeLock, *[worktree].compact)
+    end
+
+    desc 'unlock WORKTREE', 'Unlock a worktree'
+    def unlock(worktree = nil)
+      run_command('worktree unlock', Commands::WorktreeUnlock, *[worktree].compact)
+    end
+
+    desc 'move WORKTREE PATH', 'Move a worktree to another directory'
+    long_desc <<~TEXT
+      Moves the worktree (a path or branch) to PATH. The main checkout and the current worktree
+      cannot be moved; a locked worktree needs --force.
+    TEXT
+    option :force, type: :boolean, default: false, desc: 'Also move a locked worktree'
+    def move(worktree = nil, destination = nil)
+      run_command('worktree move', Commands::WorktreeMove, *[worktree, destination].compact)
+    end
+
+    desc 'prune', 'Forget worktrees whose directory is gone'
+    long_desc <<~TEXT
+      Removes git's record of worktrees whose directory no longer exists. Locked worktrees stay.
+      Branches are not touched. Asks for confirmation; pass --yes to skip it, or --dry-run.
+    TEXT
+    def prune
+      run_command('worktree prune', Commands::WorktreePrune)
+    end
+
+    desc 'clean', 'Remove worktrees whose branch is merged, gone, stale or agent-created'
+    long_desc <<~TEXT
+      Removes worktrees whose branch matches the criteria of `gitflash clean`: merged into the
+      default branch or upstream gone by default, plus --stale [DAYS] and --agent. The main
+      checkout, the current worktree and worktrees on protected branches are never removed;
+      locked worktrees and worktrees with uncommitted changes are skipped (and listed with the
+      reason) unless --force is given.
+
+      Each removal saves a snapshot first, as `wt remove` does. Branches are kept: run
+      `gitflash clean` afterwards to delete them. Missing directories are handled by `wt prune`.
+
+      Asks for confirmation; pass --yes to skip it, or --dry-run.
+    TEXT
+    option :merged, type: :boolean, desc: 'Branches merged into the default branch'
+    option :gone, type: :boolean, desc: 'Branches whose upstream branch was deleted'
+    option :stale, type: :string, banner: 'DAYS', lazy_default: '',
+                   desc: 'Branches without commits for DAYS days (default: stale_days setting)'
+    option :agent, type: :boolean, desc: 'Branches created by an agent'
+    option :force, type: :boolean, default: false,
+                   desc: 'Also remove locked worktrees and worktrees with uncommitted changes'
+    def clean
+      run_command('worktree clean', Commands::WorktreeClean)
+    end
+
+    desc 'remove [WORKTREE...]', 'Remove worktrees (paths or branch names), saving a snapshot first'
+    long_desc descriptions.worktree_remove.long
+    option :force, type: :boolean, default: false,
+                   desc: 'Remove locked worktrees and worktrees with uncommitted changes'
+    def remove(*worktrees)
+      run_command('worktree remove', Commands::WorktreeRemove, *worktrees)
+    end
+  end
+end

data/lib/gitflash/worktree_revival.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Brings back a worktree that was removed after a snapshot of it: adds the worktree again on
+  # its branch (or detached HEAD) and restores its files. Branch tips are restored before the
+  # worktree is added, so a branch deleted or moved since is checked out at its saved tip and its
+  # files always match it.
+  class WorktreeRevival
+    def initialize(snapshot, repo:)
+      @snapshot = snapshot
+      @repo = repo
+    end
+
+    # Same shape as an undo plan, plus `recreate_worktree`
+    def plan
+      head = @snapshot.head
+      { branches: Restore.new(@snapshot).plan[:branches],
+        head: { from: nil, to: head[:branch] || head[:sha] },
+        worktree: !@snapshot.worktree.nil?, stashes: [], snapshot: @snapshot.id,
+        recreate_worktree: @snapshot.worktree_path }
+    end
+
+    def scope
+      %w[branches]
+    end
+
+    def empty?
+      false
+    end
+
+    # Returns nil on success or the failed step's Result
+    def apply
+      failure = Restore.new(@snapshot).apply(only: :branches)
+      return failure if failure
+
+      result = attach
+      return result unless result.success?
+
+      restore = Restore.new(@snapshot, bash: Git::InDirectory.new(@snapshot.worktree_path))
+      restore.apply
+    end
+
+    private
+
+    def attach
+      worktrees = Worktrees.new(repo: @repo)
+      path = @snapshot.worktree_path
+      branch = @snapshot.head[:branch]
+      sha = @snapshot.head[:sha]
+      return worktrees.attach(path, detach_at: sha) unless branch
+
+      worktrees.attach(path, branch: branch, create_at: sha)
+    end
+  end
+end