gitflash 0.5.0 → 0.6.0

data/lib/gitflash/repo.rb

@@ -6,12 +6,14 @@ module Gitflash
   class Repo
     SEPARATOR = "\x1f"
     BRANCH_FORMAT = %w[
-      refname:short objectname:short HEAD upstream:short upstream:track,nobracket
+      refname objectname:short HEAD upstream:short upstream:track,nobracket
       committerdate:iso-strict authorname subject
     ].map { |field| "%(#{field})" }.join('%1f')
     COMMIT_FORMAT = %w[%h %s %an %cI].join('%x1f')
     COMMITS_LIMIT = 100
     FALLBACK_DEFAULT_BRANCHES = %w[main master].freeze
+    HEADS = 'refs/heads/'
+    REMOTE_HEAD = 'refs/remotes/origin/'
 
     def initialize(bash: Git::BashCommand)
       @bash = bash
@@ -37,11 +39,21 @@ module Gitflash
       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)
 
-      @default_branch = default_ref&.delete_prefix('origin/')
+      @default_branch = branch_name(default_ref)
     end
 
     # Commits of the current branch, newest first. Empty for a branch without commits.
@@ -54,17 +66,22 @@ module Gitflash
 
     # Full sha of a commit reference, or nil when it does not name a commit
     def resolve_commit(ref)
+      return nil if ref.start_with?('-')
+
       stdout, _stderr, success = @bash.capture('git', 'rev-parse', '--verify', '--quiet',
                                                "#{ref}^{commit}")
       success ? stdout.strip : nil
     end
 
+    # Uses `git switch`, which never discards changes or treats the name as a file path.
+    # A name that starts with a dash is refused: a ref named like an option must not become one.
     def checkout(branch)
-      run('git', 'checkout', branch, '--')
+      refuse_option_like!(branch)
+      run('git', 'switch', '--', branch)
     end
 
     def delete_branch(branch, force: false)
-      run('git', 'branch', force ? '-D' : '-d', branch)
+      run('git', 'branch', force ? '-D' : '-d', '--', branch)
     end
 
     def reset(commit, mode:)
@@ -73,13 +90,27 @@ module Gitflash
 
     private
 
+    # Removes only the prefix the ref starts with, so a branch named `refs/heads/x` keeps its name
+    def branch_name(ref)
+      return nil unless ref
+
+      ref.delete_prefix(ref.start_with?(REMOTE_HEAD) ? REMOTE_HEAD : HEADS)
+    end
+
+    def refuse_option_like!(name)
+      return unless name.start_with?('-')
+
+      raise UsageError.new("Invalid branch name '#{name}'", code: 'invalid_usage')
+    end
+
     def branch_lines
       @branch_lines ||= @bash.exec('git', 'for-each-ref', "--format=#{BRANCH_FORMAT}",
-                                   'refs/heads/')
+                                   HEADS)
                              .each_line(chomp: true).reject(&:empty?)
     end
 
-    # Ref used to check merge status: origin/HEAD's target, else a local main/master
+    # Full ref used to check merge status: origin/HEAD's target, else a local main/master.
+    # Full names are used throughout because short names change when a tag has the same name.
     def default_ref
       return @default_ref if defined?(@default_ref)
 
@@ -87,24 +118,23 @@ module Gitflash
     end
 
     def remote_default_ref
-      ref = @bash.exec('git', 'symbolic-ref', '--quiet', '--short',
-                       'refs/remotes/origin/HEAD').strip
-      ref.empty? ? nil : ref
+      ref = @bash.exec('git', 'symbolic-ref', '--quiet', "#{REMOTE_HEAD}HEAD").strip
+      ref.start_with?(REMOTE_HEAD) ? ref : nil
     rescue Git::CommandError
       nil
     end
 
     def local_default_branch
-      names = branch_lines.map { |line| line.split(SEPARATOR, 2).first }
-      FALLBACK_DEFAULT_BRANCHES.find { |name| names.include?(name) }
+      names = branch_lines.map { |line| line.split(SEPARATOR, 2).first.delete_prefix(HEADS) }
+      name = FALLBACK_DEFAULT_BRANCHES.find { |candidate| names.include?(candidate) }
+      name && "#{HEADS}#{name}"
     end
 
     def merged_branch_names
       return nil unless default_ref
 
-      @bash.exec('git', 'for-each-ref', "--merged=#{default_ref}", '--format=%(refname:short)',
-                 'refs/heads/')
-           .each_line(chomp: true).to_set
+      @bash.exec('git', 'for-each-ref', "--merged=#{default_ref}", '--format=%(refname)', HEADS)
+           .each_line(chomp: true).to_set { |ref| ref.delete_prefix(HEADS) }
     end
 
     def run(*)

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Makes text from the repository safe to print in a terminal. Commit subjects, author names
+  # and git messages are written by other people; control characters in them could move the
+  # cursor, rewrite earlier output or set the clipboard (OSC 52). They are shown as escapes.
+  # Newlines and tabs stay.
+  module TerminalText
+    UNSAFE = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/
+
+    module_function
+
+    def safe(text)
+      text.to_s.scrub.gsub(UNSAFE) do |char|
+        format(char.ord > 0xFF ? '\\u%04X' : '\\x%02X', char.ord)
+      end
+    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 text
+        $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
@@ -48,7 +49,7 @@ module Gitflash
         details = { code: error.code, message: error.message, exit_code: error.exit_code }
         $stdout.puts JSON.generate(envelope(status: error.status, plan: error.plan, error: details))
       else
-        warn error.message
+        warn TerminalText.safe(error.message)
       end
     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.0'
+  VERSION = '0.6.0'
 end