gitflash 0.6.0 → 0.7.0.beta2

data/lib/gitflash/config.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Gitflash
+  # Settings from `.gitflash.yml` in the main checkout and `~/.config/gitflash.yml`.
+  # Precedence: repository file, then user file, then built-in defaults.
+  # Command-line flags are applied by the commands themselves and win over all of these.
+  # An unknown key or a value of the wrong type raises a UsageError, so a typo never goes unnoticed.
+  Config = Data.define(:protected_patterns, :stale_days, :worktree_dir) do
+    # `root` is the main checkout; `home` is where the user file lives. The repository file wins
+    # key by key, except `protected`: both files add patterns, so a repository can protect more
+    # branches but never remove what the user protects.
+    def self.load(root:, home: Dir.home)
+      layers = [File.join(home, ConfigKeys::USER_FILE), File.join(root, ConfigKeys::REPO_FILE)]
+               .map { |path| read(path) }
+      values = layers.reduce(ConfigKeys::DEFAULTS) { |merged, layer| merged.merge(layer) }
+      new(protected_patterns: layers.flat_map { |layer| layer.fetch('protected', []) }.uniq,
+          stale_days: values['stale_days'], worktree_dir: values['worktree_dir'])
+    end
+
+    def self.defaults
+      new(protected_patterns: [], stale_days: 30, worktree_dir: ConfigKeys::DEFAULT_WORKTREE_DIR)
+    end
+
+    def self.read(path)
+      return {} unless File.file?(path)
+
+      reject_duplicate_keys!(path)
+      data = YAML.safe_load_file(path) || {}
+      validate!(data, path)
+      data
+    rescue Psych::Exception, SystemCallError, IOError => e
+      raise invalid(path, "cannot be read (#{e.message.lines.first.strip})")
+    end
+    private_class_method :read
+
+    # A YAML loader keeps only the last of two equal keys, which could drop a `protected` list
+    def self.reject_duplicate_keys!(path)
+      root = Psych.parse_file(path)
+      return unless root
+
+      duplicate = duplicate_key(root)
+      raise invalid(path, "has the key '#{duplicate}' more than once") if duplicate
+    end
+    private_class_method :reject_duplicate_keys!
+
+    def self.duplicate_key(node)
+      own = node.is_a?(Psych::Nodes::Mapping) ? own_duplicate(node) : nil
+      own || (node.children || []).filter_map { |child| duplicate_key(child) }.first
+    end
+    private_class_method :duplicate_key
+
+    def self.own_duplicate(mapping)
+      keys = mapping.children.each_slice(2).filter_map do |key, _value|
+        key.value if key.respond_to?(:value)
+      end
+      keys.tally.find { |_key, count| count > 1 }&.first
+    end
+    private_class_method :own_duplicate
+
+    def self.validate!(data, path)
+      raise invalid(path, 'must be a mapping') unless data.is_a?(Hash)
+
+      unknown = data.keys - ConfigKeys::DEFAULTS.keys
+      raise invalid(path, "has unknown keys: #{unknown.join(', ')}") if unknown.any?
+
+      check_types!(data, path)
+    end
+    private_class_method :validate!
+
+    def self.check_types!(data, path)
+      data.each do |key, value|
+        check, expected = ConfigKeys::CHECKS.fetch(key)
+        raise invalid(path, "'#{key}' must be #{expected}") unless check.call(value)
+      end
+    end
+    private_class_method :check_types!
+
+    def self.invalid(path, problem)
+      UsageError.new("#{path} #{problem}", code: 'invalid_config')
+    end
+    private_class_method :invalid
+
+    # True when the branch name matches a configured pattern (shell-style `*` and `?`)
+    def protected?(name)
+      protected_patterns.any? { |pattern| File.fnmatch?(pattern, name) }
+    end
+
+    # Directory for a new worktree. `%<repo>s` and `%<branch>s` are replaced as plain text; a
+    # relative path is resolved against the main checkout. Slashes in a branch name stay as
+    # folders.
+    def worktree_path(root:, branch:)
+      path = worktree_dir.gsub('%<repo>s') { File.basename(root) }.gsub('%<branch>s') { branch }
+      File.expand_path(path, root)
+    end
+  end
+end

data/lib/gitflash/config_keys.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Built-in defaults, files and the check each key must pass
+  module ConfigKeys
+    REPO_FILE = '.gitflash.yml'
+    USER_FILE = File.join('.config', 'gitflash.yml')
+    DEFAULT_WORKTREE_DIR = '../%<repo>s.worktrees/%<branch>s'
+    DEFAULTS = {
+      'protected' => [], 'stale_days' => 30, 'worktree_dir' => DEFAULT_WORKTREE_DIR
+    }.freeze
+    PLACEHOLDERS = ['%<repo>s', '%<branch>s'].freeze
+    MAX_TEMPLATE_LENGTH = 512
+    CHECKS = {
+      'protected' => [->(v) { v.is_a?(Array) && v.all?(String) },
+                      'a list of branch name patterns'],
+      'stale_days' => [->(v) { v.is_a?(Integer) && v.positive? }, 'a positive whole number'],
+      'worktree_dir' => [->(v) { template?(v) },
+                         'a path of up to 512 characters that uses only %<repo>s and %<branch>s']
+    }.freeze
+
+    # A path template: the two placeholders are the only `%` directives, so a width such as
+    # `%<repo>999999999s` can never make Ruby build a huge string
+    def self.template?(value)
+      return false unless value.is_a?(String)
+      return false if value.empty? || value.length > MAX_TEMPLATE_LENGTH
+
+      !PLACEHOLDERS.reduce(value) { |rest, placeholder| rest.gsub(placeholder, '') }.include?('%')
+    end
+  end
+end

data/lib/gitflash/git/bash_command.rb

@@ -16,9 +16,12 @@ module Gitflash
         end
 
         # Runs a command without a shell and returns [stdout, stderr, success].
-        # `env` adds environment variables for this command only.
+        # `env` adds environment variables for this command only. The executable is passed as a
+        # pair, which keeps Ruby from handing a lone string to a shell.
         def capture(*args, env: {})
-          stdout, stderr, status = Open3.capture3(env, *args)
+          raise CommandError, 'no command given' if args.empty?
+
+          stdout, stderr, status = Open3.capture3(env, [args.first, args.first], *args.drop(1))
           [stdout, stderr, status.success?]
         rescue SystemCallError => e
           raise CommandError, "#{args.join(' ')} failed: #{e.message}"

data/lib/gitflash/git/in_directory.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Git
+    # Runs every git command inside another directory (`git -C DIR ...`). It has the same
+    # interface as BashCommand, so StateCapture, Snapshots and Restore can work on a linked
+    # worktree without knowing about it.
+    class InDirectory
+      def initialize(path, bash: BashCommand)
+        @path = path
+        @bash = bash
+      end
+
+      def exec(*args, env: {})
+        @bash.exec(*scoped(args), env: env)
+      end
+
+      def capture(*args, env: {})
+        @bash.capture(*scoped(args), env: env)
+      end
+
+      private
+
+      def scoped(args)
+        args.first == 'git' ? ['git', '-C', @path, *args.drop(1)] : args
+      end
+    end
+  end
+end

data/lib/gitflash/hook/branch_marker.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+require 'tmpdir'
+
+module Gitflash
+  module Hook
+    # Marks the branches an agent just created as agent work (see Ownership), so
+    # `gitflash clean --agent` can find them. Runs in the PostToolUse hook, after the command:
+    # the branch exists then, and Claude Code only runs it when the command succeeded.
+    #
+    # Text in a command proves nothing (`false && git branch x` creates nothing), so a branch is
+    # only marked when it is new:
+    # - the PreToolUse hook records which of the branches the command names exist before it runs
+    #   (`record`), and a branch that existed then is never marked;
+    # - its reflog must say it was created a moment ago ("branch: Created from ..."), which also
+    #   covers a Claude Code that ran no PreToolUse hook;
+    # - it must be unmarked.
+    class BranchMarker
+      CREATED = 'branch: Created from'
+      RECENT_SECONDS = 120
+      STALE_RECORD_SECONDS = 24 * 60 * 60
+
+      def initialize(clock: -> { Time.now }, state_dir: nil)
+        @clock = clock
+        @state_dir = state_dir || File.join(Dir.tmpdir, "gitflash-hook-#{Process.uid}")
+      end
+
+      # PreToolUse: remember the branches the command may create that exist already
+      def record(command, cwd, tool_use_id)
+        creations = CommandParser.new(cwd).creations(command)
+        return if creations.empty? || (path = record_path(tool_use_id)).nil?
+        return unless private_state_dir?
+
+        prune_records
+        File.write(path, JSON.generate(existing_stamps(creations)))
+      end
+
+      # PostToolUse: branch names marked as agent work, in the directories the command ran in
+      def call(command, cwd, tool_use_id = nil)
+        existed = take_record(tool_use_id)
+        created = CommandParser.new(cwd).creations(command)
+        created.reject { |creation| already_there?(existed, creation) }
+               .select { |creation| mark(creation[:dir], creation[:branch]) }
+               .map { |creation| creation[:branch] }.uniq
+      end
+
+      private
+
+      # { key => stamp } of the named branches that exist now
+      def existing_stamps(creations)
+        existing = creations.select { |creation| branch_exists?(creation[:dir], creation[:branch]) }
+        existing.to_h { |creation| [key(creation), stamp(creation)] }
+      end
+
+      def key(creation)
+        "#{creation[:dir]}\0#{creation[:branch]}"
+      end
+
+      # A branch that was there before the command and is the same branch now. One that the
+      # command deleted and created again has a new reflog, so a new stamp, and counts as new.
+      # An empty stamp (no reflog) is no evidence of a new branch either: all that is known is
+      # that the branch existed, and claiming a branch a person may have made is the worse
+      # mistake, so it is left alone. Without a reflog nothing could be marked in any case.
+      def already_there?(existed, creation)
+        existed.key?(key(creation)) && existed[key(creation)] == stamp(creation)
+      end
+
+      # Time, commit and message of the oldest reflog entry, which is the creation of the branch;
+      # empty when the reflog is off
+      def stamp(creation)
+        return '' unless Dir.exist?(creation[:dir])
+
+        stdout, _stderr, success = Git::BashCommand.capture(
+          'git', '-C', creation[:dir], 'log', '-g', '--format=%ct %H %gs',
+          "#{Repo::HEADS}#{creation[:branch]}", '--'
+        )
+        success ? stdout.lines(chomp: true).last.to_s : ''
+      end
+
+      # One file per tool call, named from a hash so the id can never form a path
+      def record_path(tool_use_id)
+        return nil if tool_use_id.to_s.empty?
+
+        File.join(@state_dir, "#{Digest::SHA256.hexdigest(tool_use_id.to_s)}.json")
+      end
+
+      def take_record(tool_use_id)
+        path = record_path(tool_use_id)
+        return {} unless path && private_state_dir? && File.file?(path)
+
+        record = JSON.parse(File.read(path))
+        record.is_a?(Hash) ? record : {}
+      rescue JSON::ParserError
+        {}
+      ensure
+        FileUtils.rm_f(path) if path
+      end
+
+      # The directory holds the records of this user only: created with mode 0700, and refused
+      # when it is a link, belongs to someone else or is open to the group or others (a shared
+      # /tmp lets another user create the name first)
+      def private_state_dir?
+        FileUtils.mkdir_p(@state_dir, mode: 0o700)
+        stat = File.lstat(@state_dir)
+        stat.directory? && stat.owned? && stat.mode.nobits?(0o077)
+      rescue SystemCallError
+        false
+      end
+
+      # Another hook may delete a record at the same moment: a vanished file is not an error
+      def prune_records
+        Dir.glob(File.join(@state_dir, '*.json')).each do |file|
+          FileUtils.rm_f(file) if @clock.call - File.mtime(file) > STALE_RECORD_SECONDS
+        rescue SystemCallError
+          next
+        end
+      end
+
+      def branch_exists?(dir, branch)
+        return false unless Dir.exist?(dir)
+
+        _stdout, _stderr, success = Git::BashCommand.capture(
+          'git', '-C', dir, 'show-ref', '--verify', '--quiet', "#{Repo::HEADS}#{branch}"
+        )
+        success
+      end
+
+      def mark(dir, branch)
+        return false unless Dir.exist?(dir)
+
+        Dir.chdir(dir) do
+          ownership = Ownership.new
+          next false unless created_recently?(branch) && !ownership.all.key?(branch)
+
+          ownership.mark(branch, 'agent')
+          true
+        end
+      end
+
+      # The oldest reflog entry of the branch is its creation, and it is recent
+      def created_recently?(branch)
+        stdout, _stderr, success = Git::BashCommand.capture(
+          'git', 'log', '-g', '--format=%ct%x1f%gs', "#{Repo::HEADS}#{branch}", '--'
+        )
+        return false unless success
+
+        created, subject = stdout.lines(chomp: true).last.to_s.split("\x1f", 2)
+        subject.to_s.start_with?(CREATED) && @clock.call.to_i - created.to_i <= RECENT_SECONDS
+      end
+    end
+  end
+end

data/lib/gitflash/hook/claude.rb

@@ -4,7 +4,8 @@ require 'json'
 
 module Gitflash
   module Hook
-    # Claude Code PreToolUse hook for the Bash tool.
+    # Claude Code hook for the Bash tool. PostToolUse input marks the branches the command
+    # created as agent work (BranchMarker); everything below describes PreToolUse.
     #
     # Reads the hook input (JSON on stdin) and, when the command can lose work git cannot
     # restore, acts according to the mode:
@@ -15,28 +16,70 @@ module Gitflash
     class Claude
       MODES = %w[snapshot ask deny].freeze
       EVENT = 'PreToolUse'
+      POST_EVENT = 'PostToolUse'
 
-      def initialize(mode: 'snapshot', snapshots: -> { Gitflash::Snapshots.new })
+      def initialize(mode: 'snapshot', snapshots: -> { Gitflash::Snapshots.new },
+                     marker: BranchMarker.new)
         @mode = mode
         @snapshots = snapshots
+        @marker = marker
       end
 
       def call(input)
-        targets = targets(JSON.parse(input))
+        data = JSON.parse(input)
+        return after_command(data) if data['hook_event_name'] == POST_EVENT
+
+        before_command(data)
+      end
+
+      private
+
+      # PreToolUse: remember which branches exist, then snapshot, ask or deny for risky commands
+      def before_command(data)
+        record_branches(data)
+        targets = targets(data)
         return nil if targets.empty?
         return deny(targets) if @mode == 'deny'
 
         saved = merge_by_dir(targets).filter_map { |target| save(target) }
-        saved.empty? ? nil : output(saved)
+        # Asking is the user's protection: it must not depend on a snapshot having been saved
+        saved.empty? && @mode != 'ask' ? nil : output(saved, targets)
       end
 
-      private
+      # Recording is a side feature: when it fails, snapshots and the ask or deny decision still run
+      def record_branches(data)
+        return unless bash?(data)
+
+        @marker.record(command_of(data), data['cwd'] || Dir.pwd, data['tool_use_id'])
+      rescue StandardError => e
+        warn "gitflash hook: could not record branches (#{e.message})"
+      end
+
+      # PostToolUse: mark the branches the command created, and tell Claude
+      def after_command(data)
+        return nil unless data['tool_name'] == 'Bash'
+
+        marked = @marker.call(command_of(data), data['cwd'] || Dir.pwd, data['tool_use_id'])
+        return nil if marked.empty?
+
+        context = "gitflash marked #{marked.join(', ')} as agent work, so " \
+                  '`gitflash clean --agent` can find it. Change it with ' \
+                  '`gitflash mark BRANCH --owner human`.'
+        { hookSpecificOutput: { hookEventName: POST_EVENT, additionalContext: context } }
+      end
+
+      def bash?(data)
+        data['tool_name'] == 'Bash'
+      end
+
+      def command_of(data)
+        data.dig('tool_input', 'command').to_s
+      end
 
       def targets(data)
-        return [] unless data['tool_name'] == 'Bash'
+        return [] unless bash?(data)
 
-        command = data.dig('tool_input', 'command').to_s
-        CommandParser.new(data['cwd'] || Dir.pwd).targets(command)
+        CommandParser.new(data['cwd'] || Dir.pwd).targets(command_of(data))
       end
 
       # One snapshot per directory, covering every command run there
@@ -73,11 +116,8 @@ module Gitflash
         end
       end
 
-      def output(saved)
-        notes = saved.map { |target, snap| "snapshot #{snap.id} before `#{target.command}`" }
-        context = "gitflash saved #{notes.join('; ')}. If this discards work that was still " \
-                  "needed, restore it with `gitflash undo #{saved.last[1].id}` " \
-                  '(list snapshots with `gitflash snapshots`).'
+      def output(saved, targets)
+        context = saved.empty? ? Messages.unsaved(targets) : Messages.saved(saved)
         specific = { hookEventName: EVENT, additionalContext: context }
         if @mode == 'ask'
           specific[:permissionDecision] = 'ask'
@@ -88,12 +128,8 @@ module Gitflash
       end
 
       def deny(targets)
-        commands = targets.map { |target| "`#{target.command}`" }.join(', ')
-        reason = "gitflash blocked #{commands}: it can discard work git cannot restore. " \
-                 'Use the gitflash equivalent (gitflash reset, gitflash delete, ...), which ' \
-                 'saves a snapshot first, or run `gitflash snapshot` before retrying.'
         { hookSpecificOutput: { hookEventName: EVENT, permissionDecision: 'deny',
-                                permissionDecisionReason: reason } }
+                                permissionDecisionReason: Messages.denial(targets) } }
       end
 
       # Stripped stdout of a git command, or nil when it fails

data/lib/gitflash/hook/command_parser.rb

@@ -17,27 +17,68 @@ module Gitflash
       Target = Data.define(:dir, :command, :scope, :branches)
 
       PREFIXES = %w[sudo command exec time nohup env].freeze
+      SHELLS = %w[bash sh zsh dash ksh].freeze
+      MAX_NESTING = 3
       OPTIONS_WITH_VALUE = %w[-c --git-dir --work-tree --namespace --exec-path --config-env].freeze
 
       def initialize(cwd)
         @cwd = cwd
       end
 
+      # Git commands that can lose work, with what to save before them
       def targets(command_line)
-        dir = @cwd
-        segments(command_line).filter_map do |segment|
+        git_commands(command_line).filter_map do |git|
+          rule = Rules.for(git.subcommand, git.args, git.dir)
+          next unless rule
+
+          Target.new(dir: rule.fetch(:dir, git.dir), command: git.command, scope: rule[:scope],
+                     branches: rule[:branches] || [])
+        end
+      end
+
+      # Branches that git commands in the line create, as { dir:, branch: }
+      def creations(command_line)
+        git_commands(command_line).filter_map do |git|
+          branch = Creations.for(git.subcommand, git.args)
+          { dir: git.dir, branch: branch } if branch
+        end
+      end
+
+      private
+
+      # A git command found in the line: the directory it runs in (after `cd` and `-C`), the
+      # subcommand and its arguments
+      GitCommand = Data.define(:dir, :command, :subcommand, :args)
+
+      def git_commands(command_line, dir = @cwd, depth = 0)
+        segments(command_line).flat_map do |segment|
           words = words(segment)
-          next if words.empty?
+          next [] if words.empty?
 
           if words.first == 'cd'
             dir = File.expand_path(words[1] || Dir.home, dir)
-            next
+            next []
           end
-          git_target(words, dir, segment.strip) if File.basename(words.first) == 'git'
+          commands_in(words, dir, segment.strip, depth)
         end
       end
 
-      private
+      # The git command of one segment, or the ones inside `bash -c "..."` and `eval "..."`
+      def commands_in(words, dir, segment, depth)
+        return [git_command(words, dir, segment)] if File.basename(words.first) == 'git'
+
+        script = nested_script(words)
+        script && depth < MAX_NESTING ? git_commands(script, dir, depth + 1) : []
+      end
+
+      # The script text passed to a shell (`bash -c`, `sh -lc`) or to `eval`
+      def nested_script(words)
+        return words.drop(1).join(' ') if words.first == 'eval'
+        return nil unless SHELLS.include?(File.basename(words.first))
+
+        index = words.index { |word| word.match?(/\A-[a-z]*c[a-z]*\z/) }
+        index && words[index + 1]
+      end
 
       # Splits on unquoted ; & | and newlines
       def segments(line)
@@ -78,13 +119,10 @@ module Gitflash
         word.delete_prefix('(').delete_prefix('{').delete_suffix(')').delete_suffix('}')
       end
 
-      def git_target(words, dir, command)
+      def git_command(words, dir, command)
         index, dir = skip_git_options(words, dir)
-        rule = Rules.for(words[index], words[(index + 1)..] || [], dir)
-        return nil unless rule
-
-        Target.new(dir: rule.fetch(:dir, dir), command: command, scope: rule[:scope],
-                   branches: rule[:branches] || [])
+        GitCommand.new(dir: dir, command: command, subcommand: words[index],
+                       args: words[(index + 1)..] || [])
       end
 
       # Index of the subcommand, and the directory after any -C options

data/lib/gitflash/hook/creations.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Which git commands create a branch, and the name of it: `checkout -b`, `switch -c`,
+    # `branch NAME` and `worktree add -b` (or a path without a commit, which names the branch
+    # after the directory). Returns the name, or nil when the command creates no branch.
+    module Creations
+      NOT_CREATING = %w[
+        -d -D --delete -m -M --move -c -C --copy -u --set-upstream-to --unset-upstream
+        --edit-description --list -a --all -r --remotes -v -vv --verbose --show-current --contains
+        --no-contains --merged --no-merged --points-at
+      ].freeze
+      WORKTREE_VALUE_OPTIONS = %w[-b -B --reason --orphan].freeze
+
+      module_function
+
+      def for(subcommand, args)
+        case subcommand
+        when 'checkout' then flagged(args, %w[-b -B])
+        when 'switch' then flagged(args, %w[-c -C --create --force-create])
+        when 'branch' then plain_branch(args)
+        when 'worktree' then worktree(args)
+        end
+      end
+
+      # The value of the first of `flags`: `-b NAME`, `-bNAME` or `--create=NAME`
+      def flagged(args, flags)
+        args.each_with_index do |arg, index|
+          return args[index + 1] if flags.include?(arg) && args[index + 1]
+
+          value = attached_value(arg, flags)
+          return value if value
+        end
+        nil
+      end
+
+      def attached_value(arg, flags)
+        flags.each do |flag|
+          if flag.start_with?('--')
+            return arg.delete_prefix("#{flag}=") if arg.start_with?("#{flag}=")
+          elsif arg.start_with?(flag) && arg.length > flag.length && !arg.start_with?('--')
+            return arg.delete_prefix(flag)
+          end
+        end
+        nil
+      end
+
+      # `git branch NAME [START]` creates NAME; listing, deleting or renaming flags mean it does not
+      def plain_branch(args)
+        return nil if args.intersect?(NOT_CREATING)
+
+        args.find { |arg| !arg.start_with?('-') }
+      end
+
+      def worktree(args)
+        return nil unless args.first == 'add'
+
+        rest = args.drop(1)
+        named = flagged(rest, %w[-b -B])
+        return named if named
+        return nil if rest.include?('--detach') || rest.include?('--orphan')
+
+        path = positional(rest)
+        path.size == 1 ? File.basename(path.first) : nil
+      end
+
+      # Arguments that are not options or the values of options that take one
+      def positional(args)
+        result = []
+        skip = false
+        args.each do |arg|
+          if skip
+            skip = false
+          elsif WORKTREE_VALUE_OPTIONS.include?(arg)
+            skip = true
+          elsif !arg.start_with?('-')
+            result << arg
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/gitflash/hook/messages.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # What the PreToolUse hook tells Claude about a risky command
+    module Messages
+      module_function
+
+      def saved(saved)
+        notes = saved.map { |target, snap| "snapshot #{snap.id} before `#{target.command}`" }
+        "gitflash saved #{notes.join('; ')}. If this discards work that was still needed, " \
+          "restore it with #{undo_commands(saved)} (list snapshots with `gitflash snapshots`)."
+      end
+
+      # One command per snapshot: with several directories each snapshot belongs to its own
+      def undo_commands(saved)
+        return "`gitflash undo #{saved.first[1].id}`" if saved.size == 1
+
+        saved.map { |target, snap| "`gitflash undo #{snap.id}` (run in #{target.dir})" }.join(', ')
+      end
+
+      def unsaved(targets)
+        "gitflash could not save a snapshot before #{commands(targets)} (the directory is not a " \
+          'git work tree or does not exist), so nothing can be restored with `gitflash undo`.'
+      end
+
+      def denial(targets)
+        "gitflash blocked #{commands(targets)}: it can discard work git cannot restore. " \
+          'Use the gitflash equivalent (gitflash reset, gitflash delete, ...), which ' \
+          'saves a snapshot first, or run `gitflash snapshot` before retrying.'
+      end
+
+      def commands(targets)
+        targets.map { |target| "`#{target.command}`" }.join(', ')
+      end
+    end
+  end
+end