gitflash 0.5.1 → 0.7.0.beta1

data/lib/gitflash/snapshots.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'time'
+
+module Gitflash
+  # Creates, lists and deletes snapshots.
+  #
+  # Each snapshot is one commit under refs/gitflash/snapshots/<id>. Its message is the snapshot
+  # metadata as JSON, its tree is empty, and its parents are every commit the snapshot refers
+  # to, so git keeps them all as long as the ref exists. Nothing outside git's own object store
+  # is written, and linked worktrees share the snapshots.
+  class Snapshots
+    REF_PREFIX = 'refs/gitflash/snapshots/'
+    SCOPES = %w[branches head worktree stashes].freeze
+
+    def initialize(bash: Git::BashCommand, clock: -> { Time.now })
+      @bash = bash
+      @clock = clock
+      @capture = StateCapture.new(bash: bash)
+    end
+
+    # Saves the current state. `branches` limits the recorded branches (nil records all).
+    # Returns the latest snapshot instead when nothing changed since it was taken.
+    def create(reason:, scope: SCOPES, branches: nil)
+      state = @capture.call(scope, branches)
+      latest = list.first
+      return latest if latest&.state == state
+
+      store(Snapshot.new(**identity, reason: reason, **state))
+    end
+
+    # Snapshots, newest first
+    def list
+      git('for-each-ref', '--sort=-refname', '--format=%(contents:subject)', REF_PREFIX)
+        .each_line(chomp: true).reject(&:empty?)
+        .map { |line| Snapshot.from_h(JSON.parse(line)) }
+    end
+
+    def find(id)
+      list.find { |snapshot| snapshot.id == id }
+    end
+
+    def delete(id)
+      git('update-ref', '-d', "#{REF_PREFIX}#{id}")
+    end
+
+    private
+
+    def git(*)
+      @bash.exec('git', *)
+    end
+
+    # Ids sort by time down to the microsecond, so several snapshots within one second still
+    # list in the order they were taken; the random suffix keeps them unique.
+    def identity
+      now = @clock.call.utc
+      id = "#{now.strftime('%Y%m%dT%H%M%S%6N')}-#{SecureRandom.hex(2)}"
+      { id: id, created_at: now.iso8601(6) }
+    end
+
+    def store(snapshot)
+      meta = @capture.commit_tree(@capture.empty_tree, parents: snapshot.object_ids,
+                                                       message: JSON.generate(snapshot.to_h))
+      git('update-ref', "#{REF_PREFIX}#{snapshot.id}", meta)
+      snapshot
+    end
+  end
+end

data/lib/gitflash/state_capture.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module Gitflash
+  # Reads the repository state a snapshot saves and writes the needed git objects.
+  # Never changes branches, the index or the working tree.
+  class StateCapture
+    MAX_UNTRACKED_FILE_BYTES = 50 * 1024 * 1024
+    ADD_BATCH_SIZE = 500
+    IDENTITY = {
+      'GIT_AUTHOR_NAME' => 'gitflash', 'GIT_AUTHOR_EMAIL' => 'gitflash@localhost',
+      'GIT_COMMITTER_NAME' => 'gitflash', 'GIT_COMMITTER_EMAIL' => 'gitflash@localhost'
+    }.freeze
+    # Content commits get a fixed date so the same content always gives the same sha
+    FIXED_DATE = {
+      'GIT_AUTHOR_DATE' => '1970-01-01T00:00:00Z', 'GIT_COMMITTER_DATE' => '1970-01-01T00:00:00Z'
+    }.freeze
+
+    def initialize(bash: Git::BashCommand)
+      @bash = bash
+    end
+
+    # Snapshot fields except id, time and reason. `branch_names` nil records every branch.
+    def call(scope, branch_names)
+      head_sha = rev('HEAD')
+      state = {
+        scope: Snapshots::SCOPES & scope, worktree_path: git('rev-parse', '--show-toplevel'),
+        head: { branch: current_branch, sha: head_sha },
+        branches: scope.include?('branches') ? branch_tips(branch_names) : {},
+        stashes: scope.include?('stashes') ? try('stash', 'list', '--format=%H').to_s.split : [],
+        index: nil, worktree: nil, skipped_files: []
+      }
+      state.merge!(worktree(head_sha)) if scope.include?('worktree') && dirty?
+      state
+    end
+
+    def commit_tree(tree, parents:, message:, env: {})
+      parent_args = parents.uniq.flat_map { |sha| ['-p', sha] }
+      git('commit-tree', tree, *parent_args, '-m', message, env: IDENTITY.merge(env))
+    end
+
+    def empty_tree
+      @empty_tree ||= git('mktree')
+    end
+
+    private
+
+    def git(*, env: {})
+      @bash.exec('git', *, env: env).strip
+    end
+
+    # Stripped stdout, or nil when the command fails
+    def try(*)
+      stdout, _stderr, success = @bash.capture('git', *)
+      success ? stdout.strip : nil
+    end
+
+    def rev(ref)
+      try('rev-parse', '--verify', '--quiet', "#{ref}^{commit}")
+    end
+
+    def current_branch
+      ref = try('symbolic-ref', '--quiet', 'HEAD')
+      ref&.delete_prefix(Repo::HEADS)
+    end
+
+    def branch_tips(names)
+      tips = Branch.parse_tips(git('for-each-ref', "--format=#{Branch::TIPS_FORMAT}", Repo::HEADS))
+      names.nil? ? tips : tips.slice(*names)
+    end
+
+    def dirty?
+      !git('status', '--porcelain', '--untracked-files=all').empty?
+    end
+
+    def worktree(head_sha)
+      parents = [head_sha].compact
+      index_tree = try('write-tree') # nil while a merge conflict is unresolved
+      tree, skipped = worktree_tree
+      {
+        index: index_tree && content_commit(index_tree, parents, 'gitflash index'),
+        worktree: content_commit(tree, parents, 'gitflash worktree'),
+        skipped_files: skipped
+      }
+    end
+
+    def content_commit(tree, parents, message)
+      commit_tree(tree, parents: parents, message: message, env: FIXED_DATE)
+    end
+
+    # 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', git('rev-parse', '--absolute-git-dir')) do |file|
+        file.close
+        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 }
+
+        git('-C', top, 'add', '--update', env: env)
+        skipped = add_untracked(top, env)
+        [git('write-tree', env: env), skipped]
+      end
+    end
+
+    # [path, size] pairs. A file removed since `ls-files` ran (a build writing temporary files)
+    # is left out, so `git add` is not given a path that is gone.
+    def file_sizes(top, paths)
+      paths.filter_map do |path|
+        [path, File.lstat(File.join(top, path)).size]
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+
+    # Adds untracked files that are not ignored; returns the ones skipped for their size
+    def add_untracked(top, env)
+      paths = git('-C', top, 'ls-files', '-z', '--others', '--exclude-standard')
+              .split("\0").reject { |path| path.end_with?('/') }
+      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) }
+      large
+    end
+  end
+end

data/lib/gitflash/ui.rb

@@ -7,7 +7,7 @@ module Gitflash
   # Menus and confirmations are only shown in a terminal and never in JSON mode.
   #
   # JSON output always uses the same envelope (see schema/v1.json):
-  #   { schema, command, ok, status, dry_run, plan?, result?, error? }
+  #   { schema, command, ok, status, dry_run, plan?, result?, undo?, error? }
   class Ui
     JSON_SCHEMA_VERSION = 1
     OK_STATUSES = %w[done planned noop cancelled].freeze
@@ -33,12 +33,13 @@ module Gitflash
 
     # Reports the outcome of a command and returns its exit status.
     # `status` is one of done, planned, noop, cancelled or failed.
-    def report(status:, text:, plan: nil, result: nil, error: nil)
+    # `fields` may hold plan, result, error and undo (the snapshot that reverts the change).
+    def report(status:, text:, **fields)
       if json?
-        document = envelope(status: status, plan: plan, result: result, error: error)
-        $stdout.puts JSON.generate(document)
+        $stdout.puts JSON.generate(envelope(status: status, **fields))
       else
         $stdout.puts TerminalText.safe(text)
+        $stdout.puts "Undo with: gitflash undo #{fields[:undo].id}" if fields[:undo]
       end
       OK_STATUSES.include?(status) ? 0 : 1
     end
@@ -73,7 +74,7 @@ module Gitflash
 
     private
 
-    def envelope(status:, plan: nil, result: nil, error: nil)
+    def envelope(status:, plan: nil, result: nil, error: nil, undo: nil)
       {
         schema: JSON_SCHEMA_VERSION,
         command: @command,
@@ -82,6 +83,7 @@ module Gitflash
         dry_run: dry_run?,
         plan: plan,
         result: result,
+        undo: undo && { snapshot: undo.id, command: "gitflash undo #{undo.id}" },
         error: error
       }.compact
     end

data/lib/gitflash/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gitflash
-  VERSION = '0.5.1'
+  VERSION = '0.7.0.beta1'
 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 "#{path} is the main checkout" if main?
+      return "#{path} is the current worktree" if current
+
+      in_use_blocker unless force || (missing? && !locked?)
+    end
+
+    def in_use_blocker
+      return "#{path} is locked (use --force)" if locked?
+
+      "#{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

data/lib/gitflash/worktrees.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # The worktrees of the repository. All parsing of `git worktree` output lives here;
+  # callers get Worktree records and never see porcelain text.
+  class Worktrees
+    def initialize(repo:, bash: Git::BashCommand)
+      @repo = repo
+      @bash = bash
+    end
+
+    # Every worktree, main checkout first, each with its dirty state and branch status
+    def list
+      branches = @repo.branches(merged_status: true).to_h { |branch| [branch.name, branch] }
+      records.each_with_index.map { |record, index| build(record, index.zero?, branches) }
+    end
+
+    # How `add` will get the branch: an existing local branch, a new local branch that tracks
+    # origin/<branch>, or a new branch (from HEAD or `start`)
+    def source_for(branch)
+      return :existing if local_branch?(branch)
+
+      remote_branch?(branch) ? :remote : :new
+    end
+
+    # Creates the worktree and returns the git Result. `start` only applies to a new branch.
+    def add(path, branch:, source:, start: nil)
+      args = case source
+             when :existing then [path, branch]
+             when :remote then ['--track', '-b', branch, '--', path, "origin/#{branch}"]
+             else ['-b', branch, '--', path, *start]
+             end
+      args.unshift('--') if source == :existing
+      run('worktree', 'add', *args)
+    end
+
+    # Adds a worktree again for undo: on `branch` (created at `create_at` when it no longer
+    # exists) or detached at `detach_at`. A directory git still lists as missing is reused.
+    def attach(path, branch: nil, create_at: nil, detach_at: nil)
+      force = registered_missing?(path) ? ['--force'] : []
+      return run('worktree', 'add', *force, '--detach', '--', path, detach_at) if detach_at
+      return run('worktree', 'add', *force, '--', path, branch) if local_branch?(branch)
+
+      run('worktree', 'add', *force, '-b', branch, '--', path, create_at)
+    end
+
+    # Ignored files and directories (a directory counts once) of a worktree, which snapshots
+    # do not save. Empty when the directory is missing.
+    def ignored(path)
+      stdout, _stderr, success = @bash.capture('git', '-C', path, 'ls-files', '-z', '--others',
+                                               '--ignored', '--exclude-standard', '--directory')
+      success ? stdout.split("\0") : []
+    end
+
+    def lock(path, reason: nil)
+      run('worktree', 'lock', *(reason ? ['--reason', reason] : []), '--', path)
+    end
+
+    def unlock(path) = run('worktree', 'unlock', '--', path)
+
+    # A locked worktree needs `force`
+    def move(path, destination, force: false)
+      run('worktree', 'move', *(force ? %w[--force --force] : []), '--', path, destination)
+    end
+
+    def prune
+      run('worktree', 'prune')
+    end
+
+    # Removes a worktree directory. A locked one needs `force`, a dirty one too.
+    def remove(path, force: false)
+      run('worktree', 'remove', *(force ? %w[--force --force] : []), '--', path)
+    end
+
+    private
+
+    def registered_missing?(path)
+      wanted = normalized_path(path)
+      list.any? { |worktree| worktree.missing? && normalized_path(worktree.path) == wanted }
+    end
+
+    # Same directory under any spelling (symlinked parents); the directory itself may not exist
+    def normalized_path(path)
+      File.join(File.realpath(File.dirname(path)), File.basename(path))
+    rescue Errno::ENOENT
+      File.expand_path(path)
+    end
+
+    def local_branch?(branch) = ref?("#{Repo::HEADS}#{branch}")
+
+    def remote_branch?(branch) = ref?("#{Repo::REMOTE_HEAD}#{branch}")
+
+    def ref?(full_name)
+      _stdout, _stderr, success = @bash.capture('git', 'show-ref', '--verify', '--quiet', full_name)
+      success
+    end
+
+    def run(*)
+      stdout, stderr, success = @bash.capture('git', *)
+      Result.new(success: success,
+                 output: [stdout, stderr].map(&:strip).reject(&:empty?).join("\n"))
+    end
+
+    def records
+      output = @bash.exec('git', 'worktree', 'list', '--porcelain', '-z')
+      # `-z` ends every attribute with NUL and every record with an extra NUL, so paths with
+      # newlines and lock reasons come back as written
+      output.split("\0\0").reject(&:empty?).map { |block| parse(block) }
+    end
+
+    def parse(block)
+      block.split("\0").reject(&:empty?).to_h do |attribute|
+        key, value = attribute.split(' ', 2)
+        [key, value || true]
+      end
+    end
+
+    def build(record, main, branches)
+      branch = record['branch']&.delete_prefix(Repo::HEADS)
+      Worktree.new(**state(record, main), branch: branch, **branch_status(branches[branch]))
+    end
+
+    def state(record, main)
+      path = record.fetch('worktree')
+      missing = record.key?('prunable') || !File.directory?(path)
+      bare = record.key?('bare')
+      { path: path, head: record['HEAD'], main: main, bare: bare, missing: missing,
+        locked: record.key?('locked'), lock_reason: lock_reason(record['locked']),
+        dirty: dirty(path, missing, bare) }
+    end
+
+    def branch_status(info)
+      { ahead: info&.ahead, behind: info&.behind, merged: info&.merged, owner: info&.owner }
+    end
+
+    def lock_reason(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+
+    def dirty(path, missing, bare)
+      return nil if missing || bare
+
+      stdout, _stderr, success = @bash.capture('git', '-C', path, 'status', '--porcelain')
+      success ? !stdout.strip.empty? : nil
+    end
+  end
+end