git 4.3.2 → 5.0.0.beta.1

data/lib/git/diff_stats.rb

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
 module Git
-  # Provides access to the statistics of a diff between two commits,
-  # including insertions, deletions, and file-level details.
+  # Lazy diff statistics for a comparison between two trees
+  #
+  # Supports comparing (1) two commits, (2) a commit against the working tree,
+  # or (3) the index against the working tree.
+  #
+  # @example Get the insertion and deletion counts
+  #   stats = repo.diff_stats
+  #   stats.insertions #=> 3
+  #   stats.deletions  #=> 1
+  #
+  # @api public
   class DiffStats
     # @private
     def initialize(base, from, to, path_limiter = nil)
@@ -15,45 +24,81 @@ module Git
       @from = from
       @to = to
       @path_limiter = path_limiter
-      @stats = nil
+      @fetch_stats = nil
     end
 
-    # Returns the total number of lines deleted.
+    # Returns the total number of lines deleted
+    #
+    # @example Get the deletion count
+    #   stats = repo.diff_stats
+    #   stats.deletions #=> 5
+    #
+    # @return [Integer] the total deletion count
     def deletions
       fetch_stats[:total][:deletions]
     end
 
-    # Returns the total number of lines inserted.
+    # Returns the total number of lines inserted
+    #
+    # @example Get the insertion count
+    #   stats = repo.diff_stats
+    #   stats.insertions #=> 3
+    #
+    # @return [Integer] the total insertion count
     def insertions
       fetch_stats[:total][:insertions]
     end
 
-    # Returns the total number of lines changed (insertions + deletions).
+    # Returns the total number of lines changed (insertions + deletions)
+    #
+    # @example Get the total changed-line count
+    #   stats = repo.diff_stats
+    #   stats.lines #=> 8
+    #
+    # @return [Integer] the total changed-line count
     def lines
       fetch_stats[:total][:lines]
     end
 
-    # Returns a hash of statistics for each file in the diff.
+    # Returns a hash of statistics for each file in the diff
+    #
+    # @example Get per-file statistics
+    #   stats = repo.diff_stats
+    #   stats.files #=> { "lib/foo.rb" => { insertions: 3, deletions: 1 } }
     #
-    # @return [Hash<String, {insertions: Integer, deletions: Integer}>]
+    # @return [Hash{String=>Hash{Symbol=>Integer}}]
+    #   per-file statistics keyed by file path
     def files
       fetch_stats[:files]
     end
 
-    # Returns a hash of the total statistics for the diff.
+    # Returns a hash of the total statistics for the diff
+    #
+    # @example Get total statistics
+    #   stats = repo.diff_stats
+    #   stats.total #=> { insertions: 3, deletions: 1, lines: 4, files: 1 }
     #
-    # @return [{insertions: Integer, deletions: Integer, lines: Integer, files: Integer}]
+    # @return [Hash{Symbol=>Integer}]
+    #   aggregate statistics for the entire diff
     def total
       fetch_stats[:total]
     end
 
     private
 
-    # Lazily fetches and caches the stats from the git lib.
+    # Lazily fetches and caches the stats from the git lib
+    #
+    # When `@base` implements `#diff_numstat`, delegates directly to that
+    # method. Otherwise falls back to the legacy `@base.lib.diff_stats` call
+    # so that existing `Git::Base`-backed callers continue to work unchanged.
+    #
+    # @return [Hash] the fetched stats hash
     def fetch_stats
-      @fetch_stats ||= @base.lib.diff_stats(
-        @from, @to, { path_limiter: @path_limiter }
-      )
+      @fetch_stats ||= if @base.respond_to?(:diff_numstat)
+                         @base.diff_numstat(@from, @to, path_limiter: @path_limiter)
+                       else
+                         @base.lib.diff_stats(@from, @to, { path_limiter: @path_limiter })
+                       end
     end
   end
 end

data/lib/git/dirstat_info.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object representing a single directory's contribution to a diff
+  #
+  # @api public
+  #
+  # @example
+  #   info = Git::DirstatEntry.new(directory: 'lib/commands/', percentage: 45.2)
+  #   info.directory   #=> "lib/commands/"
+  #   info.percentage  #=> 45.2
+  #
+  # @!attribute [r] directory
+  #   @return [String] the directory path (always ends with '/')
+  #
+  # @!attribute [r] percentage
+  #   @return [Float] the percentage of changes in this directory (0.0-100.0)
+  #
+  DirstatEntry = Data.define(:directory, :percentage)
+
+  # Immutable result object from git --dirstat output
+  #
+  # Contains the list of directories and their contribution percentages to the diff.
+  #
+  # @api public
+  #
+  # @example
+  #   dirstat = Git::DirstatInfo.new(
+  #     entries: [
+  #       Git::DirstatEntry.new(directory: 'lib/commands/', percentage: 45.2),
+  #       Git::DirstatEntry.new(directory: 'spec/unit/', percentage: 30.1)
+  #     ]
+  #   )
+  #   dirstat.entries.first.directory  #=> "lib/commands/"
+  #   dirstat['lib/commands/']         #=> 45.2
+  #   dirstat.to_h  #=> { "lib/commands/" => 45.2, "spec/unit/" => 30.1 }
+  #
+  # @!attribute [r] entries
+  #   @return [Array<DirstatEntry>] directory statistics in order from git output
+  #
+  DirstatInfo = Data.define(:entries) do
+    # Look up percentage by directory path
+    #
+    # @param directory [String] the directory path
+    # @return [Float, nil] the percentage or nil if not found
+    #
+    def [](directory)
+      entries.find { |e| e.directory == directory }&.percentage
+    end
+
+    # Convert to a Hash mapping directory to percentage
+    #
+    # @return [Hash<String, Float>]
+    #
+    def to_h
+      entries.to_h { |e| [e.directory, e.percentage] }
+    end
+
+    # Number of directories in the dirstat
+    #
+    # @return [Integer]
+    #
+    def size
+      entries.size
+    end
+
+    # Check if dirstat is empty
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      entries.empty?
+    end
+
+    # Iterate over entries
+    #
+    # @yield [DirstatEntry] each entry
+    # @return [Enumerator] if no block given
+    #
+    def each(&block)
+      entries.each(&block)
+    end
+
+    include Enumerable
+  end
+end

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,56 @@
+# 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')
+    #
+    # @api private
+    #
+    class Global < ExecutionContext
+      # Creates a new global execution context
+      #
+      # @example Create with default settings
+      #   Git::ExecutionContext::Global.new
+      #
+      # @example Create with an explicit binary path
+      #   Git::ExecutionContext::Global.new(binary_path: '/usr/local/bin/git2')
+      #
+      # @param binary_path [String, :use_global_config] path to the git binary
+      #
+      #   Give `:use_global_config` (the default) to use `Git::Base.config.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::Base.config.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(binary_path: :use_global_config, git_ssh: :use_global_config, logger: nil)
+        super
+      end
+    end
+  end
+end

data/lib/git/execution_context/repository.rb

@@ -0,0 +1,147 @@
+# 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
+    #
+    # Prefer the factory class methods over `new` when building from a
+    # {Git::Base} object or a hash:
+    #
+    #   context = Git::ExecutionContext::Repository.from_base(base)
+    #   context = Git::ExecutionContext::Repository.from_hash(repository: '/repo/.git', ...)
+    #
+    # @example Build from a Git::Base object
+    #   context = Git::ExecutionContext::Repository.from_base(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 {Git::Base} instance
+      #
+      # @example Build from a base object
+      #   git = Git.open('/path/to/repo')
+      #   context = Git::ExecutionContext::Repository.from_base(git)
+      #
+      # @param base_object [Git::Base] the base Git object to derive context from
+      #
+      # @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_base(base_object, logger: nil)
+        new(
+          git_dir: base_object.repo.to_s,
+          git_index_file: base_object.index&.to_s,
+          git_work_dir: base_object.dir&.to_s,
+          base_object: base_object,
+          git_ssh: base_object.git_ssh,
+          binary_path: base_object.binary_path,
+          logger: logger
+        )
+      end
+
+      # 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.key?(:git_ssh) ? base_hash[:git_ssh] : :use_global_config,
+          binary_path: base_hash.key?(:binary_path) ? base_hash[: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 base_object [Git::Base, nil] originating base object
+      #
+      # @param binary_path [String, :use_global_config] path to the git binary
+      #
+      #   Give `:use_global_config` (the default) to use `Git::Base.config.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::Base.config.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,
+        base_object: 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
+        @base_object = base_object
+      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
+
+      # @return [Git::Base, nil] originating base object
+      attr_reader :base_object
+    end
+  end
+end