git 4.3.2 → 5.0.0.beta.1

data/lib/git/log.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'git/base'
+
 module Git
   # Builds and executes a `git log` query
   #
@@ -42,7 +44,7 @@ module Git
     #   git = Git.open('.')
     #   Git::Log.new(git)
     #
-    # @param base [Git::Base] the git repository object
+    # @param base [Git::Repository, Git::Base] the git repository object
     # @param max_count [Integer, Symbol, nil] the number of commits to return, or
     #   `:all` or `nil` to return all
     #
@@ -157,10 +159,21 @@ module Git
       self
     end
 
+    # Returns the facade interface for log operations.
+    #
+    # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
+    # The `is_a?` guard will be removed when {Git::Base} is deleted in Phase 4.
+    #
+    # @return [Git::Repository]
+    #
+    def log_repository
+      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+    end
+
     def run_log_if_dirty
       return unless @dirty
 
-      log_data = @base.lib.full_log_commits(@options)
+      log_data = log_repository.full_log_commits(@options)
       @commits = log_data.map { |c| Git::Object::Commit.new(@base, c['sha'], c) }
       @dirty = false
     end

data/lib/git/object.rb

@@ -4,6 +4,7 @@ require 'git/author'
 require 'git/diff'
 require 'git/errors'
 require 'git/log'
+require 'git/base'
 
 module Git
   # represents a git object
@@ -24,24 +25,55 @@ module Git
       end
 
       def sha
-        @sha ||= @base.lib.rev_parse(@objectish)
+        @sha ||= object_repository.rev_parse(@objectish)
       end
 
       def size
-        @size ||= @base.lib.cat_file_size(@objectish)
+        @size ||= object_repository.cat_file_size(@objectish)
       end
 
-      # Get the object's contents.
-      # If no block is given, the contents are cached in memory and returned as a string.
-      # If a block is given, it yields an IO object (via IO::popen) which could be used to
-      # read a large file in chunks.
+      # Returns the raw content of this git object or streams it into a temporary file
+      #
+      # Without a block, the full content is buffered in memory and cached, then
+      # returned as a `String`. With a block, git output is streamed directly to a
+      # temporary file on disk — suitable for large objects.
+      #
+      # @api public
+      #
+      # @overload contents
+      #   Returns the cached content as a string.
+      #
+      #   @return [String] the raw content of the object, cached after first call
+      #
+      #   @raise [Git::FailedError] if the object does not exist or the command fails
+      #
+      #   @example Get the contents of a blob
+      #     git.object('HEAD:README.md').contents # => "This is a README file\n"
+      #
+      # @overload contents(&block)
+      #   Streams the content to a temporary file and yields it.
+      #
+      #   Git output is written directly to a file without buffering in
+      #   memory. Use this form for large blobs to avoid memory pressure.
+      #
+      #   @yield [file] the temporary file, positioned at the start of the content
+      #
+      #   @yieldparam file [File] readable `IO` object positioned at the beginning
+      #
+      #   @yieldreturn [Object] the value to return from this method
+      #
+      #   @return [Object] the value returned by the block
+      #
+      #   @raise [Git::FailedError] if the object does not exist or the command fails
+      #
+      #   @example Read a large blob without loading it into memory
+      #     git.object('HEAD:large_file.bin').contents { |f| upload(f) }
       #
-      # Use this for large files so that they are not held in memory.
       def contents(&)
         if block_given?
-          @base.lib.cat_file_contents(@objectish, &)
+          object_repository.cat_file_contents(@objectish, &)
         else
-          @contents ||= @base.lib.cat_file_contents(@objectish)
+          @contents ||= object_repository.cat_file_contents(@objectish)
         end
       end
 
@@ -54,8 +86,7 @@ module Git
       end
 
       def grep(string, path_limiter = nil, opts = {})
-        opts = { object: sha, path_limiter: path_limiter }.merge(opts)
-        @base.lib.grep(string, opts)
+        object_repository.grep(string, path_limiter, opts.merge(object: sha))
       end
 
       def diff(objectish)
@@ -66,9 +97,23 @@ module Git
         Git::Log.new(@base, count).object(@objectish)
       end
 
-      # creates an archive of this object (tree)
+      # Creates an archive of this object and writes it to a file
+      #
+      # @api public
+      #
+      # @param file [String, nil] destination file path; a temp file is created if `nil`
+      #
+      # @param opts [Hash] archive options (see {Git::Lib#archive})
+      #
+      # @return [String] the path to the written archive file
+      #
+      # @raise [Git::FailedError] if `git archive` fails
+      #
+      # @example Archive a tree to a zip file
+      #   git.object('v1.0').archive('/tmp/release.zip', format: 'zip')
+      #
       def archive(file = nil, opts = {})
-        @base.lib.archive(@objectish, file, opts)
+        object_repository.archive(@objectish, file, opts)
       end
 
       def tree? = false
@@ -78,6 +123,19 @@ module Git
       def commit? = false
 
       def tag? = false
+
+      private
+
+      # Returns the facade interface for git object queries.
+      #
+      # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
+      # The `is_a?` guard will be removed when {Git::Base} is deleted in Phase 4.
+      #
+      # @return [Git::Repository]
+      #
+      def object_repository
+        @base.is_a?(Git::Base) ? @base.facade_repository : @base
+      end
     end
 
     # A Git blob object
@@ -117,11 +175,11 @@ module Git
       alias subdirectories trees
 
       def full_tree
-        @base.lib.full_tree(@objectish)
+        object_repository.full_tree(@objectish)
       end
 
       def depth
-        @base.lib.tree_depth(@objectish)
+        object_repository.tree_depth(@objectish)
       end
 
       def tree?
@@ -135,7 +193,7 @@ module Git
         @trees = {}
         @blobs = {}
 
-        data = @base.lib.ls_tree(@objectish)
+        data = object_repository.ls_tree(@objectish)
 
         data['tree'].each do |key, tree|
           @trees[key] = Git::Object::Tree.new(@base, tree[:sha], tree[:mode])
@@ -169,7 +227,7 @@ module Git
       end
 
       def name
-        @base.lib.name_rev(sha)
+        object_repository.name_rev(sha)
       end
 
       def gtree
@@ -239,7 +297,7 @@ module Git
       def check_commit
         return if @tree
 
-        data = @base.lib.cat_file_commit(@objectish)
+        data = object_repository.cat_file_commit(@objectish)
         from_data(data)
       end
     end
@@ -268,7 +326,8 @@ module Git
       def initialize(base, sha, name = nil)
         if name.nil?
           name = sha
-          sha = base.lib.tag_sha(name)
+          repo = base.is_a?(Git::Base) ? base.facade_repository : base
+          sha = repo.tag_sha(name)
           raise Git::UnexpectedResultError, "Tag '#{name}' does not exist." if sha == ''
         end
 
@@ -280,7 +339,7 @@ module Git
       end
 
       def annotated?
-        @annotated = @annotated.nil? ? (@base.lib.cat_file_type(name) == 'tag') : @annotated
+        @annotated = @annotated.nil? ? (object_repository.cat_file_type(name) == 'tag') : @annotated
       end
 
       def message
@@ -303,7 +362,7 @@ module Git
         return if @loaded
 
         if annotated?
-          tdata = @base.lib.cat_file_tag(@name)
+          tdata = object_repository.cat_file_tag(@name)
           @message = tdata['message'].chomp
           @tagger = Git::Author.new(tdata['tagger'])
         else
@@ -319,7 +378,7 @@ module Git
     def self.new(base, objectish, type = nil, is_tag = false) # rubocop:disable Style/OptionalBooleanParameter
       return new_tag(base, objectish) if is_tag
 
-      type ||= base.lib.cat_file_type(objectish)
+      type ||= object_repository_for(base).cat_file_type(objectish)
       # TODO: why not handle tag case here too?
       klass =
         case type
@@ -334,5 +393,16 @@ module Git
       Git::Deprecation.warn('Git::Object.new with is_tag argument is deprecated. Use Git::Object::Tag.new instead.')
       Git::Object::Tag.new(base, objectish)
     end
+
+    # Returns the facade interface for git object queries.
+    #
+    # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
+    # The `is_a?` guard will be removed when {Git::Base} is deleted in Phase 4.
+    #
+    # @return [Git::Repository]
+    #
+    private_class_method def self.object_repository_for(base)
+      base.is_a?(Git::Base) ? base.facade_repository : base
+    end
   end
 end

data/lib/git/parsers/branch.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'git/branch_info'
+require 'git/branch_delete_result'
+require 'git/branch_delete_failure'
+
+module Git
+  module Parsers
+    # Parser for git branch command output
+    #
+    # Handles parsing of `git branch --list` and `git branch --delete` output
+    # into structured data objects.
+    #
+    # ## Design Note: Namespace Organization
+    #
+    # This parser creates and returns {Git::BranchInfo} and {Git::BranchDeleteResult}
+    # objects, which live at the top-level `Git::` namespace rather than within
+    # `Git::Parsers::`. This is intentional:
+    #
+    # - **Parsers are infrastructure** - marked `@api private`, users shouldn't
+    #   interact with them directly
+    # - **Info/Result classes are public API** - returned by commands and used
+    #   throughout the codebase
+    # - **Info classes are domain entities** - represent core git concepts
+    #   (branches as data)
+    # - **Result classes are operation outcomes** - represent command results,
+    #   not parsing details
+    #
+    # Keeping Info/Result classes at `Git::` improves discoverability and correctly
+    # reflects their role as public types rather than parser internals.
+    #
+    # @api private
+    #
+    module Branch
+      # Format string for git branch --format
+      #
+      # Fields (pipe-delimited):
+      # 1. refname - full ref name (e.g., refs/heads/main, refs/remotes/origin/main)
+      # 2. objectname - full SHA of the commit the branch points to
+      # 3. HEAD - '*' if current branch, empty otherwise
+      # 4. worktreepath - path if checked out in another worktree, empty otherwise
+      # 5. symref - target ref if symbolic reference, empty otherwise
+      # 6. upstream - full upstream ref (e.g., refs/remotes/origin/main), empty if none
+      #
+      FORMAT_STRING = '%(refname)|%(objectname)|%(HEAD)|%(worktreepath)|%(symref)|%(upstream)'
+
+      # Delimiter used in format output
+      FIELD_DELIMITER = '|'
+
+      # Regex to parse successful deletion lines from stdout
+      # Matches: Deleted branch branchname (was abc123).
+      # Matches: Deleted remote-tracking branch origin/branchname (was abc123).
+      # Uses non-greedy match to capture branch names containing spaces
+      DELETED_BRANCH_REGEX = /^Deleted (?:remote-tracking )?branch (.+?) \(was/
+
+      # Regex to parse error messages from stderr
+      # Matches: error: branch 'branchname' not found.
+      ERROR_BRANCH_REGEX = /^error: branch '([^']+)'(.*)$/
+
+      module_function
+
+      # Parse git branch --list output into BranchInfo objects
+      #
+      # @example
+      #   Git::Parsers::Branch.parse_list("refs/heads/main|abc1234|*|||\nrefs/heads/feature|def5678||||\n")
+      #   # => [#<data Git::BranchInfo refname="main", ...>, #<data Git::BranchInfo refname="feature", ...>]
+      #
+      # @param stdout [String] output from git branch --list --format=...
+      #
+      # @return [Array<Git::BranchInfo>] parsed branch information
+      #
+      def parse_list(stdout)
+        stdout.split("\n").filter_map { |line| parse_branch_line(line) }
+      end
+
+      # Parse a single formatted branch line
+      #
+      # @param line [String] the line to parse (pipe-delimited fields)
+      # @return [Git::BranchInfo, nil] branch info object, or nil if line should be skipped
+      #
+      def parse_branch_line(line)
+        fields = line.split(FIELD_DELIMITER, 6)
+
+        return nil if non_branch_entry?(fields[0])
+
+        build_branch_info(fields)
+      end
+
+      # Build a BranchInfo from parsed fields
+      #
+      # @param fields [Array<String>] the parsed fields: [refname, objectname, head, worktreepath, symref, upstream]
+      # @return [Git::BranchInfo] the branch info object
+      #
+      def build_branch_info(fields)
+        raw_refname, objectname, head, worktreepath, symref, upstream = fields
+        current = head == '*'
+
+        Git::BranchInfo.new(
+          refname: normalize_refname(raw_refname),
+          target_oid: presence(objectname),
+          current: current,
+          worktree: in_other_worktree?(worktreepath, current),
+          symref: presence(symref),
+          upstream: build_upstream_info(upstream)
+        )
+      end
+
+      # Check if the refname represents a detached HEAD state or non-branch entry
+      #
+      # Git outputs special entries for detached HEAD and non-branch states:
+      # - "(HEAD detached at <ref>)" when in detached HEAD state
+      # - "(not a branch)" for non-branch entries
+      #
+      # @param refname [String] the refname to check
+      # @return [Boolean] true if this is a non-branch entry
+      #
+      def non_branch_entry?(refname)
+        refname.match?(/^\(HEAD detached/) || refname.match?(/^\(not a branch\)/)
+      end
+
+      # Normalize a full refname to the expected format
+      #
+      # Converts:
+      # - refs/heads/main -> main
+      # - refs/remotes/origin/main -> remotes/origin/main
+      #
+      # @param refname [String] the full refname from git
+      # @return [String] normalized refname
+      #
+      def normalize_refname(refname)
+        refname.sub(%r{^refs/heads/}, '').sub(%r{^refs/}, '')
+      end
+
+      # Check if the branch is checked out in another worktree
+      #
+      # worktree is true when the branch is checked out in ANOTHER worktree
+      # (worktreepath is non-empty AND it's not the current branch)
+      #
+      # @param worktreepath [String, nil] the worktree path from git output
+      # @param current [Boolean] whether this is the current branch
+      # @return [Boolean] true if checked out in another worktree
+      #
+      def in_other_worktree?(worktreepath, current)
+        has_worktree = !worktreepath.nil? && !worktreepath.empty?
+        has_worktree && !current
+      end
+
+      # Build upstream BranchInfo from upstream refname
+      #
+      # @param upstream_ref [String, nil] the upstream ref (e.g., 'refs/remotes/origin/main')
+      # @return [Git::BranchInfo, nil] upstream branch info or nil
+      #
+      def build_upstream_info(upstream_ref)
+        return nil if upstream_ref.nil? || upstream_ref.empty?
+
+        Git::BranchInfo.new(
+          refname: normalize_refname(upstream_ref),
+          target_oid: nil, # We don't have upstream's OID from this format
+          current: false,
+          worktree: false,
+          symref: nil,
+          upstream: nil # Upstream branches don't have their own upstream in this context
+        )
+      end
+
+      # Return value if non-empty, nil otherwise
+      #
+      # @param value [String, nil] the value to check
+      # @return [String, nil] the value or nil
+      #
+      def presence(value)
+        value.nil? || value.empty? ? nil : value
+      end
+
+      # Parse deleted branch names from stdout
+      #
+      # @example
+      #   BranchParser.parse_deleted_branches("Deleted branch feature (was abc123).\n")
+      #   # => ["feature"]
+      #
+      # @param stdout [String] command stdout
+      # @return [Array<String>] names of successfully deleted branches
+      #
+      def parse_deleted_branches(stdout)
+        stdout.scan(DELETED_BRANCH_REGEX).flatten
+      end
+
+      # Parse error messages from stderr into a map
+      #
+      # @example
+      #   BranchParser.parse_error_messages("error: branch 'missing' not found.\n")
+      #   # => {"missing" => "error: branch 'missing' not found."}
+      #
+      # @param stderr [String] command stderr
+      # @return [Hash<String, String>] map of branch name to error message
+      #
+      def parse_error_messages(stderr)
+        stderr.each_line.with_object({}) do |line, hash|
+          match = line.match(ERROR_BRANCH_REGEX)
+          hash[match[1]] = line.strip if match
+        end
+      end
+
+      # Build the BranchDeleteResult from parsed data
+      #
+      # @param requested_names [Array<String>] originally requested branch names
+      # @param existing_branches [Hash<String, Git::BranchInfo>] branches that existed before delete
+      # @param deleted_names [Array<String>] names confirmed deleted in stdout
+      # @param error_map [Hash<String, String>] map of branch name to error message
+      # @return [Git::BranchDeleteResult] the result object
+      #
+      def build_delete_result(requested_names, existing_branches, deleted_names, error_map)
+        deleted = deleted_names.filter_map { |name| existing_branches[name] }
+
+        not_deleted = (requested_names - deleted_names).map do |name|
+          error_message = error_map[name] || "branch '#{name}' could not be deleted"
+          Git::BranchDeleteFailure.new(name: name, error_message: error_message)
+        end
+
+        Git::BranchDeleteResult.new(deleted: deleted, not_deleted: not_deleted)
+      end
+    end
+  end
+end

data/lib/git/parsers/cat_file.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Git
+  module Parsers
+    # Parser for `git cat-file` commit and tag output
+    #
+    # Provides class methods that transform raw `git cat-file` output lines into
+    # structured Hash objects consumed by the `Git::Repository::ObjectOperations`
+    # facade.
+    #
+    # @api private
+    #
+    module CatFile
+      module_function
+
+      # Matches a single `git cat-file` header line
+      #
+      # @api private
+      #
+      CAT_FILE_HEADER_LINE = /\A(?<key>\w+) (?<value>.*)\z/
+
+      # Parse `git cat-file commit` output into a structured Hash
+      #
+      # @param lines [Array<String>] mutable cat-file output lines, consumed
+      #   in place during header parsing
+      #
+      # @param sha [String] the object name passed by the caller
+      #
+      # @return [Hash] commit data hash with string keys
+      #
+      # @api private
+      #
+      def parse_commit(lines, sha)
+        headers = parse_commit_headers(lines)
+        message = "#{lines.join("\n")}\n"
+        { 'sha' => sha, 'message' => message }.merge(headers)
+      end
+
+      # Parse `git cat-file tag` output into a structured Hash
+      #
+      # @param lines [Array<String>] mutable cat-file output lines, consumed
+      #   in place during header parsing; remaining lines become the message
+      #
+      # @param name [String] the tag name passed by the caller
+      #
+      # @return [Hash] tag data hash with string keys
+      #
+      # @api private
+      #
+      def parse_tag(lines, name)
+        hsh = { 'name' => name }
+        each_header(lines) { |key, value| hsh[key] = value }
+        hsh['message'] = "#{lines.join("\n")}\n"
+        hsh
+      end
+
+      # Extracts and returns commit headers from the front of `lines`
+      #
+      # Mutates `lines` in place, consuming header lines and the blank
+      # separator line. After the call `lines` contains only message lines.
+      #
+      # @param lines [Array<String>] mutable cat-file output lines
+      #
+      # @return [Hash] parsed header key/value pairs; `parent` is always
+      #   an Array
+      #
+      # @api private
+      #
+      def parse_commit_headers(lines)
+        headers = { 'parent' => [] }
+        each_header(lines) do |key, value|
+          if key == 'parent'
+            headers['parent'] << value
+          else
+            headers[key] = value
+          end
+        end
+        headers
+      end
+
+      # Yields parsed header key/value pairs from `git cat-file` output lines
+      #
+      # Consumes header lines from the front of `lines` until a blank line is
+      # encountered. Continuation lines that begin with a space are folded
+      # into the previous header value using newline separators.
+      #
+      # @param lines [Array<String>] mutable output lines from a cat-file response
+      #
+      # @yield [key, value] each parsed header pair
+      #
+      # @yieldparam key [String] header field name
+      #
+      # @yieldparam value [String] unfolded header value text
+      #
+      # @yieldreturn [void]
+      #
+      # @return [void]
+      #
+      # @api private
+      #
+      def each_header(lines)
+        while (line = lines.shift) && (match = CAT_FILE_HEADER_LINE.match(line))
+          key = match[:key]
+          value_lines = [match[:value]]
+          value_lines << lines.shift.lstrip while lines.first&.start_with?(' ')
+          yield key, value_lines.join("\n")
+        end
+      end
+    end
+  end
+end