git 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c7aebf8b61eb75a0d3e587fae03711b1d9cec89c7fb69462bda24c069daeaa4
-  data.tar.gz: f73bd8a6e030209305ffbcc1bae372cd6820745569142ddd7239b366ef78d322
+  metadata.gz: cf601afe6ddef5cc504f0a350bd9595feb76cc95822bd65716d6b5cecf2d324d
+  data.tar.gz: 5f334a391220774ab0fea9c789a87fe3a45d9de55e0745d87f59c0bc9a52e5a9
 SHA512:
-  metadata.gz: 32c0e605d3ee280c19cf863f5b9a5fc9437171b9facbbee074b2ddca096c4cae3f08ddf42cb6cad7a91512824f40cd51940e1846c1f1a3e5bb7f4e7ee52e154b
-  data.tar.gz: 528bf8926dbf6b76681b8333ca3d797b1e28854921f6abcd5b2fd9a13c6861c25e6ad75462efb818c1c74de0980c96974a423ad2a19aaf87d5b27e3e2ffca8cf
+  metadata.gz: 20133b00f0f50ccc00dc1bd4bb88107911ff5f438e127b804270752c43029e2447b15a5212c701a24a49a6f98d7b12359cb3326924ea3dadf631408b316e626e
+  data.tar.gz: 11ca7ae94de18e0b3d4aad99d315c2b973a8e2521ee24a935e5236fdc91eace943074ad388889a09ef4d8e33e2a4b1355d2590fe16fe0a1eda05357e1a315290

data/CHANGELOG.md

@@ -5,6 +5,15 @@
 
 # Change Log
 
+## v2.1.0 (2024-05-31)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.0.1..v2.1.0)
+
+Changes since v2.0.1:
+
+* 93c8210 Add Git::Log#max_count
+* d84097b Update YARDoc for a few a few method
+
 ## v2.0.1 (2024-05-21)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.0.0..v2.0.1)

data/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
 

data/lib/git/base.rb

@@ -2,12 +2,14 @@ require 'logger'
 require 'open3'
 
 module Git
-  # Git::Base is the main public interface for interacting with Git commands.
+  # The main public interface for interacting with Git commands
   #
   # Instead of creating a Git::Base directly, obtain a Git::Base instance by
   # calling one of the follow {Git} class methods: {Git.open}, {Git.init},
   # {Git.clone}, or {Git.bare}.
   #
+  # @api public
+  #
   class Base
     # (see Git.bare)
     def self.bare(git_dir, options = {})
@@ -119,6 +121,62 @@ module Git
       @index = options[:index] ? Git::Index.new(options[:index], false) : nil
     end
 
+    # Update the index from the current worktree to prepare the for the next commit
+    #
+    # @example
+    #   lib.add('path/to/file')
+    #   lib.add(['path/to/file1','path/to/file2'])
+    #   lib.add(all: true)
+    #
+    # @param [String, Array<String>] paths a file or files to be added to the repository (relative to the worktree root)
+    # @param [Hash] options
+    #
+    # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
+    # @option options [Boolean] :force Allow adding otherwise ignored files
+    #
+    def add(paths = '.', **options)
+      self.lib.add(paths, options)
+    end
+
+    # adds a new remote to this repository
+    # url can be a git url or a Git::Base object if it's a local reference
+    #
+    #  @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
+    #  @git.fetch('scotts_git')
+    #  @git.merge('scotts_git/master')
+    #
+    # Options:
+    #   :fetch => true
+    #   :track => <branch_name>
+    def add_remote(name, url, opts = {})
+      url = url.repo.path if url.is_a?(Git::Base)
+      self.lib.remote_add(name, url, opts)
+      Git::Remote.new(self, name)
+    end
+
+    # Create a new git tag
+    #
+    # @example
+    #   repo.add_tag('tag_name', object_reference)
+    #   repo.add_tag('tag_name', object_reference, {:options => 'here'})
+    #   repo.add_tag('tag_name', {:options => 'here'})
+    #
+    # @param [String] name The name of the tag to add
+    # @param [Hash] options Opstions to pass to `git tag`.
+    #   See [git-tag](https://git-scm.com/docs/git-tag) for more details.
+    # @option options [boolean] :annotate Make an unsigned, annotated tag object
+    # @option options [boolean] :a An alias for the `:annotate` option
+    # @option options [boolean] :d Delete existing tag with the given names.
+    # @option options [boolean] :f Replace an existing tag with the given name (instead of failing)
+    # @option options [String] :message Use the given tag message
+    # @option options [String] :m An alias for the `:message` option
+    # @option options [boolean] :s Make a GPG-signed tag.
+    #
+    def add_tag(name, *options)
+      self.lib.tag(name, *options)
+      self.tag(name)
+    end
+
     # changes current working directory for a block
     # to the git working directory
     #
@@ -251,29 +309,6 @@ module Git
       self.object('HEAD').grep(string, path_limiter, opts)
     end
 
-    # updates the repository index using the working directory content
-    #
-    # @example
-    #   git.add
-    #   git.add('path/to/file')
-    #   git.add(['path/to/file1','path/to/file2'])
-    #   git.add(:all => true)
-    #
-    # options:
-    #   :all => true
-    #
-    # @param [String,Array] paths files paths to be added (optional, default='.')
-    # @param [Hash] options
-    # @option options [boolean] :all
-    #   Update the index not only where the working tree has a file matching
-    #   <pathspec> but also where the index already has an entry.
-    #   See [the --all option to git-add](https://git-scm.com/docs/git-add#Documentation/git-add.txt--A)
-    #   for more details.
-    #
-    def add(paths = '.', **options)
-      self.lib.add(paths, options)
-    end
-
     # removes file(s) from the git repository
     def rm(path = '.', opts = {})
       self.lib.rm(path, opts)
@@ -434,22 +469,6 @@ module Git
       self.lib.remotes.map { |r| Git::Remote.new(self, r) }
     end
 
-    # adds a new remote to this repository
-    # url can be a git url or a Git::Base object if it's a local reference
-    #
-    #  @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
-    #  @git.fetch('scotts_git')
-    #  @git.merge('scotts_git/master')
-    #
-    # Options:
-    #   :fetch => true
-    #   :track => <branch_name>
-    def add_remote(name, url, opts = {})
-      url = url.repo.path if url.is_a?(Git::Base)
-      self.lib.remote_add(name, url, opts)
-      Git::Remote.new(self, name)
-    end
-
     # sets the url for a remote
     # url can be a git url or a Git::Base object if it's a local reference
     #
@@ -473,7 +492,7 @@ module Git
       self.lib.tags.map { |r| tag(r) }
     end
 
-    # Creates a new git tag (Git::Tag)
+    # Create a new git tag
     #
     # @example
     #   repo.add_tag('tag_name', object_reference)

data/lib/git/lib.rb

@@ -38,14 +38,23 @@ module Git
 
     # Create a new Git::Lib object
     #
-    # @param [Git::Base, Hash] base An object that passes in values for
-    #   @git_work_dir, @git_dir, and @git_index_file
+    # @overload initialize(base, logger)
     #
-    # @param [Logger] logger
+    #   @param base [Hash] the hash containing paths to the Git working copy,
+    #     the Git repository directory, and the Git index file.
     #
-    # @option base [Pathname] :working_directory
-    # @option base [Pathname] :repository
-    # @option base [Pathname] :index
+    #   @option base [Pathname] :working_directory
+    #   @option base [Pathname] :repository
+    #   @option base [Pathname] :index
+    #
+    #   @param [Logger] logger
+    #
+    # @overload initialize(base, logger)
+    #
+    #   @param base [#dir, #repo, #index] an object with methods to get the Git worktree (#dir),
+    #     the Git repository directory (#repo), and the Git index file (#index).
+    #
+    #   @param [Logger] logger
     #
     def initialize(base = nil, logger = nil)
       @git_dir = nil
@@ -670,18 +679,20 @@ module Git
       command('config', '--global', name, value)
     end
 
-    # updates the repository index using the working directory content
-    #
-    #    lib.add('path/to/file')
-    #    lib.add(['path/to/file1','path/to/file2'])
-    #    lib.add(:all => true)
+
+    # Update the index from the current worktree to prepare the for the next commit
     #
-    # options:
-    #   :all => true
-    #   :force => true
+    # @example
+    #   lib.add('path/to/file')
+    #   lib.add(['path/to/file1','path/to/file2'])
+    #   lib.add(:all => true)
     #
-    # @param [String,Array] paths files paths to be added to the repository
+    # @param [String, Array<String>] paths files to be added to the repository (relative to the worktree root)
     # @param [Hash] options
+    #
+    # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
+    # @option options [Boolean] :force Allow adding otherwise ignored files
+    #
     def add(paths='.',options={})
       arr_opts = []
 

data/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 @@ module Git
       # 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
         )

data/lib/git/version.rb

@@ -1,5 +1,5 @@
 module Git
   # The current gem version
   # @return [String] the current gem version.
-  VERSION='2.0.1'
+  VERSION='2.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Scott Chacon and others
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-21 00:00:00.000000000 Z
+date: 2024-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -243,8 +243,8 @@ licenses:
 metadata:
   homepage_uri: http://github.com/ruby-git/ruby-git
   source_code_uri: http://github.com/ruby-git/ruby-git
-  changelog_uri: https://rubydoc.info/gems/git/2.0.1/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/2.0.1
+  changelog_uri: https://rubydoc.info/gems/git/2.1.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/2.1.0
 post_install_message:
 rdoc_options: []
 require_paths: