git 4.0.6 → 4.3.0

data/git.gemspec

@@ -44,6 +44,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'test-unit', '~> 3.6'
 
   unless RUBY_PLATFORM == 'java'
+    spec.add_development_dependency 'irb', '~> 1.6'
     spec.add_development_dependency 'redcarpet', '~> 3.6'
     spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
     spec.add_development_dependency 'yardstick', '~> 0.9'

data/lib/git/args_builder.rb

@@ -12,6 +12,14 @@ module Git
     ARG_BUILDERS = {
       boolean: ->(config, value) { value ? config[:flag] : [] },
 
+      boolean_negatable: lambda do |config, value|
+        case value
+        when true then config[:flag]
+        when false then config[:flag].sub('--', '--no-')
+        else []
+        end
+      end,
+
       valued_equals: ->(config, value) { "#{config[:flag]}=#{value}" if value },
 
       valued_space: ->(config, value) { [config[:flag], value.to_s] if value },

data/lib/git/base.rb

@@ -21,7 +21,9 @@ module Git
 
     # (see Git.clone)
     def self.clone(repository_url, directory, options = {})
-      new_options = Git::Lib.new(nil, options[:log]).clone(repository_url, directory, options)
+      lib_options = {}
+      lib_options[:git_ssh] = options[:git_ssh] if options.key?(:git_ssh)
+      new_options = Git::Lib.new(lib_options, options[:log]).clone(repository_url, directory, options)
       normalize_paths(new_options, bare: options[:bare] || options[:mirror])
       new(new_options)
     end
@@ -148,12 +150,20 @@ module Git
     #   commands are logged at the `:info` level.  Additional logging is done
     #   at the `:debug` level.
     #
+    # @option options [String, nil] :git_ssh Path to a custom SSH executable or script.
+    #   Controls how SSH is configured for this {Git::Base} instance:
+    #   - If this option is not provided, the global Git::Base.config.git_ssh setting is used.
+    #   - If this option is explicitly set to nil, SSH is disabled for this instance.
+    #   - If this option is a non-empty String, that value is used as the SSH command for
+    #     this instance, overriding the global Git::Base.config.git_ssh setting.
+    #
     # @return [Git::Base] an object that can execute git commands in the context
     #   of the opened working copy or bare repository
     #
     def initialize(options = {})
       options = default_paths(options)
       setup_logger(options[:log])
+      @git_ssh = options.key?(:git_ssh) ? options[:git_ssh] : :use_global_config
       initialize_components(options)
     end
 
@@ -185,7 +195,7 @@ module Git
     #   :fetch => true
     #   :track => <branch_name>
     def add_remote(name, url, opts = {})
-      url = url.repo.path if url.is_a?(Git::Base)
+      url = url.repo.to_s if url.is_a?(Git::Base)
       lib.remote_add(name, url, opts)
       Git::Remote.new(self, name)
     end
@@ -200,8 +210,8 @@ module Git
     #    @git.commit('message')
     #  end
     def chdir # :yields: the Git::Path
-      Dir.chdir(dir.path) do
-        yield dir.path
+      Dir.chdir(dir.to_s) do
+        yield dir.to_s
       end
     end
 
@@ -328,6 +338,17 @@ module Git
       @lib ||= Git::Lib.new(self, @logger)
     end
 
+    # Returns the per-instance git_ssh configuration value.
+    #
+    # This may be:
+    # * a [String] path when an explicit git_ssh command has been configured
+    # * the Symbol `:use_global_config` when this instance is using the global config
+    # * `nil` when SSH has been explicitly disabled for this instance
+    #
+    # @return [String, Symbol, nil] the git_ssh configuration value for this instance
+    # @api private
+    attr_reader :git_ssh
+
     # Run a grep for 'string' on the HEAD of the git repository
     #
     # @example Limit grep's scope by calling grep() from a specific object:
@@ -342,7 +363,8 @@ module Git
     #   end
     #
     # @param string [String] the string to search for
-    # @param path_limiter [String, Array] a path or array of paths to limit the search to or nil for no limit
+    # @param path_limiter [String, Pathname, Array<String, Pathname>] a path or array
+    #   of paths to limit the search to or nil for no limit
     # @param opts [Hash] options to pass to the underlying `git grep` command
     #
     # @option opts [Boolean] :ignore_case (false) ignore case when matching
@@ -508,8 +530,8 @@ module Git
     # @param branch [String] the branch to pull from
     # @param opts [Hash] options to pass to the pull command
     #
-    # @option opts [Boolean] :allow_unrelated_histories (false) Merges histories of two projects that started their
-    #   lives independently
+    # @option opts [Boolean] :allow_unrelated_histories (false) Merges histories of
+    #   two projects that started their lives independently
     # @example pulls from origin/master
     #   @git.pull
     # @example pulls from upstream/master
@@ -536,11 +558,48 @@ module Git
     #  @git.set_remote_url('scotts_git', 'git://repo.or.cz/rubygit.git')
     #
     def set_remote_url(name, url)
-      url = url.repo.path if url.is_a?(Git::Base)
+      url = url.repo.to_s if url.is_a?(Git::Base)
       lib.remote_set_url(name, url)
       Git::Remote.new(self, name)
     end
 
+    # Configures which branches are fetched for a remote
+    #
+    # Uses `git remote set-branches` to set or append fetch refspecs. When the `add:`
+    # option is not given, the `--add` option is not passed to the git command
+    #
+    # @example Replace fetched branches with a single glob pattern
+    #   git = Git.open('/path/to/repo')
+    #   # Only fetch branches matching "feature/*" from origin
+    #   git.remote_set_branches('origin', 'feature/*')
+    #
+    # @example Append a glob pattern to existing fetched branches
+    #   git = Git.open('/path/to/repo')
+    #   # Keep existing fetch refspecs and add all release branches
+    #   git.remote_set_branches('origin', 'release/*', add: true)
+    #
+    # @example Configure multiple explicit branches
+    #   git = Git.open('/path/to/repo')
+    #   git.remote_set_branches('origin', 'main', 'development', 'hotfix')
+    #
+    # @param name [String] the remote name (for example, "origin")
+    # @param branches [Array<String>] branch names or globs (for example, '*')
+    # @param add [Boolean] when true, append to existing refspecs instead of replacing them
+    #
+    # @return [nil]
+    #
+    # @raise [ArgumentError] if no branches are provided @raise [Git::FailedError] if
+    # the underlying git command fails
+    #
+    def remote_set_branches(name, *branches, add: false)
+      branch_list = branches.flatten
+      raise ArgumentError, 'branches are required' if branch_list.empty?
+
+      lib.remote_set_branches(name, branch_list, add: add)
+
+      nil
+    end
+
     # removes a remote from this repository
     #
     # @git.remove_remote('scott_git')
@@ -595,6 +654,57 @@ module Git
       lib.gc
     end
 
+    # Verifies the connectivity and validity of objects in the database
+    #
+    # Runs `git fsck` to check repository integrity and identify dangling,
+    # missing, or unreachable objects.
+    #
+    # @overload fsck(objects = [], options = {})
+    #   @param objects [Array<String>] specific objects to treat as heads for unreachability trace.
+    #     If no objects are given, git fsck defaults to using the index file, all SHA-1
+    #     references in the refs namespace, and all reflogs.
+    #   @param [Hash] options options to pass to the underlying `git fsck` command
+    #
+    #   @option options [Boolean] :unreachable print unreachable objects
+    #   @option options [Boolean] :strict enable strict checking
+    #   @option options [Boolean] :connectivity_only check only connectivity (faster)
+    #   @option options [Boolean] :root report root nodes
+    #   @option options [Boolean] :tags report tags
+    #   @option options [Boolean] :cache consider objects in the index
+    #   @option options [Boolean] :no_reflogs do not consider reflogs
+    #   @option options [Boolean] :lost_found write dangling objects to .git/lost-found
+    #     (note: this modifies the repository by creating files)
+    #   @option options [Boolean, nil] :dangling print dangling objects (true/false/nil for default)
+    #   @option options [Boolean, nil] :full check objects in alternate pools (true/false/nil for default)
+    #   @option options [Boolean, nil] :name_objects name objects by refs (true/false/nil for default)
+    #   @option options [Boolean, nil] :references check refs database consistency (true/false/nil for default)
+    #
+    #   @return [Git::FsckResult] categorized objects flagged by fsck
+    #
+    #   @example Check repository integrity
+    #     result = git.fsck
+    #     result.dangling.each { |obj| puts "#{obj.type}: #{obj.sha}" }
+    #
+    #   @example Check with strict mode and suppress dangling output
+    #     result = git.fsck(strict: true, dangling: false)
+    #
+    #   @example Check if repository has any issues
+    #     result = git.fsck
+    #     puts "Repository is clean" if result.empty?
+    #
+    #   @example List root commits
+    #     result = git.fsck(root: true)
+    #     result.root.each { |obj| puts obj.sha }
+    #
+    #   @example Check specific objects
+    #     result = git.fsck('abc1234', 'def5678')
+    #
+    # rubocop:disable Style/ArgumentsForwarding
+    def fsck(*objects, **opts)
+      lib.fsck(*objects, **opts)
+    end
+    # rubocop:enable Style/ArgumentsForwarding
+
     def apply(file)
       return unless File.exist?(file)
 
@@ -812,18 +922,32 @@ module Git
     #
     # @param objectish [String] The first commit or object to compare. Defaults to 'HEAD'.
     # @param obj2 [String, nil] The second commit or object to compare.
-    # @return [Git::Diff::Stats]
-    def diff_stats(objectish = 'HEAD', obj2 = nil)
-      Git::DiffStats.new(self, objectish, obj2)
+    # @param opts [Hash] Options to filter the diff.
+    # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter Limit stats to specified path(s).
+    # @return [Git::DiffStats]
+    def diff_stats(objectish = 'HEAD', obj2 = nil, opts = {})
+      Git::DiffStats.new(self, objectish, obj2, opts[:path_limiter])
     end
 
     # Returns a Git::Diff::PathStatus object for accessing the name-status report.
     #
     # @param objectish [String] The first commit or object to compare. Defaults to 'HEAD'.
     # @param obj2 [String, nil] The second commit or object to compare.
-    # @return [Git::Diff::PathStatus]
-    def diff_path_status(objectish = 'HEAD', obj2 = nil)
-      Git::DiffPathStatus.new(self, objectish, obj2)
+    # @param opts [Hash] Options to filter the diff.
+    # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter Limit status to specified path(s).
+    # @option opts [String, Pathname, Array<String, Pathname>] :path (deprecated) Legacy alias for :path_limiter.
+    # @return [Git::DiffPathStatus]
+    def diff_path_status(objectish = 'HEAD', obj2 = nil, opts = {})
+      path_limiter = if opts.key?(:path_limiter)
+                       opts[:path_limiter]
+                     elsif opts.key?(:path)
+                       Git::Deprecation.warn(
+                         'Git::Base#diff_path_status :path option is deprecated. Use :path_limiter instead.'
+                       )
+                       opts[:path]
+                     end
+
+      Git::DiffPathStatus.new(self, objectish, obj2, path_limiter)
     end
 
     # Provided for backwards compatibility

data/lib/git/diff.rb

@@ -18,8 +18,38 @@ module Git
     end
     attr_reader :from, :to
 
-    def path(path)
-      @path = path
+    # Limits the diff to the specified path(s)
+    #
+    # When called with no arguments (or only nil arguments), removes any existing
+    # path filter, showing all files in the diff. Internally stores a single path
+    # as a String and multiple paths as an Array for efficiency.
+    #
+    # @example Limit diff to a single path
+    #   git.diff('HEAD~3', 'HEAD').path('lib/')
+    #
+    # @example Limit diff to multiple paths
+    #   git.diff('HEAD~3', 'HEAD').path('src/', 'docs/', 'README.md')
+    #
+    # @example Remove path filtering (show all files)
+    #   diff.path  # or diff.path(nil)
+    #
+    # @param paths [String, Pathname] one or more paths to filter the diff. Pass no arguments to remove filtering.
+    # @return [self] returns self for method chaining
+    # @raise [ArgumentError] if any path is an Array (use splatted arguments instead)
+    #
+    def path(*paths)
+      validate_paths_not_arrays(paths)
+
+      cleaned_paths = paths.compact
+
+      @path = if cleaned_paths.empty?
+                nil
+              elsif cleaned_paths.length == 1
+                cleaned_paths.first
+              else
+                cleaned_paths
+              end
+
       self
     end
 
@@ -102,6 +132,14 @@ module Git
 
     private
 
+    def validate_paths_not_arrays(paths)
+      return unless paths.any? { |p| p.is_a?(Array) }
+
+      raise ArgumentError,
+            'path expects individual arguments, not arrays. ' \
+            "Use path('lib/', 'docs/') not path(['lib/', 'docs/'])"
+    end
+
     def process_full
       return if @full_diff_files
 

data/lib/git/diff_path_status.rb

@@ -39,7 +39,7 @@ module Git
     # Lazily fetches and caches the path status from the git lib.
     def fetch_path_status
       @fetch_path_status ||= @base.lib.diff_path_status(
-        @from, @to, { path: @path_limiter }
+        @from, @to, { path_limiter: @path_limiter }
       )
     end
   end

data/lib/git/fsck_object.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents an object returned by `git fsck`
+  #
+  # This class provides information about dangling, missing, unreachable, or
+  # problematic Git objects found during repository integrity checks.
+  #
+  # @api public
+  #
+  class FsckObject
+    # The type of the Git object
+    # @return [Symbol] one of :commit, :tree, :blob, or :tag
+    attr_reader :type
+
+    # The SHA-1 hash of the object
+    # @return [String] the 40-character SHA-1 hash
+    attr_reader :sha
+
+    # A warning or error message associated with this object
+    # @return [String, nil] the message, or nil if no message
+    attr_reader :message
+
+    # A name describing how the object is reachable (from --name-objects)
+    # @return [String, nil] the name, or nil if not provided
+    attr_reader :name
+
+    # Create a new FsckObject
+    #
+    # @param type [Symbol] the object type (:commit, :tree, :blob, or :tag)
+    # @param sha [String] the 40-character SHA-1 hash
+    # @param message [String, nil] optional warning/error message
+    # @param name [String, nil] optional name from --name-objects (e.g., "HEAD~2^2:src/")
+    #
+    def initialize(type:, sha:, message: nil, name: nil)
+      @type = type
+      @sha = sha
+      @message = message
+      @name = name
+    end
+
+    # Returns the SHA as the string representation
+    # @return [String] the SHA-1 hash
+    def to_s
+      sha
+    end
+  end
+end

data/lib/git/fsck_result.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents the result of running `git fsck`
+  #
+  # This class provides structured access to the objects found during a
+  # repository integrity check, categorized by their status.
+  #
+  # @api public
+  #
+  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
+
+    # rubocop:disable Metrics/ParameterLists
+
+    # 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: [])
+      @dangling = dangling
+      @missing = missing
+      @unreachable = unreachable
+      @warnings = warnings
+      @root = root
+      @tagged = tagged
+    end
+
+    # rubocop:enable Metrics/ParameterLists
+
+    # Returns true if any issues were found
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   result = git.fsck
+    #   puts "Repository has issues!" if result.any_issues?
+    #
+    def any_issues?
+      [dangling, missing, unreachable, warnings].any?(&:any?)
+    end
+
+    # Returns true if no issues were found
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   result = git.fsck
+    #   puts "Repository is clean" if result.empty?
+    #
+    def empty?
+      !any_issues?
+    end
+
+    # Returns all objects from all categories (excluding informational root/tagged)
+    #
+    # @return [Array<Git::FsckObject>]
+    #
+    # @example
+    #   result = git.fsck
+    #   result.all_objects.each { |obj| puts obj.sha }
+    #
+    def all_objects
+      dangling + missing + unreachable + warnings
+    end
+
+    # Returns the total number of issues found
+    #
+    # @return [Integer]
+    #
+    # @example
+    #   result = git.fsck
+    #   puts "Found #{result.count} issues"
+    #
+    def count
+      all_objects.size
+    end
+
+    # Returns a hash representation of the result
+    #
+    # @return [Hash{Symbol => Array<Git::FsckObject>}]
+    #
+    # @example
+    #   result = git.fsck
+    #   result.to_h # => { dangling: [...], missing: [...], ... }
+    #
+    def to_h
+      {
+        dangling: dangling, missing: missing, unreachable: unreachable,
+        warnings: warnings, root: root, tagged: tagged
+      }
+    end
+  end
+end