Add Git::Log#max_count

jcouball · jcouball · commit 93c8210f3228 · 2024-05-31T09:46:45.000-07:00
diff --git a/README.md b/README.md
@@ -101,16 +101,28 @@ directory, in the index and in the repository.  Similar to running 'git status'
 
 **Git::Remote**- A reference to a remote repository that is tracked by this repository.
 
-**Git::Log** - An Enumerable object that references all the `Git::Object::Commit` objects that encompass your log query, which can be constructed through methods on the `Git::Log object`,
-like:
+**Git::Log** - An Enumerable object that references all the `Git::Object::Commit`
+objects that encompass your log query, which can be constructed through methods on
+the `Git::Log object`, like:
 
- `@git.log(20).object("some_file").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] }`
+```ruby
+git.log
+  .max_count(:all)
+  .object('README.md')
+  .since('10 years ago')
+  .between('v1.0.7', 'HEAD')
+  .map { |commit| commit.sha }
+```
 
-Pass the `--all` option to `git log` as follows:
+A maximum of 30 commits are returned if `max_count` is not called. To get all commits
+that match the log query, call `max_count(:all)`.
 
- `@git.log.all.each { |commit| [block] }`
+Note that `git.log.all` adds the `--all` option to the underlying `git log` command.
+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, you should call `max_count`.
 
- **Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
+**Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
 
 ## Errors Raised By This Gem
 
diff --git a/lib/git/log.rb b/lib/git/log.rb
@@ -1,15 +1,76 @@
 module Git
 
-  # object that holds the last X commits on given branch
+  # 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
+  #
+  # @example The last n commits
+  #   Git::Log.new(git).max_commits(50) #=> Enumerable of last 50 commits
+  #
+  # @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')
+  #
+  # @api public
+  #
   class Log
     include Enumerable
 
-    def initialize(base, count = 30)
+    # Create a new Git::Log object
+    #
+    # @example
+    #   git = Git.open('.')
+    #   Git::Log.new(git)
+    #
+    # @param base [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
+    #
+    #   Passing max_count to {#initialize} is equivalent to calling {#max_count} on the object.
+    #
+    def initialize(base, max_count = 30)
       dirty_log
       @base = base
-      @count = count
+      max_count(max_count)
+    end
+
+    # The maximum number of commits to return
+    #
+    # @example All commits returned by `git log`
+    #   git = Git.open('.')
+    #   Git::Log.new(git).max_count(:all)
+    #
+    # @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 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
+    #
+    # @return [self]
+    #
     def all
       dirty_log
       @all = true
@@ -119,7 +180,7 @@ def check_log
       # 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,
+          count: @max_count, all: @all, object: @object, path_limiter: @path, since: @since,
           author: @author, grep: @grep, skip: @skip, until: @until, between: @between,
           cherry: @cherry
         )
diff --git a/tests/units/test_log.rb b/tests/units/test_log.rb
@@ -9,6 +9,28 @@ def setup
     @git = Git.open(@wdir)
   end
 
+  def test_log_max_count_default
+    assert_equal(30, @git.log.size)
+  end
+
+  # In these tests, note that @git.log(n) is equivalent to @git.log.max_count(n)
+  def test_log_max_count_20
+    assert_equal(20, @git.log(20).size)
+    assert_equal(20, @git.log.max_count(20).size)
+  end
+
+  def test_log_max_count_nil
+    assert_equal(72, @git.log(nil).size)
+    assert_equal(72, @git.log.max_count(nil).size)
+  end
+
+  def test_log_max_count_all
+    assert_equal(72, @git.log(:all).size)
+    assert_equal(72, @git.log.max_count(:all).size)
+  end
+
+  # Note that @git.log.all does not control the number of commits returned. For that,
+  # use @git.log.max_count(n)
   def test_log_all
     assert_equal(72, @git.log(100).size)
     assert_equal(76, @git.log(100).all.size)
