gitflash 0.5.1 → 0.7.0.beta1

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/rules.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Which git subcommands can lose work git cannot restore, and what to save before them.
+    # Each rule takes the subcommand's arguments and the directory, and returns nil (safe) or
+    # { scope:, branches:, dir: } where branches may contain :current for the checked-out one.
+    module Rules
+      FULL = %w[branches head worktree].freeze
+
+      module_function
+
+      def for(subcommand, args, dir)
+        rule = RULES[subcommand]
+        rule&.call(args, dir)
+      end
+
+      def any?(args, flags)
+        args.intersect?(flags)
+      end
+
+      # `git checkout PATH` overwrites uncommitted changes in PATH without any flag, and telling a
+      # path from a branch needs git; an argument that names an existing file counts as a path.
+      def checkout(args, dir)
+        discards = any?(args, %w[-- . --force --patch --ours --theirs]) ||
+                   short_flags(args).match?(/[fp]/) || path_arg?(args, dir)
+        discards ? { scope: %w[worktree] } : nil
+      end
+
+      # The letters of all short options, so bundled ones such as `-fq` are seen
+      def short_flags(args)
+        args.select { |arg| arg.start_with?('-') && !arg.start_with?('--') }.join
+      end
+
+      def path_arg?(args, dir)
+        args.reject { |arg| arg.start_with?('-') }.any? do |arg|
+          File.exist?(File.expand_path(arg, dir))
+        end
+      end
+
+      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
+      end
+
+      def switch(args, _dir)
+        discards = any?(args, %w[--force --discard-changes]) || short_flags(args).include?('f')
+        discards ? { scope: %w[head worktree] } : nil
+      end
+
+      def stash(args, _dir)
+        case args.first
+        when 'drop', 'clear' then { scope: %w[stashes] }
+        when 'pop' then { scope: %w[worktree stashes] }
+        end
+      end
+
+      def branch(args, _dir)
+        return nil unless any?(args, %w[-d -D --delete -f --force -m -M --move -C --copy])
+
+        { scope: %w[branches], branches: args.reject { |arg| arg.start_with?('-') } }
+      end
+
+      def update_ref(args, _dir)
+        return nil unless args.include?('-d')
+
+        heads = args.select { |arg| arg.start_with?('refs/heads/') }
+        { scope: %w[branches], branches: heads.map { |ref| ref.delete_prefix('refs/heads/') } }
+      end
+
+      def rebase(args, _dir)
+        args.include?('--continue') ? nil : { scope: FULL, branches: [:current] }
+      end
+
+      def abort(args, _dir)
+        any?(args, %w[--abort --quit]) ? { scope: %w[worktree] } : nil
+      end
+
+      # `git worktree remove --force PATH` deletes that worktree's uncommitted files
+      def worktree(args, dir)
+        return nil unless args.first == 'remove' && any?(args, %w[-f --force])
+
+        path = args[1..].reject { |arg| arg.start_with?('-') }.first
+        path && { scope: %w[worktree], dir: File.expand_path(path, dir) }
+      end
+
+      RULES = {
+        'reset' => ->(_args, _dir) { { scope: FULL, branches: [:current] } },
+        'checkout' => method(:checkout),
+        'restore' => ->(_args, _dir) { { scope: %w[worktree] } },
+        'clean' => method(:clean),
+        'switch' => method(:switch),
+        'stash' => method(:stash),
+        'branch' => method(:branch),
+        'update-ref' => method(:update_ref),
+        'rebase' => method(:rebase),
+        'merge' => method(:abort),
+        'cherry-pick' => method(:abort),
+        'revert' => method(:abort),
+        'am' => method(:abort),
+        'worktree' => method(:worktree)
+      }.freeze
+    end
+  end
+end

data/lib/gitflash/hook/settings.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Gitflash
+  module Hook
+    # Where Claude Code reads the settings that can hold the gitflash hook, following its rules:
+    #   local    .claude/settings.local.json at the repository root (the main checkout's root
+    #            inside a linked worktree), for sessions started anywhere in the repository
+    #   project  .claude/settings.json in the directory a session starts in; gitflash uses the
+    #            repository's top level, so it applies to sessions started there
+    #   user     ~/.claude/settings.json, for every session
+    # Claude Code reloads these files in running sessions, so no restart is needed.
+    class Settings
+      SCOPES = %w[local project user].freeze
+      PATTERN = /\bgitflash hook claude\b/
+
+      # `repo` is nil outside a git repository; only the user scope applies there
+      def initialize(repo)
+        @repo = repo
+      end
+
+      def path(scope)
+        case scope
+        when 'user' then File.join(Dir.home, '.claude', 'settings.json')
+        when 'project' then File.join(@repo.toplevel, '.claude', 'settings.json')
+        else File.join(@repo.main_root, '.claude', 'settings.local.json')
+        end
+      end
+
+      # Which Claude Code sessions read the file of a scope
+      def applies_to(scope)
+        case scope
+        when 'user' then 'every Claude Code session'
+        when 'project' then "Claude Code sessions started in #{@repo.toplevel}"
+        else "Claude Code sessions in #{@repo.main_root} and its worktrees"
+        end
+      end
+
+      def scopes
+        @repo ? SCOPES : %w[user]
+      end
+
+      def read(path)
+        return {} unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise Error.new("#{path} is not valid JSON: #{e.message}", code: 'invalid_settings')
+      end
+
+      # 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
+end

data/lib/gitflash/hook_cli.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'thor'
+
+module Gitflash
+  # `gitflash hook ...`: integrations that let agents keep using plain git safely
+  class HookCli < Thor
+    include CommandRunner
+
+    namespace 'hook'
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'claude',
+         'Run as a Claude Code hook (PreToolUse and PostToolUse; reads the input on stdin)'
+    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),
+      it saves a snapshot first and tells Claude how to undo it.
+
+      --mode snapshot  save a snapshot and let the command run (default)
+      --mode ask       save a snapshot and ask the user to approve the command
+      --mode deny      block the command and point to the gitflash equivalent
+
+      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.
+
+      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
+      output = Hook::Claude.new(mode: options[:mode]).call($stdin.read)
+      puts JSON.generate(output) if output
+    rescue StandardError => e
+      warn "gitflash hook: #{e.message}"
+    end
+
+    desc 'install', 'Register the gitflash hook in Claude Code settings'
+    long_desc <<~TEXT
+      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
+      --scope project  .claude/settings.json at the repository top level (shared with the team);
+                       applies to sessions started there
+      --scope user     ~/.claude/settings.json; applies to every session
+
+      Claude Code reloads settings files, so running sessions pick the hook up without a restart.
+      Check the result with `gitflash hook status`.
+
+      Accepts the global --json and --dry-run options after the subcommand: gitflash hook install --json
+    TEXT
+    option :scope, type: :string, default: 'local', enum: Commands::HookInstall::SCOPES
+    option :mode, type: :string, default: 'snapshot', enum: Hook::Claude::MODES
+    def install
+      run_command('hook install', Commands::HookInstall, repo_required: options[:scope] != 'user')
+    end
+
+    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 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
+      run_command('hook status', Commands::HookStatus, repo_required: false)
+    end
+  end
+end

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,15 +30,24 @@ 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
       branches.find(&:current?)&.name
     end
 
+    def toplevel
+      @bash.exec('git', 'rev-parse', '--show-toplevel').strip
+    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
+      File.basename(common) == '.git' ? File.dirname(common) : toplevel
+    end
+
     # The branch that origin/HEAD points to, else main or master when present locally
     def default_branch
       return @default_branch if defined?(@default_branch)

data/lib/gitflash/restore.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Plans and applies the restore of a snapshot. Only the parts in the snapshot's scope are
+  # restored, and only where the repository differs from the snapshot. Branches and files
+  # created after the snapshot are left alone.
+  class Restore
+    def initialize(snapshot, bash: Git::BashCommand)
+      @snapshot = snapshot
+      @bash = bash
+    end
+
+    # { branches: [{branch, from, to}], head: {from, to} | nil, worktree: bool, stashes: [sha] }
+    def plan
+      @plan ||= {
+        branches: @snapshot.scope?('branches') ? branch_changes : [],
+        head: @snapshot.scope?('head') ? head_change : nil,
+        worktree: @snapshot.scope?('worktree') && worktree_differs?,
+        stashes: @snapshot.scope?('stashes') ? missing_stashes : []
+      }
+    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 (`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
+
+    def steps
+      branch_steps + head_steps + worktree_steps + stash_steps
+    end
+
+    def branch_steps
+      plan[:branches].map do |change|
+        # An empty old value makes git refuse to overwrite a branch created since the plan
+        ['update-ref', "refs/heads/#{change[:branch]}", change[:to], change[:from] || '']
+      end
+    end
+
+    # With the worktree in scope HEAD is moved directly and the files are restored next;
+    # otherwise a normal checkout keeps local changes.
+    def head_steps
+      return [] unless plan[:head]
+
+      branch = @snapshot.head[:branch]
+      sha = @snapshot.head[:sha]
+      if @snapshot.scope?('worktree')
+        detach = ['update-ref', '--no-deref', 'HEAD', sha]
+        [branch ? ['symbolic-ref', 'HEAD', "refs/heads/#{branch}"] : detach]
+      else
+        [branch ? ['switch', '--', branch] : ['checkout', '--detach', sha]]
+      end
+    end
+
+    # Working tree first (tracked and snapshot-untracked files), then the staged state
+    def worktree_steps
+      return [] unless plan[:worktree] && target_worktree
+
+      steps = [['read-tree', '--reset', '-u', target_worktree]]
+      steps << ['read-tree', '--reset', target_index] if target_index != target_worktree
+      steps
+    end
+
+    def stash_steps
+      plan[:stashes].reverse.map { |sha| ['stash', 'store', '-m', 'gitflash undo', sha] }
+    end
+
+    def target_worktree
+      @snapshot.worktree || @snapshot.head[:sha]
+    end
+
+    def target_index
+      return @snapshot.index if @snapshot.index
+
+      @snapshot.worktree ? @snapshot.head[:sha] : target_worktree
+    end
+
+    def branch_changes
+      tips = current_tips
+      @snapshot.branches.filter_map do |name, sha|
+        { branch: name, from: tips[name], to: sha } unless tips[name] == sha
+      end
+    end
+
+    def head_change
+      current = current_head
+      target = @snapshot.head
+      same = if target[:branch]
+               current[:branch] == target[:branch]
+             else
+               current[:branch].nil? && current[:sha] == target[:sha]
+             end
+      same ? nil : { from: current[:branch] || current[:sha], to: target[:branch] || target[:sha] }
+    end
+
+    def current_head
+      { branch: capture('symbolic-ref', '--quiet', 'HEAD')&.delete_prefix(Repo::HEADS),
+        sha: capture('rev-parse', '--verify', '--quiet', 'HEAD^{commit}') }
+    end
+
+    def worktree_differs?
+      return true unless capture('status', '--porcelain', '--untracked-files=all').to_s.empty?
+
+      target_worktree && tree_of(target_worktree) != tree_of('HEAD')
+    end
+
+    def missing_stashes
+      @snapshot.stashes - capture('stash', 'list', '--format=%H').to_s.split
+    end
+
+    def current_tips
+      Branch.parse_tips(capture('for-each-ref', "--format=#{Branch::TIPS_FORMAT}", Repo::HEADS))
+    end
+
+    def tree_of(ref)
+      capture('rev-parse', '--verify', '--quiet', "#{ref}^{tree}")
+    end
+
+    # Stripped stdout of a git command, or nil when it fails
+    def capture(*)
+      stdout, _stderr, success = @bash.capture('git', *)
+      success ? stdout.strip : nil
+    end
+
+    def run(*)
+      stdout, stderr, success = @bash.capture('git', *)
+      output = [stdout, stderr].map(&:strip).reject(&:empty?).join("\n")
+      Result.new(success: success, output: output)
+    end
+  end
+end

data/lib/gitflash/snapshot.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Saved repository state that `gitflash undo` can restore.
+  #
+  # scope          parts of the state that undo restores: branches, head, worktree, stashes
+  # head           { branch:, sha: } of HEAD; branch is nil on a detached HEAD, sha nil before
+  #                the first commit
+  # branches       { name => sha } of the recorded local branches
+  # stashes        stash commits, newest first
+  # index          commit whose tree is the staged state, nil when the tree was clean
+  # worktree       commit whose tree is the working tree including untracked files (not
+  #                ignored ones), nil when the tree was clean
+  # skipped_files  untracked files left out because they were too large
+  Snapshot = Data.define(
+    :id, :created_at, :reason, :scope, :worktree_path, :head, :branches, :stashes,
+    :index, :worktree, :skipped_files
+  ) do
+    def self.from_h(hash)
+      new(
+        id: hash['id'], created_at: hash['created_at'], reason: hash['reason'],
+        scope: hash['scope'], worktree_path: hash['worktree_path'],
+        head: { branch: hash.dig('head', 'branch'), sha: hash.dig('head', 'sha') },
+        branches: hash['branches'] || {}, stashes: hash['stashes'] || [],
+        index: hash['index'], worktree: hash['worktree'], skipped_files: hash['skipped_files'] || []
+      )
+    end
+
+    def scope?(part)
+      scope.include?(part)
+    end
+
+    # Commits the snapshot must keep reachable
+    def object_ids
+      ([head[:sha], index, worktree] + branches.values + stashes).compact.uniq
+    end
+
+    # Everything except id, time and reason, to detect an unchanged repository
+    def state
+      to_h.except(:id, :created_at, :reason)
+    end
+
+    def to_h
+      super.merge(branches: branches.transform_keys(&:to_s))
+    end
+  end
+end