git 1.19.1 → 5.5.0

data/lib/git/file_ref.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object representing a reference to a file at a specific point in time
+  #
+  # FileRef encapsulates the mode, SHA, and path of a file as it exists on one side
+  # of a diff. This is used to represent either the source (before) or destination
+  # (after) state of a file in a diff operation.
+  #
+  # When a file doesn't exist on a side of the diff (e.g., src for new files,
+  # dst for deleted files), the entire FileRef should be nil rather than having
+  # a FileRef with nil attributes.
+  #
+  #
+  # @example A modified file's source reference
+  #   src = Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/foo.rb')
+  #
+  # @example A new file (src would be nil, not a FileRef)
+  #   # src = nil
+  #   dst = Git::FileRef.new(mode: '100644', sha: 'def5678', path: 'lib/new_file.rb')
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  #
+  # @!attribute [r] mode
+  #   @return [String] the file mode (e.g., '100644' for regular file, '100755' for executable,
+  #     '120000' for symlink)
+  #
+  # @!attribute [r] sha
+  #   @return [String] the blob SHA (object identifier)
+  #
+  # @!attribute [r] path
+  #   @return [String] the file path relative to repository root
+  #
+  FileRef = Data.define(:mode, :sha, :path) do
+    # Check if this is a regular file (not executable, symlink, etc.)
+    #
+    # @return [Boolean] true if mode is 100644
+    #
+    def regular_file?
+      mode == '100644'
+    end
+
+    # Check if this is an executable file
+    #
+    # @return [Boolean] true if mode is 100755
+    #
+    def executable?
+      mode == '100755'
+    end
+
+    # Check if this is a symbolic link
+    #
+    # @return [Boolean] true if mode is 120000
+    #
+    def symlink?
+      mode == '120000'
+    end
+
+    # Return the mode as an integer (parsed as octal)
+    #
+    # Useful for bit operations on file permissions.
+    #
+    # @example Check file permissions
+    #   ref.mode_bits & 0o777  # => 0o644 (420 decimal)
+    #
+    # @example Check if group writable
+    #   (ref.mode_bits & 0o020) != 0
+    #
+    # @return [Integer] the mode as an integer
+    #
+    def mode_bits
+      mode.to_i(8)
+    end
+  end
+end

data/lib/git/fsck_object.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents an object returned by `git fsck`
+  #
+  # This class provides information about dangling, missing, unreachable, or
+  # problematic Git objects found during repository integrity checks.
+  #
+  # @api public
+  #
+  class FsckObject
+    # The type of the Git object
+    #
+    # @return [Symbol] one of :commit, :tree, :blob, or :tag
+    attr_reader :type
+
+    # The object identifier (OID) of the object
+    #
+    # @return [String] the 40-character object identifier
+    attr_reader :oid
+
+    # A warning or error message associated with this object
+    #
+    # @return [String, nil] the message, or nil if no message
+    attr_reader :message
+
+    # A name describing how the object is reachable (from --name-objects)
+    #
+    # @return [String, nil] the name, or nil if not provided
+    attr_reader :name
+
+    # Create a new FsckObject
+    #
+    # @param type [Symbol] the object type (:commit, :tree, :blob, or :tag)
+    #
+    # @param oid [String] the 40-character object identifier
+    #
+    # @param message [String, nil] optional warning/error message
+    #
+    # @param name [String, nil] optional name from --name-objects (e.g., "HEAD~2^2:src/")
+    #
+    def initialize(type:, oid:, message: nil, name: nil)
+      @type = type
+      @oid = oid
+      @message = message
+      @name = name
+    end
+
+    # Returns the OID as the string representation
+    #
+    # @return [String] the object identifier
+    def to_s
+      oid
+    end
+  end
+end

data/lib/git/fsck_result.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents the result of running `git fsck`
+  #
+  # This class provides structured access to the objects found during a
+  # repository integrity check, categorized by their status.
+  #
+  # @api public
+  #
+  class FsckResult
+    # Objects not referenced by any other object
+    #
+    # @return [Array<Git::FsckObject>]
+    attr_reader :dangling
+
+    # Objects that are referenced but not present in the repository
+    #
+    # @return [Array<Git::FsckObject>]
+    attr_reader :missing
+
+    # Objects not reachable from any ref
+    #
+    # @return [Array<Git::FsckObject>]
+    attr_reader :unreachable
+
+    # Objects with warnings (each includes a message)
+    #
+    # @return [Array<Git::FsckObject>]
+    attr_reader :warnings
+
+    # Root nodes (commits with no parents) when --root is used
+    #
+    # @return [Array<Git::FsckObject>]
+    attr_reader :root
+
+    # Tagged objects when --tags is used
+    #
+    # @return [Array<Git::FsckObject>]
+    attr_reader :tagged
+
+    # rubocop:disable Metrics/ParameterLists
+
+    # Create a new FsckResult
+    #
+    # @param dangling [Array<Git::FsckObject>] dangling objects
+    #
+    # @param missing [Array<Git::FsckObject>] missing objects
+    #
+    # @param unreachable [Array<Git::FsckObject>] unreachable objects
+    #
+    # @param warnings [Array<Git::FsckObject>] objects with warnings
+    #
+    # @param root [Array<Git::FsckObject>] root nodes
+    #
+    # @param tagged [Array<Git::FsckObject>] tagged objects
+    #
+    def initialize(dangling: [], missing: [], unreachable: [], warnings: [], root: [], tagged: [])
+      @dangling = dangling
+      @missing = missing
+      @unreachable = unreachable
+      @warnings = warnings
+      @root = root
+      @tagged = tagged
+    end
+
+    # rubocop:enable Metrics/ParameterLists
+
+    # Returns true if any issues were found
+    #
+    # @example Check for repository issues
+    #   result = git.fsck
+    #   puts "Repository has issues!" if result.any_issues?
+    #
+    # @return [Boolean]
+    #
+    def any_issues?
+      [dangling, missing, unreachable, warnings].any?(&:any?)
+    end
+
+    # Returns true if no issues were found
+    #
+    # @example Check if the result is empty
+    #   result = git.fsck
+    #   puts "Repository is clean" if result.empty?
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      !any_issues?
+    end
+
+    # Returns all objects from all categories (excluding informational root/tagged)
+    #
+    # @example Iterate over all objects
+    #   result = git.fsck
+    #   result.all_objects.each { |obj| puts obj.oid }
+    #
+    # @return [Array<Git::FsckObject>]
+    #
+    def all_objects
+      dangling + missing + unreachable + warnings
+    end
+
+    # Returns the total number of issues found
+    #
+    # @example Count all issues
+    #   result = git.fsck
+    #   puts "Found #{result.count} issues"
+    #
+    # @return [Integer]
+    #
+    def count
+      all_objects.size
+    end
+
+    # Returns a hash representation of the result
+    #
+    # @example Convert to a hash
+    #   result = git.fsck
+    #   result.to_h # => { dangling: [...], missing: [...], ... }
+    #
+    # @return [Hash{Symbol => Array<Git::FsckObject>}]
+    #
+    def to_h
+      {
+        dangling: dangling, missing: missing, unreachable: unreachable,
+        warnings: warnings, root: root, tagged: tagged
+      }
+    end
+  end
+end

data/lib/git/log.rb

@@ -1,131 +1,347 @@
-module Git
+# frozen_string_literal: true
 
-  # object that holds the last X commits on given branch
+module Git
+  # Builds and executes a `git log` query
+  #
+  # This class provides a fluent interface for building complex `git log` queries.
+  #
+  # Queries default to returning 30 commits; call {#max_count} with `:all` to
+  # return every matching commit. Calling {#all} adds the `--all` flag to include
+  # all refs in the search but does not change the number of commits returned.
+  #
+  # The query is lazily executed when results are requested either via the modern
+  # `#execute` method or the deprecated Enumerable methods.
+  #
+  # @example Using the modern `execute` API
+  #   log = git.log.max_count(50).between('v1.0', 'v1.1').author('Scott')
+  #   results = log.execute
+  #   puts "Found #{results.size} commits."
+  #   results.each { |commit| puts commit.sha }
+  #
+  # @api public
+  #
   class Log
     include Enumerable
 
-    def initialize(base, count = 30)
-      dirty_log
-      @base = base
-      @count = count
-    end
+    # An immutable, Enumerable collection of `Git::Object::Commit` objects.
+    # Returned by `Git::Log#execute`.
+    #
+    # @api public
+    Result = Data.define(:commits) do
+      include Enumerable
 
-    def all
-      dirty_log
-      @all = true
-      self
-    end
+      # Iterates over each commit in query order
+      #
+      # @overload each
+      #   @example Get an enumerator
+      #     results.each.map(&:sha)
+      #
+      #   @return [Enumerator<Git::Object::Commit>] an enumerator over commits
+      #
+      # @overload each(&block)
+      #   @example Iterate with a block
+      #     results.each { |commit| puts commit.sha }
+      #
+      #   @yield [commit] each commit from the result
+      #
+      #   @yieldparam commit [Git::Object::Commit] a commit in query order
+      #
+      #   @yieldreturn [void]
+      #
+      #   @return [Array<Git::Object::Commit>] the commit array
+      #
+      def each(&block) = commits.each(&block)
 
-    def object(objectish)
-      dirty_log
-      @object = objectish
-      return self
-    end
+      # Returns the last commit in the result
+      #
+      # @return [Git::Object::Commit, nil] the last commit, or `nil` when empty
+      #
+      def last = commits.last
 
-    def author(regex)
-      dirty_log
-      @author = regex
-      return self
-    end
+      # Returns a commit by index or a slice of commits by range
+      #
+      # @param index [Integer, Range] the commit index or range to retrieve
+      #
+      # @return [Git::Object::Commit, Array<Git::Object::Commit>, nil] the selected
+      #   commit or commits
+      #
+      def [](index) = commits[index]
 
-    def grep(regex)
-      dirty_log
-      @grep = regex
-      return self
-    end
+      # Returns the commits joined with newlines
+      #
+      # @return [String] newline-separated commits
+      #
+      def to_s = commits.join("\n")
 
-    def path(path)
-      dirty_log
-      @path = path
-      return self
+      # Returns the number of commits in the result
+      #
+      # @return [Integer] the commit count
+      #
+      def size = commits.size
     end
 
-    def skip(num)
-      dirty_log
-      @skip = num
-      return self
+    # Create a new Git::Log object
+    #
+    # @example
+    #   git = Git.open('.')
+    #   Git::Log.new(git)
+    #
+    # @param base [Git::Repository] the git repository object
+    #
+    # @param max_count [Integer, Symbol, nil] the number of commits to return, or
+    #   `:all` or `nil` to return all
+    #
+    #   Passing max_count to {#initialize} is equivalent to calling {#max_count} on the object.
+    #
+    def initialize(base, max_count = 30)
+      @base = base
+      @options = {}
+      @dirty = true
+      self.max_count(max_count)
     end
 
-    def since(date)
-      dirty_log
-      @since = date
-      return self
-    end
+    # Set query options using a fluent interface.
+    # Each method returns `self` to allow for chaining.
+    #
+    # Sets the maximum number of commits to return
+    #
+    # @param num [Integer, Symbol, nil] the maximum commit count, or `:all` / `nil`
+    #   for no limit
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def max_count(num)      = set_option(:count, num == :all ? nil : num)
 
-    def until(date)
-      dirty_log
-      @until = date
-      return self
-    end
+    # Includes commits reachable from all refs
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def all                 = set_option(:all, true)
 
-    def between(sha1, sha2 = nil)
-      dirty_log
-      @between = [sha1, sha2]
-      return self
-    end
+    # Sets the revision range expression for the log query
+    #
+    # @param objectish [String] a git revision expression to pass to `git log`
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def object(objectish)   = set_option(:object, objectish)
 
-    def cherry
-      dirty_log
-      @cherry = true
-      return self
-    end
+    # Filters commits by author pattern
+    #
+    # @param regex [String] a pattern matched against author names
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def author(regex)       = set_option(:author, regex)
 
-    def to_s
-      self.map { |c| c.to_s }.join("\n")
+    # Filters commits by commit message pattern
+    #
+    # @param regex [String] a pattern matched against commit messages
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def grep(regex)         = set_option(:grep, regex)
+
+    # Interprets {#grep} and {#author} patterns as Perl-compatible regular expressions
+    #
+    # Selects PCRE instead of git's default POSIX basic regular expressions for
+    # every pattern in the query. Requires a git built with PCRE support.
+    #
+    # @example Match a metacharacter against a non-ASCII character on Git for Windows
+    #   repo.log.perl_regexp.grep('^.PFEL').execute
+    #
+    # @return [Git::Log] the current query builder
+    #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather
+    #   than characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` never matches a whole multi-byte character. The match fails
+    #   silently: git exits zero and the result is empty. PCRE does match characters
+    #   on that platform, but it is a different dialect than git's default, so
+    #   selecting it is a deliberate choice by the caller.
+    #
+    def perl_regexp         = set_option(:perl_regexp, true)
+
+    # Limits commits to those that touch the given path or paths
+    #
+    # @param path [String, Pathname, Array<String, Pathname>] path limiter input
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def path(path)          = set_option(:path_limiter, path)
+
+    # Skips a number of commits before returning results
+    #
+    # @param num [Integer] the number of commits to skip
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def skip(num)           = set_option(:skip, num)
+
+    # Includes only commits newer than the given date expression
+    #
+    # @param date [String] a git-compatible date expression
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def since(date)         = set_option(:since, date)
+
+    # Includes only commits older than the given date expression
+    #
+    # @param date [String] a git-compatible date expression
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def until(date)         = set_option(:until, date)
+
+    # Limits commits to the given revision range
+    #
+    # @param val1 [String] the first revision
+    #
+    # @param val2 [String, nil] the second revision; when `nil`, validation fails
+    #   at execution time
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def between(val1, val2 = nil) = set_option(:between, [val1, val2])
+
+    # Omits commits equivalent to cherry-picked commits
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def cherry              = set_option(:cherry, true)
+
+    # Includes only merge commits
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def merges              = set_option(:merges, true)
+
+    # Executes the git log command and returns an immutable result object
+    #
+    # This is the preferred way to get log data. It separates the query
+    # building from the execution, making the API more predictable.
+    #
+    # @example
+    #   query = g.log.since('2 weeks ago').author('Scott')
+    #   results = query.execute
+    #   puts "Found #{results.size} commits"
+    #   results.each do |commit|
+    #     # ...
+    #   end
+    #
+    # @return [Git::Log::Result] an object containing the log results
+    #
+    def execute
+      run_log_if_dirty
+      Result.new(@commits)
     end
 
+    # @!group Deprecated Enumerable Interface
 
-    # forces git log to run
+    # @deprecated Use {#execute} and call `each` on the result.
+    def each(&)
+      Git::Deprecation.warn(
+        'Calling Git::Log#each is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #each on the result object.'
+      )
+      run_log_if_dirty
+      @commits.each(&)
+    end
 
+    # @deprecated Use {#execute} and call `size` on the result.
     def size
-      check_log
-      @commits.size rescue nil
+      Git::Deprecation.warn(
+        'Calling Git::Log#size is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #size on the result object.'
+      )
+      run_log_if_dirty
+      @commits.size
     end
 
-    def each(&block)
-      check_log
-      @commits.each(&block)
+    # @deprecated Use {#execute} and call `to_s` on the result.
+    def to_s
+      Git::Deprecation.warn(
+        'Calling Git::Log#to_s is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #to_s on the result object.'
+      )
+      run_log_if_dirty
+      @commits.join("\n")
     end
 
+    # @deprecated Use {#execute} and call the method on the result.
     def first
-      check_log
-      @commits.first rescue nil
+      Git::Deprecation.warn(
+        'Calling Git::Log#first is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #first on the result object.'
+      )
+      run_log_if_dirty
+      @commits.first
     end
 
+    # @deprecated Use {#execute} and call the method on the result.
     def last
-      check_log
-      @commits.last rescue nil
+      Git::Deprecation.warn(
+        'Calling Git::Log#last is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #last on the result object.'
+      )
+      run_log_if_dirty
+      @commits.last
     end
 
+    # @param index [Integer, Range] the commit index or range to retrieve
+    #
+    # @return [Git::Object::Commit, Array<Git::Object::Commit>, nil] the selected
+    #   commit or commits
+    #
+    # @deprecated Use {#execute} and call the method on the result.
+    #
     def [](index)
-      check_log
-      @commits[index] rescue nil
+      Git::Deprecation.warn(
+        'Calling Git::Log#[] is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #[] on the result object.'
+      )
+      run_log_if_dirty
+      @commits[index]
     end
 
+    # @!endgroup
 
     private
 
-      def dirty_log
-        @dirty_flag = true
-      end
-
-      def check_log
-        if @dirty_flag
-          run_log
-          @dirty_flag = false
-        end
-      end
-
-      # actually run the 'git log' command
-      def run_log
-        log = @base.lib.full_log_commits(
-          count: @count, all: @all, object: @object, path_limiter: @path, since: @since,
-          author: @author, grep: @grep, skip: @skip, until: @until, between: @between,
-          cherry: @cherry
-        )
-        @commits = log.map { |c| Git::Object::Commit.new(@base, c['sha'], c) }
-      end
+    # Sets a log query option and marks cached results dirty
+    #
+    # @param key [Symbol] the option key
+    #
+    # @param value [Object] the option value
+    #
+    # @return [Git::Log] the current query builder
+    #
+    def set_option(key, value)
+      @dirty = true
+      @options[key] = value
+      self
+    end
 
-  end
+    # @return [Git::Repository]
+    #
+    def log_repository
+      @base
+    end
+
+    # Refreshes cached commits when query options have changed
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] if configured query options are invalid
+    #
+    # @raise [Git::FailedError] if the underlying `git log` command fails
+    #
+    def run_log_if_dirty
+      return unless @dirty
 
+      log_data = log_repository.full_log_commits(@options)
+      @commits = log_data.map { |c| Git::Object::Commit.new(@base, c['sha'], c) }
+      @dirty = false
+    end
+  end
 end