gitflash 0.6.0 → 0.7.0.beta1

data/lib/gitflash/commands/worktree_add.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Adds a worktree for an existing, remote or new branch. Additive, so it needs no
+    # confirmation and no snapshot. A branch created here is marked as agent work.
+    class WorktreeAdd < Base
+      def call(branch = nil)
+        validate_name!(branch)
+        worktrees = Worktrees.new(repo: repo)
+        source = worktrees.source_for(branch)
+        check_options!(source)
+        check_free!(worktrees, branch, source)
+
+        plan = build_plan(branch, source)
+        if ui.dry_run?
+          return planned(plan,
+                         "Would add worktree #{plan[:path]} on #{branch} (#{source})")
+        end
+
+        add(worktrees, plan)
+      end
+
+      private
+
+      def validate_name!(branch)
+        usage_error!('invalid_usage', 'Pass the branch: gitflash wt add BRANCH') if branch.nil?
+        valid = !branch.start_with?('-') && ref_format_ok?(branch)
+        usage_error!('invalid_usage', "Invalid branch name '#{branch}'") unless valid
+      end
+
+      def ref_format_ok?(branch)
+        _stdout, _stderr, success = Git::BashCommand.capture('git', 'check-ref-format', '--branch',
+                                                             branch)
+        success
+      end
+
+      def check_options!(source)
+        return unless options[:from] && source != :new
+
+        usage_error!('invalid_options', '--from only applies to a new branch, but the branch ' \
+                                        "already exists (#{source})")
+      end
+
+      def check_free!(worktrees, branch, source)
+        return unless source == :existing
+
+        holder = worktrees.list.find { |worktree| worktree.branch == branch }
+        return unless holder
+
+        usage_error!('invalid_usage', "Branch #{branch} is already checked out at #{holder.path}")
+      end
+
+      def build_plan(branch, source)
+        path = target_path(branch)
+        if File.exist?(path) && !(File.directory?(path) && Dir.empty?(path))
+          usage_error!('invalid_usage', "#{path} already exists and is not an empty directory")
+        end
+
+        { branch: branch, path: path, source: source.to_s, from: options[:from],
+          owner: source == :existing ? nil : owner }
+      end
+
+      def target_path(branch)
+        return File.expand_path(options[:path]) if options[:path]
+
+        config.worktree_path(root: repo.main_root, branch: branch)
+      end
+
+      def owner
+        value = options[:owner] || 'agent'
+        return value if Ownership::OWNERS.include?(value)
+
+        usage_error!('invalid_options', "Unknown owner '#{value}' (use agent or human)")
+      end
+
+      def add(worktrees, plan)
+        source = plan[:source].to_sym
+        result = worktrees.add(plan[:path], branch: plan[:branch], source: source,
+                                            start: plan[:from])
+        git_error!('worktree add', result) unless result.success?
+
+        Ownership.new.mark(plan[:branch], plan[:owner]) if plan[:owner]
+        report(plan)
+      end
+
+      def report(plan)
+        ui.report(status: 'done', plan: plan, result: outcome(plan),
+                  text: "Added worktree #{plan[:path]} on #{plan[:branch]}")
+      end
+
+      def outcome(plan)
+        head = Git::BashCommand.exec('git', '-C', plan[:path], 'rev-parse', 'HEAD').strip
+        plan.slice(:branch, :path, :source, :owner).merge(head: head)
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_clean.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Removes the worktrees whose branch is no longer needed (same criteria as `clean`).
+    # Main, current, locked and dirty worktrees are skipped with the reason unless --force
+    # allows locked and dirty ones; the main checkout and the current worktree never go.
+    # Removal, snapshots and undo work as in `wt remove`. Branches are kept: run `gitflash clean`
+    # afterwards to delete them. Worktrees with a missing directory belong to `wt prune`.
+    class WorktreeClean < WorktreeRemove
+      include CleanCriteria
+
+      def call
+        chosen, @skipped = select
+        @reasons = chosen.to_h { |candidate| [candidate.item.path, candidate.reasons] }
+        return nothing_to_clean if chosen.empty?
+
+        remove(chosen.map(&:item))
+      end
+
+      private
+
+      def select
+        Cleanup.worktrees(worktrees.list, branches: repo.branches(merged_status: true),
+                                          rules: rules, protection: Protection.new(config: config),
+                                          blocker: ->(worktree) { blocker(worktree) })
+      end
+
+      def blocker(worktree)
+        worktree.removal_blocker(force: force?, current: current?(worktree))
+      end
+
+      def build_plan(chosen)
+        super.merge(skipped: @skipped)
+      end
+
+      def plan_row(worktree)
+        super.merge(reasons: @reasons[worktree.path])
+      end
+
+      def nothing_to_clean
+        plan = { worktrees: [], force: force?, skipped: @skipped }
+        text = (['Nothing to clean'] + @skipped.map { |row| "Kept #{row[:path]}: #{row[:reason]}" })
+        ui.report(status: 'noop', plan: plan, result: { removed: [], failed: [] },
+                  text: text.join("\n"))
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Shared lookup for the `worktree` commands that act on one worktree
+    class WorktreeCommand < Base
+      private
+
+      def worktrees
+        @worktrees ||= Worktrees.new(repo: repo)
+      end
+
+      # The worktree named by a path or a branch; raises `unknown_worktree` when none matches
+      def find!(target, list = worktrees.list)
+        path = File.expand_path(target)
+        list.find { |worktree| worktree.path == path || worktree.branch == target } ||
+          usage_error!('unknown_worktree', "Unknown worktree: #{target}")
+      end
+
+      def refuse_main!(worktree, action)
+        return unless worktree.main?
+
+        usage_error!('protected_worktree',
+                     "#{worktree.path} is the main checkout; cannot #{action}")
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_list.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Lists the worktrees of the repository
+    class WorktreeList < Base
+      def call
+        worktrees = Worktrees.new(repo: repo).list
+        ui.report(status: 'done', result: { worktrees: worktrees.map(&:to_h) },
+                  text: table(worktrees))
+      end
+
+      private
+
+      def table(worktrees)
+        width = worktrees.map { |worktree| worktree.path.length }.max
+        worktrees.map { |worktree| row(worktree, width) }.join("\n")
+      end
+
+      def row(worktree, width)
+        [worktree.path.ljust(width), worktree.branch || "(detached #{worktree.head.to_s[0, 7]})",
+         flags(worktree)].join('  ').rstrip
+      end
+
+      def flags(worktree)
+        labels = state_labels(worktree) + position_labels(worktree)
+        labels.select { |_label, shown| shown }.map(&:first).join(', ')
+      end
+
+      def state_labels(worktree)
+        [['main', worktree.main?], ['agent', worktree.owner == 'agent'],
+         ['dirty', worktree.dirty?], ['dirty state unknown', unknown_dirty?(worktree)],
+         ['locked', worktree.locked?], ['missing', worktree.missing?],
+         ['merged', worktree.merged && worktree.branch != repo.default_branch]]
+      end
+
+      # git status failed in a directory that exists; JSON keeps `dirty: null`
+      def unknown_dirty?(worktree)
+        worktree.dirty.nil? && !worktree.missing? && !worktree.bare
+      end
+
+      def position_labels(worktree)
+        [["ahead #{worktree.ahead}", worktree.ahead.to_i.positive?],
+         ["behind #{worktree.behind}", worktree.behind.to_i.positive?]]
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_lock.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Locks or unlocks a worktree, so `prune`, `remove` and `clean` leave it alone.
+    # Needs no confirmation: the change is reversed by the opposite command.
+    class WorktreeLock < WorktreeCommand
+      def call(target = nil)
+        unless target
+          usage_error!('invalid_usage',
+                       "Pass the worktree: gitflash wt #{verb} WORKTREE")
+        end
+        worktree = find!(target)
+        refuse_main!(worktree, verb)
+        return noop(worktree) if worktree.locked? == lock?
+        return planned(plan(worktree), "Would #{verb} #{worktree.path}") if ui.dry_run?
+
+        change(worktree)
+      end
+
+      private
+
+      def lock? = true
+
+      def verb = lock? ? 'lock' : 'unlock'
+
+      def plan(worktree)
+        { path: worktree.path, reason: (options[:reason] if lock?) }.compact
+      end
+
+      def change(worktree)
+        result = git_change(worktree)
+        git_error!("worktree #{verb}", result) unless result.success?
+
+        report('done', worktree, "#{verb.capitalize}ed #{worktree.path}")
+      end
+
+      def git_change(worktree)
+        return worktrees.unlock(worktree.path) unless lock?
+
+        worktrees.lock(worktree.path, reason: options[:reason])
+      end
+
+      def noop(worktree)
+        report('noop', worktree, "#{worktree.path} is #{lock? ? 'already locked' : 'not locked'}")
+      end
+
+      def report(status, worktree, text)
+        ui.report(status: status, plan: plan(worktree), text: text,
+                  result: plan(worktree).merge(locked: lock?))
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_move.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Moves a worktree to another directory. Refuses the main checkout, the current worktree
+    # (its directory would disappear under the caller) and locked worktrees unless --force.
+    # Needs no confirmation: moving it back reverses it.
+    class WorktreeMove < WorktreeCommand
+      def call(target = nil, destination = nil)
+        unless target && destination
+          usage_error!('invalid_usage',
+                       'Pass the worktree and its new path')
+        end
+        worktree = find!(target)
+        check!(worktree)
+        plan = { from: worktree.path, to: File.expand_path(destination), force: force? }
+        return planned(plan, "Would move #{plan[:from]} to #{plan[:to]}") if ui.dry_run?
+
+        move(plan)
+      end
+
+      private
+
+      def force?
+        options[:force] ? true : false
+      end
+
+      def check!(worktree)
+        refuse_main!(worktree, 'move')
+        if worktree.path == repo.toplevel
+          usage_error!('protected_worktree', "#{worktree.path} is the current worktree")
+        end
+        return unless worktree.locked? && !force?
+
+        usage_error!('protected_worktree', "#{worktree.path} is locked (use --force)")
+      end
+
+      def move(plan)
+        result = worktrees.move(plan[:from], plan[:to], force: plan[:force])
+        git_error!('worktree move', result) unless result.success?
+
+        ui.report(status: 'done', plan: plan, result: plan.slice(:from, :to),
+                  text: "Moved #{plan[:from]} to #{plan[:to]}")
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_prune.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Forgets worktrees whose directory is gone (locked ones stay). Branches are not touched.
+    # Takes no snapshot: only git's own bookkeeping for the missing directory is removed.
+    class WorktreePrune < WorktreeCommand
+      def call
+        stale = worktrees.list.select { |worktree| worktree.missing? && !worktree.locked? }
+        return noop if stale.empty?
+
+        prune_or_ask({ worktrees: stale.map(&:path) })
+      end
+
+      private
+
+      def prune_or_ask(plan)
+        return planned(plan, "Would prune:\n#{bullets(plan)}") if ui.dry_run?
+
+        question = "You are about to prune:\n\n#{bullets(plan)}"
+        ui.confirm?(question, plan: plan) ? prune(plan) : cancelled(plan)
+      end
+
+      def prune(plan)
+        result = worktrees.prune
+        git_error!('worktree prune', result) unless result.success?
+
+        ui.report(status: 'done', plan: plan, result: { pruned: plan[:worktrees] },
+                  text: "Pruned:\n#{bullets(plan)}")
+      end
+
+      def noop
+        ui.report(status: 'noop', result: { pruned: [] }, text: 'No missing worktrees to prune')
+      end
+
+      def bullets(plan)
+        plan[:worktrees].map { |path| "* #{path}" }.join("\n")
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_remove.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Removes worktrees given as paths or branch names, or picked from a menu.
+    # The main checkout, the worktree gitflash runs in, locked and dirty worktrees are refused
+    # unless --force is given (the main checkout and the current one never can be removed).
+    # Each removal saves a snapshot of the worktree first; `gitflash undo ID` brings the
+    # directory, its branch and its uncommitted files back.
+    class WorktreeRemove < WorktreeCommand
+      include RemovalReport
+
+      def call(*targets)
+        worktrees = Worktrees.new(repo: repo).list
+        targets = pick(worktrees) if targets.empty?
+        return 0 if targets.nil?
+
+        chosen = resolve(targets, worktrees)
+        remove(chosen)
+      end
+
+      private
+
+      def pick(worktrees)
+        require_interactive!('Pass the worktrees to remove: gitflash wt remove PATH_OR_BRANCH...')
+        choices = worktrees.reject { |worktree| worktree.main? || current?(worktree) }
+                           .to_h { |wt| ["#{wt.branch || '(detached)'}  #{wt.path}", wt.path] }
+        return report_nothing('No worktrees available to remove') if choices.empty?
+
+        picked = ui.multi_select('Select worktrees to remove', choices)
+        picked.empty? ? report_nothing('No worktrees selected') : picked
+      end
+
+      def force?
+        options[:force] ? true : false
+      end
+
+      def current?(worktree)
+        worktree.path == repo.toplevel
+      end
+
+      def resolve(targets, worktrees)
+        chosen = targets.uniq.map { |target| find!(target, worktrees) }.uniq(&:path)
+        refused = chosen.filter_map do |worktree|
+          worktree.removal_blocker(force: force?, current: current?(worktree))
+        end
+        usage_error!('protected_worktree', refused.join('; ')) if refused.any?
+        chosen
+      end
+
+      def remove(chosen)
+        plan = build_plan(chosen)
+        return planned(plan, "Would remove:\n#{preview(chosen, plan)}") if dry_run?
+        return cancelled(plan) unless ui.confirm?(summary(chosen, plan), plan: plan)
+
+        outcomes = chosen.map { |worktree| remove_one(worktree) }
+        report_results(plan, outcomes)
+      end
+
+      def dry_run? = ui.dry_run?
+
+      def preview(chosen, plan) = "#{bullets(chosen)}#{ignored_warning(plan)}"
+
+      # The plan reported and returned in JSON; `wt clean` adds why each worktree was chosen
+      def build_plan(chosen)
+        { worktrees: chosen.map { |worktree| plan_row(worktree) }, force: force? }
+      end
+
+      def plan_row(worktree)
+        ignored = worktree.missing? ? [] : Worktrees.new(repo: repo).ignored(worktree.path)
+        { path: worktree.path, branch: worktree.branch, dirty: worktree.dirty?,
+          locked: worktree.locked?, ignored_count: ignored.size, ignored: ignored.first(5) }
+      end
+
+      def remove_one(worktree)
+        snapshot = snapshot_for(worktree)
+        unsaved = snapshot.skipped_files
+        return refuse_unsaved(worktree, unsaved) if unsaved.any?
+
+        result = Worktrees.new(repo: repo).remove(worktree.path, force: force?)
+        Removal.new(worktree: worktree, result: result, snapshot: (snapshot if result.success?))
+      end
+
+      # Files a snapshot cannot hold (untracked and over 50 MB) would be lost for good
+      def refuse_unsaved(worktree, files)
+        shown = files.first(3).join(', ')
+        shown += ", and #{files.size - 3} more" if files.size > 3
+        message = "#{files.size} untracked file(s) over 50 MB cannot be saved by a snapshot " \
+                  "(#{shown}); move or delete them first"
+        Removal.new(worktree: worktree, result: Result.new(success: false, output: message),
+                    snapshot: nil)
+      end
+
+      # A missing directory has no HEAD or files to save; only the branch tip is
+      def snapshot_for(worktree)
+        reason = "gitflash wt remove #{worktree.path}"
+        branches = [worktree.branch].compact
+        return take_snapshot(reason, scope: %w[branches], branches: branches) if worktree.missing?
+
+        take_snapshot(reason, scope: %w[branches head worktree], branches: branches,
+                              dir: worktree.path)
+      end
+
+      def summary(chosen, plan)
+        "You are about to remove the following worktrees:\n\n#{bullets(chosen)}" \
+          "#{ignored_warning(plan)}"
+      end
+
+      def bullets(chosen)
+        chosen.map { |worktree| "* #{worktree.path} (#{worktree.branch || 'detached'})" }.join("\n")
+      end
+
+      def report_nothing(text)
+        ui.report(status: 'noop', result: { removed: [], failed: [] }, text: text)
+        nil
+      end
+    end
+  end
+end

data/lib/gitflash/commands/worktree_unlock.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Unlocks a worktree; see WorktreeLock
+    class WorktreeUnlock < WorktreeLock
+      private
+
+      def lock? = false
+    end
+  end
+end

data/lib/gitflash/config.rb

@@ -0,0 +1,95 @@
+# 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
+    def self.load(root:, home: Dir.home)
+      values = [File.join(home, ConfigKeys::USER_FILE), File.join(root, ConfigKeys::REPO_FILE)]
+               .map { |path| read(path) }
+               .reduce(ConfigKeys::DEFAULTS) { |merged, layer| merged.merge(layer) }
+      new(protected_patterns: values['protected'], 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}` and `%{branch}` are replaced; a relative path
+    # is resolved against the main checkout. Slashes in a branch name stay as folders.
+    def worktree_path(root:, branch:)
+      path = format(worktree_dir, repo: File.basename(root), branch: branch)
+      File.expand_path(path, root)
+    end
+  end
+end

data/lib/gitflash/config_keys.rb

@@ -0,0 +1,19 @@
+# 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
+    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) { v.is_a?(String) && !v.empty? }, 'a non-empty string']
+    }.freeze
+  end
+end

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