git 3.1.1 → 4.0.1

data/lib/git/log.rb

@@ -1,31 +1,36 @@
 # frozen_string_literal: true
 
 module Git
-
-  # Return the last n commits that match the specified criteria
-  #
-  # @example The last (default number) of commits
-  #   git = Git.open('.')
-  #   Git::Log.new(git) #=> Enumerable of the last 30 commits
+  # Builds and executes a `git log` query.
   #
-  # @example The last n commits
-  #   Git::Log.new(git).max_commits(50) #=> Enumerable of last 50 commits
+  # This class provides a fluent interface for building complex `git log` queries.
+  # The query is lazily executed when results are requested either via the modern
+  # `#execute` method or the deprecated Enumerable methods.
   #
-  # @example All commits returned by `git log`
-  #   Git::Log.new(git).max_count(:all) #=> Enumerable of all commits
-  #
-  # @example All commits that match complex criteria
-  #   Git::Log.new(git)
-  #     .max_count(:all)
-  #     .object('README.md')
-  #     .since('10 years ago')
-  #     .between('v1.0.7', 'HEAD')
+  # @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
 
+    # An immutable, Enumerable collection of `Git::Object::Commit` objects.
+    # Returned by `Git::Log#execute`.
+    # @api public
+    Result = Data.define(:commits) do
+      include Enumerable
+
+      def each(&block) = commits.each(&block)
+      def last = commits.last
+      def [](index) = commits[index]
+      def to_s = map(&:to_s).join("\n")
+      def size = commits.size
+    end
+
     # Create a new Git::Log object
     #
     # @example
@@ -39,161 +44,100 @@ module Git
     #   Passing max_count to {#initialize} is equivalent to calling {#max_count} on the object.
     #
     def initialize(base, max_count = 30)
-      dirty_log
       @base = base
-      max_count(max_count)
+      @options = {}
+      @dirty = true
+      self.max_count(max_count)
     end
 
-    # The maximum number of commits to return
+    # Set query options using a fluent interface.
+    # Each method returns `self` to allow for chaining.
     #
-    # @example All commits returned by `git log`
-    #   git = Git.open('.')
-    #   Git::Log.new(git).max_count(:all)
+    def max_count(num)      = set_option(:count, num == :all ? nil : num)
+    def all                 = set_option(:all, true)
+    def object(objectish)   = set_option(:object, objectish)
+    def author(regex)       = set_option(:author, regex)
+    def grep(regex)         = set_option(:grep, regex)
+    def path(path)          = set_option(:path_limiter, path)
+    def skip(num)           = set_option(:skip, num)
+    def since(date)         = set_option(:since, date)
+    def until(date)         = set_option(:until, date)
+    def between(val1, val2 = nil) = set_option(:between, [val1, val2])
+    def cherry              = set_option(:cherry, true)
+    def merges              = set_option(:merges, true)
+
+    # Executes the git log command and returns an immutable result object
     #
-    # @param num_or_all [Integer, Symbol, nil] the number of commits to return, or
-    #   `:all` or `nil` to return all
-    #
-    # @return [self]
-    #
-    def max_count(num_or_all)
-      dirty_log
-      @max_count = (num_or_all == :all) ? nil : num_or_all
-      self
-    end
-
-    # Adds the --all flag to the git log command
+    # This is the preferred way to get log data. It separates the query
+    # building from the execution, making the API more predictable.
     #
-    # This asks for the logs of all refs (basically all commits reachable by HEAD,
-    # branches, and tags). This does not control the maximum number of commits
-    # returned. To control how many commits are returned, call {#max_count}.
-    #
-    # @example Return the last 50 commits reachable by all refs
-    #   git = Git.open('.')
-    #   Git::Log.new(git).max_count(50).all
+    # @example
+    #   query = g.log.since('2 weeks ago').author('Scott')
+    #   results = query.execute
+    #   puts "Found #{results.size} commits"
+    #   results.each do |commit|
+    #     # ...
+    #   end
     #
-    # @return [self]
+    # @return [Git::Log::Result] an object containing the log results
     #
-    def all
-      dirty_log
-      @all = true
-      self
-    end
-
-    def object(objectish)
-      dirty_log
-      @object = objectish
-      return self
-    end
-
-    def author(regex)
-      dirty_log
-      @author = regex
-      return self
-    end
-
-    def grep(regex)
-      dirty_log
-      @grep = regex
-      return self
-    end
-
-    def path(path)
-      dirty_log
-      @path = path
-      return self
+    def execute
+      run_log_if_dirty
+      Result.new(@commits)
     end
 
-    def skip(num)
-      dirty_log
-      @skip = num
-      return self
-    end
+    # @!group Deprecated Enumerable Interface
 
-    def since(date)
-      dirty_log
-      @since = date
-      return self
+    # @deprecated Use {#execute} and call `each` on the result.
+    def each(&)
+      deprecate_and_run
+      @commits.each(&)
     end
 
-    def until(date)
-      dirty_log
-      @until = date
-      return self
+    # @deprecated Use {#execute} and call `size` on the result.
+    def size
+      deprecate_and_run
+      @commits&.size
     end
 
-    def between(sha1, sha2 = nil)
-      dirty_log
-      @between = [sha1, sha2]
-      return self
+    # @deprecated Use {#execute} and call `to_s` on the result.
+    def to_s
+      deprecate_and_run
+      @commits&.map(&:to_s)&.join("\n")
     end
 
-    def cherry
-      dirty_log
-      @cherry = true
-      return self
+    # @deprecated Use {#execute} and call the method on the result.
+    %i[first last []].each do |method_name|
+      define_method(method_name) do |*args|
+        deprecate_and_run
+        @commits&.public_send(method_name, *args)
+      end
     end
 
-    def merges
-      dirty_log
-      @merges = true
-      return self
-    end
+    # @!endgroup
 
-    def to_s
-      self.map { |c| c.to_s }.join("\n")
-    end
-
-    # forces git log to run
+    private
 
-    def size
-      check_log
-      @commits.size rescue nil
+    def set_option(key, value)
+      @dirty = true
+      @options[key] = value
+      self
     end
 
-    def each(&block)
-      check_log
-      @commits.each(&block)
-    end
+    def run_log_if_dirty
+      return unless @dirty
 
-    def first
-      check_log
-      @commits.first rescue nil
+      log_data = @base.lib.full_log_commits(@options)
+      @commits = log_data.map { |c| Git::Object::Commit.new(@base, c['sha'], c) }
+      @dirty = false
     end
 
-    def last
-      check_log
-      @commits.last rescue nil
+    def deprecate_and_run(method = caller_locations(1, 1)[0].label)
+      Git::Deprecation.warn(
+        "Calling Git::Log##{method} is deprecated. " \
+        "Call #execute and then ##{method} on the result object."
+      )
+      run_log_if_dirty
     end
-
-    def [](index)
-      check_log
-      @commits[index] rescue nil
-    end
-
-
-    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: @max_count, all: @all, object: @object, path_limiter: @path, since: @since,
-          author: @author, grep: @grep, skip: @skip, until: @until, between: @between,
-          cherry: @cherry, merges: @merges
-        )
-        @commits = log.map { |c| Git::Object::Commit.new(@base, c['sha'], c) }
-      end
-
   end
-
 end

data/lib/git/object.rb

@@ -6,10 +6,9 @@ require 'git/errors'
 require 'git/log'
 
 module Git
-
   # represents a git object
   class Object
-
+    # A base class for all Git objects
     class AbstractObject
       attr_accessor :objectish, :type, :mode
 
@@ -38,16 +37,16 @@ module Git
       # read a large file in chunks.
       #
       # Use this for large files so that they are not held in memory.
-      def contents(&block)
+      def contents(&)
         if block_given?
-          @base.lib.cat_file_contents(@objectish, &block)
+          @base.lib.cat_file_contents(@objectish, &)
         else
           @contents ||= @base.lib.cat_file_contents(@objectish)
         end
       end
 
       def contents_array
-        self.contents.split("\n")
+        contents.split("\n")
       end
 
       def to_s
@@ -55,7 +54,7 @@ module Git
       end
 
       def grep(string, path_limiter = nil, opts = {})
-        opts = {:object => sha, :path_limiter => path_limiter}.merge(opts)
+        opts = { object: sha, path_limiter: path_limiter }.merge(opts)
         @base.lib.grep(string, opts)
       end
 
@@ -72,19 +71,17 @@ module Git
         @base.lib.archive(@objectish, file, opts)
       end
 
-      def tree?; false; end
+      def tree? = false
 
-      def blob?; false; end
+      def blob? = false
 
-      def commit?; false; end
-
-      def tag?; false; end
+      def commit? = false
 
+      def tag? = false
     end
 
-
+    # A Git blob object
     class Blob < AbstractObject
-
       def initialize(base, sha, mode = nil)
         super(base, sha)
         @mode = mode
@@ -93,11 +90,10 @@ module Git
       def blob?
         true
       end
-
     end
 
+    # A Git tree object
     class Tree < AbstractObject
-
       def initialize(base, sha, mode = nil)
         super(base, sha)
         @mode = mode
@@ -112,13 +108,13 @@ module Git
       def blobs
         @blobs ||= check_tree[:blobs]
       end
-      alias_method :files, :blobs
+      alias files blobs
 
       def trees
         @trees ||= check_tree[:trees]
       end
-      alias_method :subtrees, :trees
-      alias_method :subdirectories, :trees
+      alias subtrees trees
+      alias subdirectories trees
 
       def full_tree
         @base.lib.full_tree(@objectish)
@@ -134,31 +130,27 @@ module Git
 
       private
 
-        # actually run the git command
-        def check_tree
-          @trees = {}
-          @blobs = {}
-
-          data = @base.lib.ls_tree(@objectish)
+      # actually run the git command
+      def check_tree
+        @trees = {}
+        @blobs = {}
 
-          data['tree'].each do |key, tree|
-            @trees[key] = Git::Object::Tree.new(@base, tree[:sha], tree[:mode])
-          end
+        data = @base.lib.ls_tree(@objectish)
 
-          data['blob'].each do |key, blob|
-            @blobs[key] = Git::Object::Blob.new(@base, blob[:sha], blob[:mode])
-          end
+        data['tree'].each do |key, tree|
+          @trees[key] = Git::Object::Tree.new(@base, tree[:sha], tree[:mode])
+        end
 
-          {
-            :trees => @trees,
-            :blobs => @blobs
-          }
+        data['blob'].each do |key, blob|
+          @blobs[key] = Git::Object::Blob.new(@base, blob[:sha], blob[:mode])
         end
 
+        { trees: @trees, blobs: @blobs }
+      end
     end
 
+    # A Git commit object
     class Commit < AbstractObject
-
       def initialize(base, sha, init = nil)
         super(base, sha)
         @tree = nil
@@ -166,9 +158,9 @@ module Git
         @author = nil
         @committer = nil
         @message = nil
-        if init
-          set_commit(init)
-        end
+        return unless init
+
+        from_data(init)
       end
 
       def message
@@ -214,18 +206,23 @@ module Git
       def committer_date
         committer.date
       end
-      alias_method :date, :committer_date
+      alias date committer_date
 
       def diff_parent
         diff(parent)
       end
 
-      def set_commit(data)
+      def set_commit(data) # rubocop:disable Naming/AccessorMethodName
+        Git.deprecation('Git::Object::Commit#set_commit is deprecated. Use #from_data instead.')
+        from_data(data)
+      end
+
+      def from_data(data)
         @sha ||= data['sha']
         @committer = Git::Author.new(data['committer'])
         @author = Git::Author.new(data['author'])
         @tree = Git::Object::Tree.new(@base, data['tree'])
-        @parents = data['parent'].map{ |sha| Git::Object::Commit.new(@base, sha) }
+        @parents = data['parent'].map { |sha| Git::Object::Commit.new(@base, sha) }
         @message = data['message'].chomp
       end
 
@@ -235,33 +232,57 @@ module Git
 
       private
 
-        # see if this object has been initialized and do so if not
-        def check_commit
-          return if @tree
-
-          data = @base.lib.cat_file_commit(@objectish)
-          set_commit(data)
-        end
+      # see if this object has been initialized and do so if not
+      def check_commit
+        return if @tree
 
+        data = @base.lib.cat_file_commit(@objectish)
+        from_data(data)
+      end
     end
 
+    # A Git tag object
+    #
+    # This class represents a tag in Git, which can be either annotated or lightweight.
+    #
+    # Annotated tags contain additional metadata such as the tagger's name, email, and
+    # the date when the tag was created, along with a message.
+    #
+    # TODO: Annotated tags are not objects
+    #
     class Tag < AbstractObject
       attr_accessor :name
 
-      def initialize(base, sha, name)
+      # @overload initialize(base, name)
+      #   @param base [Git::Base] The Git base object
+      #   @param name [String] The name of the tag
+      #
+      # @overload initialize(base, sha, name)
+      #   @param base [Git::Base] The Git base object
+      #   @param sha [String] The SHA of the tag object
+      #   @param name [String] The name of the tag
+      #
+      def initialize(base, sha, name = nil)
+        if name.nil?
+          name = sha
+          sha = base.lib.tag_sha(name)
+          raise Git::UnexpectedResultError, "Tag '#{name}' does not exist." if sha == ''
+        end
+
         super(base, sha)
+
         @name = name
         @annotated = nil
         @loaded = false
       end
 
       def annotated?
-        @annotated ||= (@base.lib.cat_file_type(self.name) == 'tag')
+        @annotated = @annotated.nil? ? (@base.lib.cat_file_type(name) == 'tag') : @annotated
       end
 
       def message
-        check_tag()
-        return @message
+        check_tag
+        @message
       end
 
       def tag?
@@ -269,8 +290,8 @@ module Git
       end
 
       def tagger
-        check_tag()
-        return @tagger
+        check_tag
+        @tagger
       end
 
       private
@@ -278,31 +299,25 @@ module Git
       def check_tag
         return if @loaded
 
-        if !self.annotated?
-          @message = @tagger = nil
-        else
+        if annotated?
           tdata = @base.lib.cat_file_tag(@name)
           @message = tdata['message'].chomp
           @tagger = Git::Author.new(tdata['tagger'])
+        else
+          @message = @tagger = nil
         end
 
         @loaded = true
       end
-
     end
 
     # if we're calling this, we don't know what type it is yet
     # so this is our little factory method
-    def self.new(base, objectish, type = nil, is_tag = false)
-      if is_tag
-        sha = base.lib.tag_sha(objectish)
-        if sha == ''
-          raise Git::UnexpectedResultError.new("Tag '#{objectish}' does not exist.")
-        end
-        return Git::Object::Tag.new(base, sha, objectish)
-      end
+    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)
+      # TODO: why not handle tag case here too?
       klass =
         case type
         when /blob/   then Blob
@@ -312,5 +327,9 @@ module Git
       klass.new(base, objectish)
     end
 
+    private_class_method def self.new_tag(base, objectish)
+      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
   end
 end

data/lib/git/path.rb

@@ -1,17 +1,28 @@
 # frozen_string_literal: true
 
 module Git
+  # A base class that represents and validates a filesystem path
+  #
+  # Use for tracking things relevant to a Git repository, such as the working
+  # directory or index file.
+  #
+  class Path
+    attr_accessor :path
 
- class Path
+    def initialize(path, check_path = nil, must_exist: nil)
+      unless check_path.nil?
+        Git::Deprecation.warn(
+          'The "check_path" argument is deprecated and ' \
+          'will be removed in a future version. Use "must_exist:" instead.'
+        )
+      end
 
-    attr_accessor :path
+      # default is true
+      must_exist = must_exist.nil? && check_path.nil? ? true : must_exist || check_path
 
-    def initialize(path, check_path=true)
       path = File.expand_path(path)
 
-      if check_path && !File.exist?(path)
-        raise ArgumentError, 'path does not exist', [path]
-      end
+      raise ArgumentError, 'path does not exist', [path] if must_exist && !File.exist?(path)
 
       @path = path
     end
@@ -27,6 +38,5 @@ module Git
     def to_s
       @path
     end
- end
-
+  end
 end

data/lib/git/remote.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Git
-  class Remote < Path
-
+  # A remote in a Git repository
+  class Remote
     attr_accessor :name, :url, :fetch_opts
 
     def initialize(base, name)
@@ -13,7 +13,7 @@ module Git
       @fetch_opts = config['fetch']
     end
 
-    def fetch(opts={})
+    def fetch(opts = {})
       @base.fetch(@name, opts)
     end
 
@@ -35,6 +35,5 @@ module Git
     def to_s
       @name
     end
-
   end
 end

data/lib/git/repository.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module Git
-
   class Repository < Path
   end
-
 end