gitflash 0.5.1 → 0.6.0

data/lib/gitflash/restore.rb

@@ -0,0 +1,140 @@
+# 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
+
+    def empty?
+      plan[:branches].empty? && plan[:head].nil? && !plan[:worktree] && plan[:stashes].empty?
+    end
+
+    # Applies the plan; returns nil on success or the failed step's Result
+    def apply
+      steps.each do |args|
+        result = run(*args)
+        return result unless result.success?
+      end
+      nil
+    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

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', File.expand_path(git('rev-parse', '--git-dir'))) do |file|
+        file.close
+        real_index = File.expand_path(git('rev-parse', '--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.6.0'
 end