git 4.0.7 → 4.1.0

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.0.7"
+  ".": "4.1.0"
 }

data/.rubocop_todo.yml

@@ -9,4 +9,4 @@
 # Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 1039
+  Max: 1150

data/CHANGELOG.md

@@ -5,6 +5,30 @@
 
 # Change Log
 
+## [4.1.0](https://github.com/ruby-git/ruby-git/compare/v4.0.7...v4.1.0) (2026-01-02)
+
+
+### Features
+
+* Add per-instance git_ssh configuration support ([26c1199](https://github.com/ruby-git/ruby-git/commit/26c119969ec71c23c965f55f0570471f8ddf333a))
+* **clone:** Add single_branch option ([a6929bb](https://github.com/ruby-git/ruby-git/commit/a6929bb0bfd51cba3a595e47740897ca619da468))
+* **diff:** Allow multiple paths in diff path limiter ([c663b62](https://github.com/ruby-git/ruby-git/commit/c663b62a0c9075a18c112e2cda3744f88f42ab7e))
+* **remote:** Add remote set-branches helper ([a7dab2b](https://github.com/ruby-git/ruby-git/commit/a7dab2bdf9088f0610dfbf3e3b78677b90195f75))
+
+
+### Bug Fixes
+
+* Prevent GIT_INDEX_FILE from corrupting worktree indexes ([27c0f16](https://github.com/ruby-git/ruby-git/commit/27c0f1629927ae23a5bb8efc4df79756a9e4406b))
+* **test:** Use larger timeout values on JRuby to prevent flaky tests ([aa8fd8b](https://github.com/ruby-git/ruby-git/commit/aa8fd8b0435246f70579bfab3cde8d45bc23233a))
+
+
+### Other Changes
+
+* Add git version support policy ([fbb0c60](https://github.com/ruby-git/ruby-git/commit/fbb0c60c56a01222133b61eb5267148773b4239c))
+* **clone:** Simplify single_branch validator ([3900233](https://github.com/ruby-git/ruby-git/commit/39002330d42c4a2b3f0413ba920e6fd534880e03))
+* Expand AI instructions with comprehensive workflows ([04907ed](https://github.com/ruby-git/ruby-git/commit/04907edd89dd716d85f190d828cbf6a0c43d47f6))
+* Make env_overrides more flexible and idiomatic ([dc0b43b](https://github.com/ruby-git/ruby-git/commit/dc0b43bccbc9c57c445efc303a3e0f6a71cbd66f))
+
 ## [4.0.7](https://github.com/ruby-git/ruby-git/compare/v4.0.6...v4.0.7) (2025-12-29)
 
 

data/README.md

@@ -19,6 +19,7 @@
 - [Deprecations](#deprecations)
 - [Examples](#examples)
 - [Ruby version support policy](#ruby-version-support-policy)
+- [Git version support policy](#git-version-support-policy)
 - [License](#license)
 - [📢 Project Announcements 📢](#-project-announcements-)
   - [2025-07-09: Architectural Redesign](#2025-07-09-architectural-redesign)
@@ -33,9 +34,9 @@ command line.
 
 Get started by obtaining a repository object by:
 
-* opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
-* initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
-* cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
+- opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
+- initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
+- cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
 
 Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
 
@@ -223,6 +224,28 @@ end
 
 _NOTE: Another way to specify where is the `git` binary is through the environment variable `GIT_PATH`_
 
+**How SSH configuration is determined:**
+
+- If `git_ssh` is not specified in the API call, the global config (`Git.configure { |c| c.git_ssh = ... }`) is used.
+- If `git_ssh: nil` is specified, SSH is disabled for that instance (no SSH key or script will be used).
+- If `git_ssh` is a non-empty string, it is used for that instance (overriding the global config).
+
+You can also specify a custom SSH script on a per-repository basis:
+
+```ruby
+# Use a specific SSH key for a single repository
+git = Git.open('/path/to/repo', git_ssh: 'ssh -i /path/to/private_key')
+
+# Or when cloning
+git = Git.clone('git@github.com:user/repo.git', 'local-dir',
+                git_ssh: 'ssh -i /path/to/private_key')
+
+# Or when initializing
+git = Git.init('new-repo', git_ssh: 'ssh -i /path/to/private_key')
+```
+
+This is especially useful in multi-threaded applications where different repositories require different SSH credentials.
+
 Here are the operations that need read permission only.
 
 ```ruby
@@ -296,6 +319,7 @@ g.diff(commit1, commit2).stats
 g.diff(commit1, commit2).name_status
 g.gtree('v2.5').diff('v2.6').insertions
 g.diff('gitsearch1', 'v2.5').path('lib/')
+g.diff('gitsearch1', 'v2.5').path('lib/', 'docs/', 'README.md')  # multiple paths
 g.diff('gitsearch1', @git.gtree('v2.5'))
 g.diff('gitsearch1', 'v2.5').path('docs/').patch
 g.gtree('v2.5').diff('v2.6').patch
@@ -368,6 +392,9 @@ g.config('user.email', 'email@email.com')
 # Clone can take a filter to tell the serve to send a partial clone
 g = Git.clone(git_url, name, :path => path, :filter => 'tree:0')
 
+# Clone can control single-branch behavior (nil default keeps current git behavior)
+g = Git.clone(git_url, name, :path => path, :depth => 1, :single_branch => false)
+
 # Clone can take an optional logger
 logger = Logger.new
 g = Git.clone(git_url, NAME, :log => logger)
@@ -442,6 +469,9 @@ g.remote(name).remove
 g.remote(name).merge
 g.remote(name).merge(branch)
 
+g.remote_set_branches('origin', '*', add: true) # append additional fetch refspecs
+g.remote_set_branches('origin', 'feature', 'release/*') # replace fetch refspecs
+
 g.fetch
 g.fetch(g.remotes.first)
 g.fetch('origin', {:ref => 'some/ref/head'} )
@@ -536,6 +566,25 @@ once the following JRuby bug is fixed:
 
 jruby/jruby#7515
 
+## Git version support policy
+
+This gem requires git version 2.28.0 or greater as specified in the gemspec. This
+requirement reflects:
+
+- The minimum git version necessary to support all features provided by this gem
+- A reasonable balance between supporting older systems and leveraging modern git
+  capabilities
+- The practical limitations of testing across multiple git versions in CI
+
+Git 2.28.0 was released on July 27, 2020. While this gem may work with earlier
+versions of git, compatibility with versions prior to 2.28.0 is not tested or
+guaranteed. Users on older git versions should upgrade to at least 2.28.0.
+
+The supported git version may be increased in future major or minor releases of this
+gem as new git features are adopted or as maintaining backward compatibility becomes
+impractical. Such changes will be clearly documented in the CHANGELOG and release
+notes.
+
 ## License
 
 Licensed under MIT License Copyright (c) 2008  Scott Chacon. See LICENSE for further

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
 
@@ -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
@@ -541,6 +563,43 @@ module Git
       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')
@@ -812,18 +871,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