ruby-git · jcouball · Jul 3, 2025 · Jul 3, 2025 · Jul 3, 2025 · Jul 3, 2025
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -3,6 +3,25 @@ inherit_from: .rubocop_todo.yml
 inherit_gem:
   main_branch_shared_rubocop_config: config/rubocop.yml
 
+# Allow test data to have long lines
+Layout/LineLength:
+  Exclude:
+    - "tests/test_helper.rb"
+    - "tests/units/**/*"
+    - "*.gemspec"
+
+# Testing and gemspec DSL results in large blocks
+Metrics/BlockLength:
+  Exclude:
+    - "tests/test_helper.rb"
+    - "tests/units/**/*"
+    - "*.gemspec"
+
+# Don't force every test class to be described
+Style/Documentation:
+  Exclude:
+    - "tests/units/**/*"
+
 AllCops:
   # Pin this project to Ruby 3.1 in case the shared config above is upgraded to 3.2
   # or later.

diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml
@@ -6,61 +6,15 @@
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 2
-Lint/DuplicateMethods:
-  Exclude:
-    - 'lib/git/base.rb'
-    - 'lib/git/worktree.rb'
-
-# Offense count: 1
-# Configuration parameters: AllowComments, AllowEmptyLambdas.
-Lint/EmptyBlock:
-  Exclude:
-    - 'tests/units/test_archive.rb'
-
-# Offense count: 3
-# Configuration parameters: AllowedParentClasses.
-Lint/MissingSuper:
-  Exclude:
-    - 'lib/git/branch.rb'
-    - 'lib/git/remote.rb'
-    - 'lib/git/worktree.rb'
-
-# Offense count: 8
-Lint/StructNewOverride:
-  Exclude:
-    - 'tests/units/test_command_line_error.rb'
-    - 'tests/units/test_failed_error.rb'
-    - 'tests/units/test_signaled_error.rb'
-    - 'tests/units/test_timeout_error.rb'
-
-# Offense count: 2
-# Configuration parameters: AllowComments, AllowNil.
-Lint/SuppressedException:
-  Exclude:
-    - 'lib/git/lib.rb'
-    - 'tests/units/test_each_conflict.rb'
-
-# Offense count: 1
-Lint/UselessConstantScoping:
-  Exclude:
-    - 'lib/git/branch.rb'
-
 # Offense count: 68
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
   Max: 109
 
-# Offense count: 8
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
-# AllowedMethods: refine
-Metrics/BlockLength:
-  Max: 49
-
 # Offense count: 21
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 898
+  Max: 925
 
 # Offense count: 14
 # Configuration parameters: AllowedMethods, AllowedPatterns.
@@ -72,92 +26,7 @@ Metrics/CyclomaticComplexity:
 Metrics/MethodLength:
   Max: 51
 
-# Offense count: 2
-# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
-Metrics/ParameterLists:
-  Max: 8
-
 # Offense count: 12
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
   Max: 22
-
-# Offense count: 1
-Naming/AccessorMethodName:
-  Exclude:
-    - 'lib/git/object.rb'
-
-# Offense count: 1
-# Configuration parameters: ForbiddenDelimiters.
-# ForbiddenDelimiters: (?i-mx:(^|\s)(EO[A-Z]{1}|END)(\s|$))
-Naming/HeredocDelimiterNaming:
-  Exclude:
-    - 'tests/units/test_signed_commits.rb'
-
-# Offense count: 5
-# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods.
-# AllowedMethods: call
-Naming/PredicateMethod:
-  Exclude:
-    - 'lib/git/branch.rb'
-    - 'lib/git/lib.rb'
-    - 'tests/units/test_command_line.rb'
-
-# Offense count: 3
-# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
-# NamePrefix: is_, has_, have_, does_
-# ForbiddenPrefixes: is_, has_, have_, does_
-# AllowedMethods: is_a?
-# MethodDefinitionMacros: define_method, define_singleton_method
-Naming/PredicatePrefix:
-  Exclude:
-    - 'spec/**/*'
-    - 'lib/git/base.rb'
-
-# Offense count: 2
-# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
-# SupportedStyles: snake_case, normalcase, non_integer
-# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
-Naming/VariableNumber:
-  Exclude:
-    - 'tests/units/test_log.rb'
-    - 'tests/units/test_log_execute.rb'
-
-# Offense count: 1
-Style/ClassVars:
-  Exclude:
-    - 'lib/git/base.rb'
-
-# Offense count: 66
-# Configuration parameters: AllowedConstants.
-Style/Documentation:
-  Enabled: false
-
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-Style/IfUnlessModifier:
-  Exclude:
-    - 'lib/git/base.rb'
-    - 'lib/git/lib.rb'
-
-# Offense count: 2
-Style/MultilineBlockChain:
-  Exclude:
-    - 'lib/git/base.rb'
-
-# Offense count: 5
-# Configuration parameters: AllowedMethods.
-# AllowedMethods: respond_to_missing?
-Style/OptionalBooleanParameter:
-  Exclude:
-    - 'lib/git/base.rb'
-    - 'lib/git/object.rb'
-    - 'lib/git/path.rb'
-    - 'lib/git/stash.rb'
-
-# Offense count: 64
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
-# URISchemes: http, https
-Layout/LineLength:
-  Max: 346
diff --git a/lib/git.rb b/lib/git.rb
@@ -216,7 +216,8 @@ def self.clone(repository_url, directory = nil, options = {})
   # @example with the logging option
   #   logger = Logger.new(STDOUT, level: Logger::INFO)
   #   Git.default_branch('.', log: logger) # => 'master'
-  #   I, [2022-04-13T16:01:33.221596 #18415]  INFO -- : git '-c' 'core.quotePath=true' '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD'  2>&1
+  #   I, [2022-04-13T16:01:33.221596 #18415]  INFO -- : git '-c' 'core.quotePath=true'
+  #     '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD'  2>&1
   #
   # @param repository [URI, Pathname, String] The (possibly remote) repository to get the default branch name for
   #

diff --git a/lib/git/author.rb b/lib/git/author.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Git
+  # An author in a Git commit
   class Author
     attr_accessor :name, :email, :date
 

diff --git a/lib/git/base.rb b/lib/git/base.rb
@@ -35,7 +35,7 @@ def self.repository_default_branch(repository, options = {})
     #
     # @return [Git::Config] the current config instance.
     def self.config
-      @@config ||= Config.new
+      @config ||= Config.new
     end
 
     def self.binary_version(binary_path)
@@ -91,8 +91,10 @@ def self.root_of_worktree(working_dir)
       raise ArgumentError, "'#{working_dir}' does not exist" unless Dir.exist?(working_dir)
 
       begin
-        result, status = Open3.capture2e(Git::Base.config.binary_path, '-c', 'core.quotePath=true', '-c',
-                                         'color.ui=false', 'rev-parse', '--show-toplevel', chdir: File.expand_path(working_dir))
+        result, status = Open3.capture2e(
+          Git::Base.config.binary_path, '-c', 'core.quotePath=true', '-c',
+          'color.ui=false', 'rev-parse', '--show-toplevel', chdir: File.expand_path(working_dir)
+        )
         result = result.chomp
       rescue Errno::ENOENT
         raise ArgumentError, 'Failed to find the root of the worktree: git binary not found'
@@ -182,29 +184,6 @@ def add_remote(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)
-      lib.tag(name, *options)
-      tag(name)
-    end
-
     # changes current working directory for a block
     # to the git working directory
     #
@@ -256,43 +235,77 @@ def repo
 
     # returns the repository size in bytes
     def repo_size
-      Dir.glob(File.join(repo.path, '**', '*'), File::FNM_DOTMATCH).reject do |f|
-        f.include?('..')
-      end.map do |f|
-        File.expand_path(f)
-      end.uniq.map do |f|
-        File.stat(f).size.to_i
-      end.reduce(:+)
+      all_files = Dir.glob(File.join(repo.path, '**', '*'), File::FNM_DOTMATCH)
+
+      all_files.reject { |file| file.include?('..') }
+               .map { |file| File.expand_path(file) }
+               .uniq
+               .sum { |file| File.stat(file).size.to_i }
     end
 
-    def set_index(index_file, check = true)
+    def set_index(index_file, check = nil, must_exist: nil)
+      unless check.nil?
+        Git::Deprecation.warn(
+          'The "check" argument is deprecated and will be removed in a future version. ' \
+          'Use "must_exist:" instead.'
+        )
+      end
+
+      # default is true
+      must_exist = must_exist.nil? && check.nil? ? true : must_exist | check
+
       @lib = nil
-      @index = Git::Index.new(index_file.to_s, check)
+      @index = Git::Index.new(index_file.to_s, must_exist:)
     end
 
-    def set_working(work_dir, check = true)
+    def set_working(work_dir, check = nil, must_exist: nil)
+      unless check.nil?
+        Git::Deprecation.warn(
+          'The "check" argument is deprecated and will be removed in a future version. ' \
+          'Use "must_exist:" instead.'
+        )
+      end
+
+      # default is true
+      must_exist = must_exist.nil? && check.nil? ? true : must_exist | check
+
       @lib = nil
-      @working_directory = Git::WorkingDirectory.new(work_dir.to_s, check)
+      @working_directory = Git::WorkingDirectory.new(work_dir.to_s, must_exist:)
     end
 
     # returns +true+ if the branch exists locally
-    def is_local_branch?(branch)
+    def local_branch?(branch)
       branch_names = branches.local.map(&:name)
       branch_names.include?(branch)
     end
 
+    def is_local_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+      Git.deprecation('Git::Base#is_local_branch? is deprecated. Use Git::Base#local_branch? instead.')
+      local_branch?(branch)
+    end
+
     # returns +true+ if the branch exists remotely
-    def is_remote_branch?(branch)
+    def remote_branch?(branch)
       branch_names = branches.remote.map(&:name)
       branch_names.include?(branch)
     end
 
+    def is_remote_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+      Git.deprecated('Git::Base#is_remote_branch? is deprecated. Use Git::Base#remote_branch? instead.')
+      remote_branch?(branch)
+    end
+
     # returns +true+ if the branch exists
-    def is_branch?(branch)
+    def branch?(branch)
       branch_names = branches.map(&:name)
       branch_names.include?(branch)
     end
 
+    def is_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+      Git.deprecated('Git::Base#is_branch? is deprecated. Use Git::Base#branch? instead.')
+      branch?(branch)
+    end
+
     # this is a convenience method for accessing the class that wraps all the
     # actual 'git' forked system calls.  At some point I hope to replace the Git::Lib
     # class with one that uses native methods or libgit C bindings
@@ -768,7 +781,7 @@ def status
 
     # @return [Git::Object::Tag] a tag object
     def tag(tag_name)
-      Git::Object.new(self, tag_name, 'tag', true)
+      Git::Object::Tag.new(self, tag_name)
     end
 
     # Find as good common ancestors as possible for a merge
@@ -874,7 +887,8 @@ def diff_path_status(objectish = 'HEAD', obj2 = nil)
         end
 
       if File.file?(repository)
-        repository = File.expand_path(File.read(repository)[8..].strip, options[:working_directory])
+        repository = File.expand_path(File.read(repository)[8..].strip,
+                                      options[:working_directory])
       end
 
       options[:repository] = repository