git 5.0.0.beta.2 → 5.0.0.beta.4

data/lib/git/fsck_result.rb

@@ -10,26 +10,32 @@ module Git
   #
   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
 
@@ -38,10 +44,15 @@ module Git
     # 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: [])
@@ -57,60 +68,60 @@ module Git
 
     # Returns true if any issues were found
     #
-    # @return [Boolean]
-    #
-    # @example
+    # @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
     #
-    # @return [Boolean]
-    #
-    # @example
+    # @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)
     #
-    # @return [Array<Git::FsckObject>]
-    #
-    # @example
+    # @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
     #
-    # @return [Integer]
-    #
-    # @example
+    # @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
     #
-    # @return [Hash{Symbol => Array<Git::FsckObject>}]
-    #
-    # @example
+    # @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,

data/lib/git/log.rb

@@ -25,14 +25,58 @@ module Git
 
     # An immutable, Enumerable collection of `Git::Object::Commit` objects.
     # Returned by `Git::Log#execute`.
+    #
     # @api public
     Result = Data.define(:commits) do
       include Enumerable
 
+      # 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)
+
+      # Returns the last commit in the result
+      #
+      # @return [Git::Object::Commit, nil] the last commit, or `nil` when empty
+      #
       def last = commits.last
+
+      # 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]
+
+      # Returns the commits joined with newlines
+      #
+      # @return [String] newline-separated commits
+      #
       def to_s = commits.join("\n")
+
+      # Returns the number of commits in the result
+      #
+      # @return [Integer] the commit count
+      #
       def size = commits.size
     end
 
@@ -59,17 +103,98 @@ module Git
     # 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)
+
+    # Includes commits reachable from all refs
+    #
+    # @return [Git::Log] the current query builder
+    #
     def all                 = set_option(:all, true)
+
+    # 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)
+
+    # 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)
+
+    # 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)
+
+    # 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
@@ -109,7 +234,7 @@ module Git
         'Calling Git::Log#size is deprecated. Call #execute and then #size on the result object.'
       )
       run_log_if_dirty
-      @commits&.size
+      @commits.size
     end
 
     # @deprecated Use {#execute} and call `to_s` on the result.
@@ -118,7 +243,7 @@ module Git
         'Calling Git::Log#to_s is deprecated. Call #execute and then #to_s on the result object.'
       )
       run_log_if_dirty
-      @commits&.join("\n")
+      @commits.join("\n")
     end
 
     # @deprecated Use {#execute} and call the method on the result.
@@ -127,7 +252,7 @@ module Git
         'Calling Git::Log#first is deprecated. Call #execute and then #first on the result object.'
       )
       run_log_if_dirty
-      @commits&.first
+      @commits.first
     end
 
     # @deprecated Use {#execute} and call the method on the result.
@@ -136,22 +261,36 @@ module Git
         'Calling Git::Log#last is deprecated. Call #execute and then #last on the result object.'
       )
       run_log_if_dirty
-      @commits&.last
+      @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)
       Git::Deprecation.warn(
         'Calling Git::Log#[] is deprecated. Call #execute and then #[] on the result object.'
       )
       run_log_if_dirty
-      @commits&.[](index)
+      @commits[index]
     end
 
     # @!endgroup
 
     private
 
+    # 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
@@ -164,6 +303,14 @@ module Git
       @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