git 4.0.7 → 4.1.0

data/lib/git/lib.rb

@@ -5,6 +5,7 @@ require_relative 'args_builder'
 require 'git/command_line'
 require 'git/errors'
 require 'logger'
+require 'pathname'
 require 'pp'
 require 'process_executer'
 require 'stringio'
@@ -64,6 +65,7 @@ module Git
     #
     def initialize(base = nil, logger = nil)
       @logger = logger || Logger.new(nil)
+      @git_ssh = :use_global_config
 
       case base
       when Git::Base
@@ -98,6 +100,21 @@ module Git
       { keys: [:filter],    flag: '--filter',    type: :valued_space },
       { keys: %i[remote origin], flag: '--origin', type: :valued_space },
       { keys: [:config], flag: '--config', type: :repeatable_valued_space },
+      {
+        keys: [:single_branch],
+        type: :custom,
+        validator: ->(value) { [nil, true, false].include?(value) },
+        builder: lambda do |value|
+          case value
+          when true
+            ['--single-branch']
+          when false
+            ['--no-single-branch']
+          else
+            []
+          end
+        end
+      },
       {
         keys: [:depth],
         type: :custom,
@@ -255,7 +272,8 @@ module Git
     #
     #   Only :between or :object options can be used, not both.
     #
-    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    # @option opts :path_limiter [String, Pathname, Array<String, Pathname>] only
+    #   include commits that impact files from the specified paths
     #
     # @return [Array<String>] the log output
     #
@@ -310,7 +328,7 @@ module Git
     #
     #   Only :between or :object options can be used, not both.
     #
-    # @option opts :path_limiter [Array<String>, String] only include commits that
+    # @option opts :path_limiter [String, Pathname, Array<String, Pathname>] only include commits that
     #   impact files from the specified paths
     #
     # @option opts :skip [Integer]
@@ -719,17 +737,17 @@ module Git
     end
 
     def worktree_add(dir, commitish = nil)
-      return command('worktree', 'add', dir, commitish) unless commitish.nil?
+      return worktree_command('worktree', 'add', dir, commitish) unless commitish.nil?
 
-      command('worktree', 'add', dir)
+      worktree_command('worktree', 'add', dir)
     end
 
     def worktree_remove(dir)
-      command('worktree', 'remove', dir)
+      worktree_command('worktree', 'remove', dir)
     end
 
     def worktree_prune
-      command('worktree', 'prune')
+      worktree_command('worktree', 'prune')
     end
 
     def list_files(ref_dir)
@@ -824,6 +842,53 @@ module Git
       raise ArgumentError, "Invalid #{arg_name}: '#{invalid_args.join("', '")}'"
     end
 
+    # Normalizes path specifications for Git commands
+    #
+    # Converts a single path or array of paths into a consistent array format
+    # suitable for appending to Git command arguments after '--'. Empty strings
+    # are filtered out after conversion.
+    #
+    # @param pathspecs [String, Pathname, Array<String, Pathname>, nil] path(s) to normalize
+    # @param arg_name [String] name of the argument for error messages
+    # @return [Array<String>, nil] normalized array of path strings, or nil if empty/nil input
+    # @raise [ArgumentError] if any path is not a String or Pathname
+    #
+    def normalize_pathspecs(pathspecs, arg_name)
+      return nil unless pathspecs
+
+      normalized = Array(pathspecs)
+      validate_pathspec_types(normalized, arg_name)
+
+      normalized = normalized.map(&:to_s).reject(&:empty?)
+      return nil if normalized.empty?
+
+      normalized
+    end
+
+    # Validates that all pathspecs are String or Pathname objects
+    #
+    # @param pathspecs [Array] the pathspecs to validate
+    # @param arg_name [String] name of the argument for error messages
+    # @raise [ArgumentError] if any path is not a String or Pathname
+    #
+    def validate_pathspec_types(pathspecs, arg_name)
+      return if pathspecs.all? { |path| path.is_a?(String) || path.is_a?(Pathname) }
+
+      raise ArgumentError, "Invalid #{arg_name}: must be a String, Pathname, or Array of Strings/Pathnames"
+    end
+
+    # Handle deprecated :path option in favor of :path_limiter
+    def handle_deprecated_path_option(opts)
+      if opts.key?(:path_limiter)
+        opts[:path_limiter]
+      elsif opts.key?(:path)
+        Git::Deprecation.warn(
+          'Git::Lib#diff_path_status :path option is deprecated. Use :path_limiter instead.'
+        )
+        opts[:path]
+      end
+    end
+
     DIFF_FULL_OPTION_MAP = [
       { type: :static, flag: '-p' },
       { keys: [:path_limiter], type: :validate_only }
@@ -836,8 +901,8 @@ module Git
       args = build_args(opts, DIFF_FULL_OPTION_MAP)
       args.push(obj1, obj2).compact!
 
-      if (path = opts[:path_limiter]) && path.is_a?(String)
-        args.push('--', path)
+      if (pathspecs = normalize_pathspecs(opts[:path_limiter], 'path limiter'))
+        args.push('--', *pathspecs)
       end
 
       command('diff', *args)
@@ -855,8 +920,8 @@ module Git
       args = build_args(opts, DIFF_STATS_OPTION_MAP)
       args.push(obj1, obj2).compact!
 
-      if (path = opts[:path_limiter]) && path.is_a?(String)
-        args.push('--', path)
+      if (pathspecs = normalize_pathspecs(opts[:path_limiter], 'path limiter'))
+        args.push('--', *pathspecs)
       end
 
       output_lines = command_lines('diff', *args)
@@ -865,6 +930,7 @@ module Git
 
     DIFF_PATH_STATUS_OPTION_MAP = [
       { type: :static, flag: '--name-status' },
+      { keys: [:path_limiter], type: :validate_only },
       { keys: [:path], type: :validate_only }
     ].freeze
 
@@ -874,7 +940,11 @@ module Git
 
       args = build_args(opts, DIFF_PATH_STATUS_OPTION_MAP)
       args.push(reference1, reference2).compact!
-      args.push('--', opts[:path]) if opts[:path]
+
+      path_limiter = handle_deprecated_path_option(opts)
+      if (pathspecs = normalize_pathspecs(path_limiter, 'path limiter'))
+        args.push('--', *pathspecs)
+      end
 
       parse_diff_path_status(args)
     end
@@ -1319,6 +1389,20 @@ module Git
       command('remote', *command_args)
     end
 
+    REMOTE_SET_BRANCHES_OPTION_MAP = [
+      { keys: [:add], flag: '--add', type: :boolean }
+    ].freeze
+
+    def remote_set_branches(name, branches, opts = {})
+      ArgsBuilder.validate!(opts, REMOTE_SET_BRANCHES_OPTION_MAP)
+
+      flags = build_args(opts, REMOTE_SET_BRANCHES_OPTION_MAP)
+      branch_args = Array(branches).flatten
+      command_args = ['set-branches'] + flags + [name] + branch_args
+
+      command('remote', *command_args)
+    end
+
     def remote_set_url(name, url)
       arr_opts = ['set-url']
       arr_opts << name
@@ -1628,12 +1712,14 @@ module Git
       @git_dir = base_object.repo.path
       @git_index_file = base_object.index&.path
       @git_work_dir = base_object.dir&.path
+      @git_ssh = base_object.git_ssh
     end
 
     def initialize_from_hash(base_hash)
       @git_dir = base_hash[:repository]
       @git_index_file = base_hash[:index]
       @git_work_dir = base_hash[:working_directory]
+      @git_ssh = base_hash.key?(:git_ssh) ? base_hash[:git_ssh] : :use_global_config
     end
 
     def return_base_opts_from_clone(clone_dir, opts)
@@ -1641,6 +1727,7 @@ module Git
       base_opts[:repository] = clone_dir if opts[:bare] || opts[:mirror]
       base_opts[:working_directory] = clone_dir unless opts[:bare] || opts[:mirror]
       base_opts[:log] = opts[:log] if opts[:log]
+      base_opts[:git_ssh] = opts[:git_ssh] if opts.key?(:git_ssh)
       base_opts
     end
 
@@ -1883,14 +1970,63 @@ module Git
       op.split("\n")
     end
 
-    def env_overrides
+    # Returns a hash of environment variable overrides for git commands
+    #
+    # This method builds a hash of environment variables that control git's behavior,
+    # such as the git directory, working tree, and index file locations.
+    #
+    # @param additional_overrides [Hash] additional environment variables to set or unset
+    #
+    #   Keys should be environment variable names (String) and values should be either:
+    #   * A String value to set the environment variable
+    #   * `nil` to unset the environment variable
+    #
+    #   Per Process.spawn semantics, setting a key to `nil` will unset that environment
+    #   variable, removing it from the environment passed to the git command.
+    #
+    # @return [Hash<String, String|nil>] environment variable overrides
+    #
+    # @example Basic usage with default environment variables
+    #   env_overrides
+    #   # => { 'GIT_DIR' => '/path/to/.git', 'GIT_WORK_TREE' => '/path/to/worktree', ... }
+    #
+    # @example Adding a custom environment variable
+    #   env_overrides('GIT_TRACE' => '1')
+    #   # => { 'GIT_DIR' => '/path/to/.git', ..., 'GIT_TRACE' => '1' }
+    #
+    # @example Unsetting an environment variable (used by worktree_command_line)
+    #   env_overrides('GIT_INDEX_FILE' => nil)
+    #   # => { 'GIT_DIR' => '/path/to/.git', 'GIT_WORK_TREE' => '/path/to/worktree',
+    #   #      'GIT_INDEX_FILE' => nil, 'GIT_SSH' => <git_ssh_value>, 'LC_ALL' => 'en_US.UTF-8' }
+    #   # When passed to Process.spawn, GIT_INDEX_FILE will be unset in the environment
+    #
+    # @see https://ruby-doc.org/core/Process.html#method-c-spawn Process.spawn
+    #
+    # @api private
+    #
+    def env_overrides(**additional_overrides)
       {
         'GIT_DIR' => @git_dir,
         'GIT_WORK_TREE' => @git_work_dir,
         'GIT_INDEX_FILE' => @git_index_file,
-        'GIT_SSH' => Git::Base.config.git_ssh,
+        'GIT_SSH' => resolved_git_ssh,
         'LC_ALL' => 'en_US.UTF-8'
-      }
+      }.merge(additional_overrides)
+    end
+
+    # Resolve the git_ssh value to use for this instance
+    #
+    # @return [String, nil] the resolved git_ssh value
+    #
+    #   Returns the global config value if @git_ssh is the sentinel :use_global_config,
+    #   otherwise returns @git_ssh (which may be nil or a string)
+    #
+    # @api private
+    #
+    def resolved_git_ssh
+      return Git::Base.config.git_ssh if @git_ssh == :use_global_config
+
+      @git_ssh
     end
 
     def global_opts
@@ -1906,6 +2042,46 @@ module Git
         Git::CommandLine.new(env_overrides, Git::Base.config.binary_path, global_opts, @logger)
     end
 
+    # Returns a command line instance without GIT_INDEX_FILE for worktree commands
+    #
+    # Git worktrees manage their own index files and setting GIT_INDEX_FILE
+    # causes corruption of both the main worktree and new worktree indexes.
+    #
+    # @return [Git::CommandLine]
+    # @api private
+    #
+    def worktree_command_line
+      @worktree_command_line ||=
+        Git::CommandLine.new(env_overrides('GIT_INDEX_FILE' => nil), Git::Base.config.binary_path, global_opts,
+                             @logger)
+    end
+
+    # @overload worktree_command(*args, **options_hash)
+    #   Runs a git worktree command and returns the output
+    #
+    #   This method is similar to #command but uses a command line instance
+    #   that excludes GIT_INDEX_FILE from the environment to prevent index corruption.
+    #
+    #   @param args [Array<String>] the command arguments
+    #   @param options_hash [Hash] the options to pass to the command
+    #
+    #   @return [String] the command's stdout
+    #
+    # @see #command
+    #
+    # @api private
+    #
+    def worktree_command(*, **options_hash)
+      options_hash = COMMAND_ARG_DEFAULTS.merge(options_hash)
+      options_hash[:timeout] ||= Git.config.timeout
+
+      extra_options = options_hash.keys - COMMAND_ARG_DEFAULTS.keys
+      raise ArgumentError, "Unknown options: #{extra_options.join(', ')}" if extra_options.any?
+
+      result = worktree_command_line.run(*, **options_hash)
+      result.stdout
+    end
+
     # Runs a git command and returns the output
     #
     # Additional args are passed to the command line. They should exclude the 'git'

data/lib/git/version.rb

@@ -3,5 +3,5 @@
 module Git
   # The current gem version
   # @return [String] the current gem version.
-  VERSION = '4.0.7'
+  VERSION = '4.1.0'
 end

data/lib/git.rb

@@ -93,6 +93,12 @@ module Git
   # @param [Hash] options The options for this command (see list of valid
   #   options below)
   #
+  # @option options [String, nil] :git_ssh An optional custom SSH command
+  #
+  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
+  #   - If nil, disables SSH for this instance.
+  #   - If a non-empty string, uses that value for this instance.
+  #
   # @option options [Logger] :log A logger to use for Git operations.  Git commands
   #   are logged at the `:info` level.  Additional logging is done at the `:debug`
   #   level.
@@ -145,6 +151,20 @@ module Git
   # @option options [String] :filter Request that the server send a partial
   #   clone according to the given filter
   #
+  # @option options [Boolean, nil] :single_branch Control whether the clone
+  #   limits fetch refspecs to a single branch.
+  #   - If nil (default), no flag is passed and the Git default is used.
+  #   - If true, `--single-branch` is passed to limit the refspec to the
+  #     checkout branch.
+  #   - If false, `--no-single-branch` is passed to broaden the refspec (useful
+  #     for shallow clones that should include all branches).
+  #
+  # @option options [String, nil] :git_ssh An optional custom SSH command
+  #
+  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
+  #   - If nil, disables SSH for this instance.
+  #   - If a non-empty string, uses that value for this instance.
+  #
   # @option options [Logger] :log A logger to use for Git operations.  Git
   #   commands are logged at the `:info` level.  Additional logging is done
   #   at the `:debug` level.
@@ -187,6 +207,13 @@ module Git
   #     config: ['user.name=John Doe', 'user.email=john@doe.com']
   #   )
   #
+  # @example Clone using a specific SSH key
+  #   git = Git.clone(
+  #     'git@github.com:ruby-git/ruby-git.git',
+  #     'local-dir',
+  #     git_ssh: 'ssh -i /path/to/private_key'
+  #   )
+  #
   # @return [Git::Base] an object that can execute git commands in the context
   #   of the cloned local working copy or cloned repository.
   #
@@ -300,6 +327,12 @@ module Git
   #   and converted to an absolute path using
   #   [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
   #
+  # @option options [String, nil] :git_ssh An optional custom SSH command
+  #
+  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
+  #   - If nil, disables SSH for this instance.
+  #   - If a non-empty string, uses that value for this instance.
+  #
   # @option options [Logger] :log A logger to use for Git operations.  Git
   #   commands are logged at the `:info` level.  Additional logging is done
   #   at the `:debug` level.
@@ -374,6 +407,12 @@ module Git
   # @option options [Pathname] :index used to specify a non-standard path to an
   #   index file.  The default is `"#{working_dir}/.git/index"`
   #
+  # @option options [String, nil] :git_ssh An optional custom SSH command
+  #
+  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
+  #   - If nil, disables SSH for this instance.
+  #   - If a non-empty string, uses that value for this instance.
+  #
   # @option options [Logger] :log A logger to use for Git operations.  Git
   #   commands are logged at the `:info` level.  Additional logging is done
   #   at the `:debug` level.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 4.0.7
+  version: 4.1.0
 platform: ruby
 authors:
 - Scott Chacon and others
@@ -305,8 +305,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/4.0.7/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/4.0.7
+  changelog_uri: https://rubydoc.info/gems/git/4.1.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/4.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: