git 4.3.2 → 5.0.0.beta.2

data/lib/git/errors.rb

@@ -21,7 +21,8 @@ module Git
   #     │   └─> Git::SignaledError
   #     │       └─> Git::TimeoutError
   #     ├─> Git::ProcessIOError
-  #     └─> Git::UnexpectedResultError
+  #     ├─> Git::UnexpectedResultError
+  #     └─> Git::VersionError
   # ```
   #
   # | Error Class | Description |
@@ -33,6 +34,7 @@ module Git
   # | `TimeoutError` | This is a specific type of `SignaledError` that is raised when the git command line operation times out and is killed via the SIGKILL signal. This happens if the operation takes longer than the timeout duration configured in `Git.config.timeout` or via the `:timeout` parameter given in git methods that support timeouts. |
   # | `ProcessIOError` | An error was encountered reading or writing to a subprocess. |
   # | `UnexpectedResultError` | The command line ran without error but did not return the expected results. |
+  # | `VersionError` | The installed git version does not meet the requirements of the git gem or a specific command. |
   #
   # @example Rescuing a generic error
   #   begin
@@ -57,6 +59,7 @@ module Git
   # @see Git::TimeoutError
   # @see Git::ProcessIOError
   # @see Git::UnexpectedResultError
+  # @see Git::VersionError
   #
   # @api public
   #
@@ -146,7 +149,7 @@ module Git
   # The git command executed, status, stdout, and stderr, and the timeout duration
   # are available from this object.
   #
-  # result.status.timeout? will be `true`
+  # result.status.timed_out? will be `true`
   #
   # @api public
   #
@@ -209,4 +212,64 @@ module Git
   # @api public
   #
   class UnexpectedResultError < Git::Error; end
+
+  # Raised when the installed git version does not meet requirements
+  #
+  # This error is raised when:
+  # - The installed git version is below `Git::MINIMUM_GIT_VERSION`
+  # - A command requires a minimum git version that isn't met
+  # - A command was removed in a git version older than the installed version
+  #
+  # @example Rescuing a version error
+  #   begin
+  #     git.some_command
+  #   rescue Git::VersionError => e
+  #     puts "Git version #{e.actual_version} does not meet requirements"
+  #     puts "  #{e.subject}: requires #{e.constraint}"
+  #   end
+  #
+  # @api public
+  #
+  class VersionError < Git::Error
+    # Create a VersionError
+    #
+    # @param subject [#to_s] the entity with the version requirement (e.g., "The git gem", a Class)
+    # @param constraint [Git::VersionConstraint] the version constraint that was violated
+    # @param actual_version [Git::Version] the installed git version
+    #
+    def initialize(subject:, constraint:, actual_version:)
+      @subject = subject
+      @constraint = constraint
+      @actual_version = actual_version
+      super(build_message)
+    end
+
+    # The entity that has the version requirement
+    #
+    # @return [#to_s]
+    #
+    attr_reader :subject
+
+    # The version constraint that was violated
+    #
+    # @return [Git::VersionConstraint]
+    #
+    attr_reader :constraint
+
+    # The installed git version that caused the error
+    #
+    # @return [Git::Version]
+    #
+    attr_reader :actual_version
+
+    private
+
+    def build_message
+      if constraint.too_new?(actual_version)
+        "#{subject} requires git < #{constraint.before} (found #{actual_version})"
+      else
+        "#{subject} requires git >= #{constraint.min} (found #{actual_version})"
+      end
+    end
+  end
 end

data/lib/git/execution_context/global.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'git/execution_context'
+
+module Git
+  class ExecutionContext
+    # Execution context for global git commands (no repository required)
+    #
+    # Used for commands that do not require an existing repository — such as
+    # `git init`, `git clone`, and `git version`. Unlike
+    # {Git::ExecutionContext::Repository}, this class leaves `GIT_DIR`,
+    # `GIT_WORK_TREE`, and `GIT_INDEX_FILE` as `nil` (which unsets them), so
+    # that the parent environment cannot leak an unintended repository context.
+    # `GIT_SSH` is still supported to allow SSH-based remote operations
+    # (e.g. `git clone git@github.com:...`).
+    #
+    # @example Create a context using the default git binary
+    #   context = Git::ExecutionContext::Global.new
+    #
+    # @example Create a context targeting a specific binary
+    #   context = Git::ExecutionContext::Global.new(binary_path: '/usr/local/bin/git2')
+    #
+    # @see Git::ExecutionContext#initialize for constructor parameters and
+    #   their semantics
+    #
+    # @api private
+    #
+    class Global < ExecutionContext
+    end
+  end
+end

data/lib/git/execution_context/repository.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'git/execution_context'
+
+module Git
+  class ExecutionContext
+    # Execution context for repository-bound git commands
+    #
+    # Manages the git environment for commands that operate within an existing
+    # repository — setting `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, and
+    # `GIT_SSH` — and prepending `--git-dir` / `--work-tree` to every git
+    # invocation via {#global_opts}.
+    #
+    # ### Construction
+    #
+    # Use {.from_hash} to build from a configuration hash:
+    #
+    #   context = Git::ExecutionContext::Repository.from_hash(repository: '/repo/.git', ...)
+    #
+    # @example Build from a configuration hash
+    #   context = Git::ExecutionContext::Repository.from_hash(
+    #     repository: '/path/to/.git',
+    #     working_directory: '/path/to'
+    #   )
+    #
+    # @api private
+    #
+    class Repository < ExecutionContext
+      # Creates a Repository context from a Hash
+      #
+      # Expected keys: `:repository`, `:working_directory`, `:index`, `:git_ssh`,
+      # `:binary_path`
+      #
+      # @example Build from a configuration hash
+      #   context = Git::ExecutionContext::Repository.from_hash(
+      #     repository: '/path/to/.git',
+      #     working_directory: '/path/to'
+      #   )
+      #
+      # @param base_hash [Hash] the hash of repository configuration values
+      #
+      # @param logger [Logger, nil] logger forwarded to the CommandLine layer;
+      #   `nil` uses a null logger (see {Git::ExecutionContext#initialize})
+      #
+      # @return [Git::ExecutionContext::Repository] the new repository context
+      #
+      def self.from_hash(base_hash, logger: nil)
+        new(
+          git_dir: base_hash[:repository],
+          git_index_file: base_hash[:index],
+          git_work_dir: base_hash[:working_directory],
+          git_ssh: base_hash.fetch(:git_ssh, :use_global_config),
+          binary_path: base_hash.fetch(:binary_path, :use_global_config),
+          logger: logger
+        )
+      end
+
+      # Creates a new repository execution context
+      #
+      # @example Create with required git_dir
+      #   Git::ExecutionContext::Repository.new(git_dir: '/path/to/.git')
+      #
+      # @param git_dir [String, nil] path to the `.git` directory
+      #
+      # @param git_work_dir [String, nil] path to the working tree
+      #
+      # @param git_index_file [String, nil] path to the index file
+      #
+      # @param binary_path [String, :use_global_config] path to the git binary
+      #
+      #   Give `:use_global_config` (the default) to use
+      #   `Git::Config.instance.binary_path`.
+      #
+      #   Passing `nil` raises `ArgumentError` — there is no "unset the
+      #   binary" semantic.
+      #
+      # @param git_ssh [String, nil, :use_global_config] the SSH wrapper path
+      #
+      #   Give `nil` to unset `GIT_SSH`, or `:use_global_config` (default)
+      #   to use `Git::Config.instance.git_ssh`.
+      #
+      # @param logger [Logger, nil] the logger to use in the CommandLine layer
+      #
+      #   Give `nil` to use a null logger (`Logger.new(nil)`).
+      #
+      # @raise [ArgumentError] if `binary_path` is `nil`
+      #
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        git_dir:,
+        git_work_dir: nil,
+        git_index_file: nil,
+        binary_path: :use_global_config,
+        git_ssh: :use_global_config,
+        logger: nil
+      )
+        super(binary_path: binary_path, git_ssh: git_ssh, logger: logger)
+        @git_dir = git_dir
+        @git_work_dir = git_work_dir
+        @git_index_file = git_index_file
+      end
+
+      # @return [String, nil] path to the `.git` directory
+      attr_reader :git_dir
+
+      # @return [String, nil] path to the working tree
+      attr_reader :git_work_dir
+
+      # @return [String, nil] path to the index file
+      attr_reader :git_index_file
+
+      # Returns a new instance with the same configuration, applying `overrides`
+      #
+      # Uses raw stored values for `binary_path`, `git_ssh`, and `logger` so
+      # that `:use_global_config` sentinels are preserved across rebuilds and
+      # future changes to `Git.configure` continue to take effect.
+      #
+      # @param overrides [Hash] keyword arguments to override in the new instance
+      #
+      # @return [Git::ExecutionContext::Repository] the new context
+      #
+      # @api private
+      #
+      def dup_with(**overrides)
+        self.class.new(
+          git_dir: @git_dir,
+          git_work_dir: @git_work_dir,
+          git_index_file: @git_index_file,
+          binary_path: @binary_path,
+          git_ssh: @git_ssh,
+          logger: @logger,
+          **overrides
+        )
+      end
+    end
+  end
+end