thuban 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73f95adb20a42969a69908bab030d4939a94a1bd0bc9ddcacbb9b95dff3dd6a9
-  data.tar.gz: 8ebf2299e31de698cfae6b7487a7722703f50d4fd5a0820adf6e6c35d1eb2616
+  metadata.gz: a397fe928169662180d71c9c3c9df55eabd167eca7b300d01aaf4db57a5b5d16
+  data.tar.gz: 6cc6e1ed699ada02e46bf3623ca03dd73012ef9163b7b7a270889cbd1f817dcd
 SHA512:
-  metadata.gz: 97e8fe6cbbfa497234aafc55a4c49f0d9775721451c2e32a1882d4d15066d079cf1544ef41c48bff61230297ad7191b64da8de5b2a63636a6224516037d9b9da
-  data.tar.gz: 889372feb5805cdfb126a1f9668700abda26307b6617be36556e917050c90270aff58e9e193dc3bad832d9be2aa15f41b885466801c3f8f5bed27de38588945c
+  metadata.gz: 006ee4c48ee212ce1e70df30691e743bc0e1f798789d53a1afdc64ad643eba50a85a32f2e0c36e2fb043a3b7680225ee9b140153ef7374e636d1b96b81c1756a
+  data.tar.gz: 216cf9908627ff5655820f6d85b9499921aa89424bc5461df35c8d100392d9206c613f1b179850ce5a887d69839d32ce2fc7a481e7324ed5498737eb5323c31e

data/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
-## Unreleased
+## 0.6.0 - 2026-09-17
+
+- Add transactional repository-level merge conflict resolution with stale-state checks and Git-compatible type status.
 
 ## 0.5.0 - 2026-09-17
 

data/README.md

@@ -48,7 +48,7 @@ repository operations work directly with Git data without invoking the Git execu
 Add Thuban to your Gemfile:
 
 ```ruby
-gem "thuban", "~> 0.5.0"
+gem "thuban", "~> 0.6.0"
 ```
 
 Then install it:
@@ -168,6 +168,24 @@ removes the stage-zero entry; stage the corresponding HEAD entry to restore a
 tracked path. `conflicts` exposes stage 1/2/3 entries and `resolve` replaces
 them with a stage-zero entry.
 
+For a transactional index and worktree update, capture a repository conflict
+and resolve that exact snapshot:
+
+```ruby
+conflict = repo.conflicts.first
+repo.resolve_conflict(conflict, choice: :ours) # :theirs or :both
+repo.resolve_conflict(conflict, choice: :manual, content: edited, mode: 0o100644)
+```
+
+`:ours` and `:theirs` also resolve a deleted side. `:both` performs a text
+three-way merge and places ours before theirs in remaining regions. Binary and
+symlink conflicts can be selected unchanged or replaced with `:manual`; they
+cannot use `:both`. HEAD and the index are locked, and the captured worktree is
+revalidated at each write boundary. A change observed there raises
+`RefLockError` before the index or worktree is changed; uncoordinated writes
+racing the final atomic replacement require external coordination. Other
+unresolved paths remain in the index.
+
 Create and update refs with optimistic old-OID checks:
 
 ```ruby

data/lib/thuban/conflict_resolution.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Thuban
+  ConflictWorktree = Struct.new(:kind, :content, :mode, keyword_init: true)
+  Conflict = Struct.new(:path, :base, :ours, :theirs, :head, :worktree, :index_checksum, keyword_init: true)
+
+  class Repository
+    CONFLICT_CHOICES = %i[ours theirs both manual].freeze
+    CONFLICT_FILE_MODES = [0o100644, 0o100755, 0o120000].freeze
+
+    def conflicts
+      current_index = index
+      checksum = current_index.send(:source_checksum)
+      current_head = head
+      current_index.conflicts.group_by(&:path).sort.map do |path, entries|
+        current_index.send(:validate_path, path)
+        all_entries = current_index.entries.select { |entry| entry.path == path }
+        stages = all_entries.to_h { |entry| [entry.stage, entry] }
+        raise CorruptObject, "invalid conflict entries for #{path}" unless
+          stages.length == all_entries.length && !stages.key?(0) && stages.keys.all? { |stage| (1..3).cover?(stage) }
+
+        Conflict.new(path: path.dup.freeze, base: conflict_entry(stages[1]), ours: conflict_entry(stages[2]),
+          theirs: conflict_entry(stages[3]), head: current_head&.dup&.freeze,
+          worktree: conflict_worktree(path), index_checksum: checksum.dup.freeze).freeze
+      end
+    end
+
+    def resolve_conflict(conflict, choice:, content: nil, mode: nil)
+      raise ArgumentError, "expected a Thuban::Conflict" unless conflict.is_a?(Conflict)
+      raise ArgumentError, "invalid conflict choice" unless CONFLICT_CHOICES.include?(choice)
+      raise ArgumentError, "unsafe conflict worktree type" unless %i[missing file symlink].include?(conflict.worktree.kind)
+
+      current_index = index
+      current_index.send(:validate_path, conflict.path)
+      entries = current_index.entries.dup
+      worktree = {}
+      removed = []
+      validate = ->(locked_index, backups) { validate_conflict_snapshot!(conflict, locked_index, backups.fetch(conflict.path)) }
+
+      RefStore.new(self).send(:with_lock, "HEAD", old_oid: conflict.head) do
+        replace_repository_state(worktree, entries, remove_paths: removed, affected_paths: [conflict.path],
+          current_index: current_index, validate: validate) do
+          selected = conflict_resolution(conflict, choice, content, mode)
+          entries.reject! { |entry| entry.path == conflict.path }
+          if selected
+            entry, data = selected
+            entries << entry
+            worktree[conflict.path] = TreeEntry.new(path: conflict.path, oid: entry.oid, mode: entry.mode)
+            type, stored = odb.read(entry.oid)
+            raise CorruptObject, "conflict entry is not a blob" unless type == "blob" && stored == data
+          else
+            removed << conflict.path
+          end
+        end
+      end
+      conflict.path
+    end
+
+    private
+
+    def conflict_entry(entry)
+      return unless entry
+
+      copy = entry.dup
+      copy.path = copy.path.dup.freeze
+      copy.oid = copy.oid.dup.freeze
+      copy.freeze
+    end
+
+    def conflict_worktree(path)
+      absolute = worktree_path(path)
+      stat = File.lstat(absolute)
+      if stat.symlink?
+        ConflictWorktree.new(kind: :symlink, content: File.readlink(absolute).b.freeze, mode: 0o120000).freeze
+      elsif stat.file?
+        mode = 0o100000 | ((stat.mode & 0o100).positive? ? 0o755 : 0o644)
+        ConflictWorktree.new(kind: :file, content: File.binread(absolute).freeze, mode: mode).freeze
+      elsif stat.directory?
+        ConflictWorktree.new(kind: :directory, content: nil, mode: 0o040000).freeze
+      else
+        ConflictWorktree.new(kind: :other, content: nil, mode: stat.mode & 0o170000).freeze
+      end
+    rescue Errno::ENOENT, Errno::ENOTDIR
+      ConflictWorktree.new(kind: :missing, content: nil, mode: nil).freeze
+    end
+
+    def conflict_resolution(conflict, choice, content, mode)
+      case choice
+      when :ours, :theirs
+        raise ArgumentError, "content and mode are only accepted for both or manual resolution" if content || mode
+        entry = conflict.public_send(choice)
+        entry && conflict_selected_entry(conflict.path, entry, read_conflict_blob(entry))
+      when :both
+        raise ArgumentError, "content is only accepted for manual resolution" if content
+        conflict_both_resolution(conflict, mode)
+      when :manual
+        raise ArgumentError, "manual resolution requires String content" unless content.is_a?(String)
+        selected_mode = conflict_resolution_mode(conflict, mode)
+        conflict_selected_entry(conflict.path, nil, content.b, mode: selected_mode)
+      end
+    end
+
+    def conflict_both_resolution(conflict, mode)
+      raise ArgumentError, "both resolution requires ours and theirs" unless conflict.ours && conflict.theirs
+      sides = [conflict.base, conflict.ours, conflict.theirs].compact
+      raise ArgumentError, "both resolution only supports regular files" unless
+        sides.all? { |entry| [0o100644, 0o100755].include?(entry.mode) }
+
+      base = conflict.base ? read_conflict_blob(conflict.base) : "".b
+      ours = read_conflict_blob(conflict.ours)
+      theirs = read_conflict_blob(conflict.theirs)
+      raise ArgumentError, "both resolution does not support binary files" if [base, ours, theirs].any? { |value| value.include?("\0") }
+
+      result = Porrima::Merge.three_way(base: base, ours: ours, theirs: theirs)
+      data = Porrima::Merge.to_resolved_text(Porrima::Merge.resolve_all(result, :ours_then_theirs))
+      conflict_selected_entry(conflict.path, nil, data, mode: conflict_resolution_mode(conflict, mode, regular: true))
+    end
+
+    def conflict_resolution_mode(conflict, mode, regular: false)
+      allowed = regular ? CONFLICT_FILE_MODES.first(2) : CONFLICT_FILE_MODES
+      if mode
+        raise ArgumentError, "invalid conflict resolution mode" unless allowed.include?(mode)
+        return mode
+      end
+
+      modes = [conflict.ours, conflict.theirs].compact.map(&:mode).uniq
+      raise ArgumentError, "conflict resolution mode is ambiguous" unless modes.length == 1 && allowed.include?(modes.first)
+
+      modes.first
+    end
+
+    def conflict_selected_entry(path, source, content, mode: source&.mode)
+      raise ArgumentError, "submodule conflicts require separate worktree handling" unless CONFLICT_FILE_MODES.include?(mode)
+
+      oid = source&.oid || write_blob(content)
+      [Index::Entry.new(path: path, oid: oid, mode: mode, size: 0, mtime: 0, mtime_nsec: 0,
+        ctime: 0, ctime_nsec: 0, dev: 0, ino: 0, uid: 0, gid: 0, stage: 0, flags: 0, extended_flags: 0), content]
+    end
+
+    def read_conflict_blob(entry)
+      raise ArgumentError, "submodule conflicts require separate worktree handling" if entry.mode == 0o160000
+      type, content = odb.read(entry.oid)
+      raise CorruptObject, "conflict entry is not a blob" unless type == "blob"
+
+      content
+    end
+
+    def validate_conflict_snapshot!(conflict, current_index, worktree_backup)
+      expected = [conflict.base, conflict.ours, conflict.theirs].compact.map do |entry|
+        [entry.path, entry.stage, entry.mode, entry.oid]
+      end.sort_by { |entry| entry[1] }
+      actual = current_index.entries.select { |entry| entry.path == conflict.path }.map do |entry|
+        [entry.path, entry.stage, entry.mode, entry.oid]
+      end.sort_by { |entry| entry[1] }
+      stale = conflict.head != head || conflict.index_checksum != current_index.send(:source_checksum) ||
+        expected != actual || actual.empty? || actual.any? { |entry| entry[1].zero? } ||
+        conflict.worktree != conflict_worktree_backup(worktree_backup) ||
+        conflict.worktree != conflict_worktree(conflict.path)
+      raise RefLockError, "Git conflict changed since it was read" if stale
+    end
+
+    def conflict_worktree_backup(backup)
+      case backup&.first
+      when :symlink
+        ConflictWorktree.new(kind: :symlink, content: backup[1].freeze, mode: 0o120000).freeze
+      when :file
+        mode = 0o100000 | ((backup[2] & 0o100).positive? ? 0o755 : 0o644)
+        ConflictWorktree.new(kind: :file, content: backup[1].freeze, mode: mode).freeze
+      else
+        ConflictWorktree.new(kind: :missing, content: nil, mode: nil).freeze
+      end
+    end
+  end
+end

data/lib/thuban/history_writer.rb

@@ -156,21 +156,14 @@ module Thuban
       raise ArgumentError, "worktree/index must be clean" if status.any? { |entry| entry.index != "?" }
     end
 
-    def replace_repository_state(worktree_tree, index_tree, remove_paths: [])
+    def replace_repository_state(worktree_tree, index_tree, remove_paths: [], affected_paths: nil, current_index: nil,
+      validate: nil)
       raise ArgumentError, "bare repository has no worktree" unless root
-      current_index = index
-      current = current_index.entries.to_h { |entry| [entry.path, entry] }
+      current_index ||= index
+      current = current_index.entries.group_by(&:path).transform_values { |entries| entries.find { |entry| entry.stage.zero? } || entries.first }
       tracked = head ? tree(head).merge(current) : current
-      raise ArgumentError, "submodule updates require separate worktree handling" if
-        (tracked.values + worktree_tree.values + index_tree.values).any? { |entry| entry.mode == 0o160000 }
-
-      removed = (tracked.keys - worktree_tree.keys) | remove_paths
-      check_worktree_collisions(worktree_tree, tracked, removed)
-      contents = worktree_tree.to_h { |path, entry| [path, odb.read(entry.oid).last] }
-      affected = (tracked.keys | worktree_tree.keys | remove_paths)
-      backups = affected.to_h { |path| [path, worktree_backup(path)] }
+      affected = affected_paths || (tracked.keys | worktree_tree.keys | remove_paths)
       index_path = File.join(git_dir, "index")
-      index_backup = File.file?(index_path) ? [File.binread(index_path), File.stat(index_path).mode & 0o777] : nil
       lock_path = index_path + ".lock"
       begin
         lock = File.open(lock_path, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o644)
@@ -178,19 +171,38 @@ module Thuban
         raise IOError, "Git index is locked: #{lock_path}"
       end
       owns_lock = true
+      changed = false
       begin
         raise RefLockError, "Git index changed since it was read" unless current_index.send(:source_unchanged?)
-
-        write_worktree_tree(worktree_tree, contents, removed)
+        backups = affected.to_h { |path| [path, worktree_backup(path)] }
+        index_backup = File.file?(index_path) ? [File.binread(index_path), File.stat(index_path).mode & 0o777] : nil
+        validate&.call(current_index, backups)
+        yield current_index if block_given?
+
+        raise ArgumentError, "repository state update escaped its affected paths" unless
+          (worktree_tree.keys | remove_paths).all? { |path| affected.include?(path) }
+        candidates = current_index.entries + worktree_tree.values + index_target_entries(index_tree)
+        candidates.select! { |entry| affected.include?(entry.path) } if affected_paths
+        raise ArgumentError, "submodule updates require separate worktree handling" if candidates.any? { |entry| entry.mode == 0o160000 }
+
+        removed = affected_paths ? ((affected - worktree_tree.keys) | remove_paths) : ((tracked.keys - worktree_tree.keys) | remove_paths)
+        check_worktree_collisions(worktree_tree, tracked, removed)
+        contents = worktree_tree.to_h { |path, entry| [path, odb.read(entry.oid).last] }
+        validate&.call(current_index, backups)
+        write_worktree_tree(worktree_tree, contents, removed) do
+          validate&.call(current_index, backups)
+          changed = true
+        end
         extensions = current_index.extensions.reject { |extension| Index::ENTRY_DEPENDENT_EXTENSIONS.include?(extension.byteslice(0, 4)) }
-        lock.write(Index.encode(index_entries(index_tree), extensions: extensions, version: current_index.version))
+        entries = index_tree.is_a?(Array) ? refresh_index_entries(index_tree, worktree_tree, affected) : index_entries(index_tree)
+        lock.write(Index.encode(entries, extensions: extensions, version: current_index.version))
         lock.flush
         lock.fsync
         lock.close
         File.rename(lock_path, index_path)
         owns_lock = false
       rescue StandardError
-        restore_worktree(backups, affected)
+        restore_worktree(backups, affected) if changed
         raise
       ensure
         lock&.close unless lock&.closed?
@@ -199,13 +211,33 @@ module Thuban
       -> { restore_repository_state(backups, affected, index_path, index_backup) }
     end
 
+    def index_target_entries(target)
+      target.is_a?(Array) ? target : target.values
+    end
+
+    def refresh_index_entries(entries, worktree_tree, affected)
+      entries.map do |entry|
+        target = worktree_tree[entry.path]
+        next entry unless entry.stage.zero? && target && affected.include?(entry.path)
+
+        stat = matching_worktree_stat(entry.path, target)
+        Index::Entry.new(path: entry.path, oid: entry.oid, mode: entry.mode, size: stat&.size.to_i,
+          mtime: stat&.mtime.to_i, mtime_nsec: stat&.mtime&.nsec.to_i,
+          ctime: stat&.ctime.to_i, ctime_nsec: stat&.ctime&.nsec.to_i,
+          dev: stat&.dev.to_i, ino: stat&.ino.to_i, uid: stat&.uid.to_i, gid: stat&.gid.to_i,
+          stage: 0, flags: 0, extended_flags: 0)
+      end
+    end
+
     def write_worktree_tree(target, contents, removed)
       removed.sort_by { |path| -path.count("/") }.each do |path|
+        yield if block_given?
         absolute = worktree_path(path)
         File.unlink(absolute) if File.file?(absolute) || File.symlink?(absolute)
       end
       prune_empty_directories(removed)
       target.sort.each do |path, entry|
+        yield if block_given?
         absolute = worktree_path(path)
         Dir.rmdir(absolute) if File.directory?(absolute) && !File.symlink?(absolute)
         FileUtils.mkdir_p(File.dirname(absolute))

data/lib/thuban/index.rb

@@ -76,6 +76,8 @@ module Thuban
 
     private
 
+    def source_checksum = @source_checksum
+
     def parse(bytes)
       raise CorruptObject, "invalid Git index" unless bytes.bytesize >= 32 && bytes.start_with?("DIRC")
       raise CorruptObject, "Git index checksum mismatch" unless Digest::SHA1.digest(bytes[0...-20]) == bytes[-20, 20]

data/lib/thuban/ref_store.rb

@@ -89,6 +89,18 @@ module Thuban
 
     attr_reader :repository
 
+    def with_lock(name, old_oid: :any)
+      validate_ref(name)
+      target = dereference(name)
+      paths = [ref_path(target)]
+      paths << ref_path(name) if target != name
+      with_locks(paths) do
+        raise RefLockError, "symbolic reference changed: #{name}" unless dereference(name) == target
+        verify_old_oid(name, repository.resolve(target), old_oid)
+        yield
+      end
+    end
+
     def validate_ref(name, head: true)
       return if head && name == "HEAD"
       invalid = !name.is_a?(String) || !name.start_with?("refs/") || name.end_with?("/", ".") ||

data/lib/thuban/status.rb

@@ -29,6 +29,7 @@ module Thuban
         original = head[path]
         x = if !original then "A"
         elsif !staged then "D"
+        elsif (original.mode & 0o170000) != (staged.mode & 0o170000) then "T"
         elsif original.mode != staged.mode || original.oid != staged.oid then "M"
         else " " end
         y = staged ? worktree_status(staged, index.path, filemode) : " "

data/lib/thuban/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Thuban
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/thuban.rb

@@ -23,6 +23,7 @@ require_relative "thuban/ref_lock_error"
 require_relative "thuban/ref_store"
 require_relative "thuban/commit_writer"
 require_relative "thuban/history_writer"
+require_relative "thuban/conflict_resolution"
 require_relative "thuban/stash"
 require_relative "thuban/pack_writer"
 require_relative "thuban/pack_reader"

data/sig/thuban.rbs

@@ -98,6 +98,24 @@ module Thuban
     def self.new: (path: String, oid: String, mode: Integer) -> instance
   end
 
+  class ConflictWorktree < Struct[untyped]
+    attr_accessor kind: :missing | :file | :symlink | :directory | :other
+    attr_accessor content: String?
+    attr_accessor mode: Integer?
+    def self.new: (kind: (:missing | :file | :symlink | :directory | :other), content: String?, mode: Integer?) -> instance
+  end
+
+  class Conflict < Struct[untyped]
+    attr_accessor path: String
+    attr_accessor base: Index::Entry?
+    attr_accessor ours: Index::Entry?
+    attr_accessor theirs: Index::Entry?
+    attr_accessor head: String?
+    attr_accessor worktree: ConflictWorktree
+    attr_accessor index_checksum: String?
+    def self.new: (path: String, base: Index::Entry?, ours: Index::Entry?, theirs: Index::Entry?, head: String?, worktree: ConflictWorktree, index_checksum: String?) -> instance
+  end
+
   class Signature < Struct[untyped]
     attr_accessor name: String
     attr_accessor email: String
@@ -162,6 +180,8 @@ module Thuban
     def reset: (String oid, ?mode: :soft | :mixed | :hard) -> String
     def cherry_pick: (String oid) -> String
     def revert: (String oid) -> String
+    def conflicts: () -> Array[Conflict]
+    def resolve_conflict: (Conflict conflict, choice: (:ours | :theirs | :both | :manual), ?content: String?, ?mode: Integer?) -> String
     def stash_push: (?message: String?, ?include_untracked: bool) -> String?
     def stash_pop: (?Integer index) -> String
     def stash_list: () -> Array[Commit]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thuban
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -36,6 +36,7 @@ files:
 - lib/thuban/blame.rb
 - lib/thuban/commit.rb
 - lib/thuban/commit_writer.rb
+- lib/thuban/conflict_resolution.rb
 - lib/thuban/corrupt_object.rb
 - lib/thuban/history_writer.rb
 - lib/thuban/ignore_matcher.rb