git 1.19.1 → 5.5.0

data/lib/git/diff_file_patch_info.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative 'file_ref'
+
+module Git
+  # Immutable value object representing a single file's patch information
+  #
+  # DiffFilePatchInfo encapsulates the parsed data from a unified diff for one file,
+  # including source and destination file references, the patch text, change type,
+  # and line statistics.
+  #
+  #
+  # @example A modified file patch
+  #   patch_info = Git::DiffFilePatchInfo.new(
+  #     src: Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/foo.rb'),
+  #     dst: Git::FileRef.new(mode: '100644', sha: 'def5678', path: 'lib/foo.rb'),
+  #     patch: "diff --git a/lib/foo.rb b/lib/foo.rb\n...",
+  #     status: :modified,
+  #     similarity: nil,
+  #     binary: false,
+  #     insertions: 10,
+  #     deletions: 5
+  #   )
+  #
+  # @example A new file patch (src is nil)
+  #   patch_info = Git::DiffFilePatchInfo.new(
+  #     src: nil,
+  #     dst: Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/new.rb'),
+  #     patch: "diff --git a/lib/new.rb b/lib/new.rb\nnew file mode 100644\n...",
+  #     status: :added,
+  #     similarity: nil,
+  #     binary: false,
+  #     insertions: 20,
+  #     deletions: 0
+  #   )
+  #
+  # @!attribute [r] src
+  #   @return [FileRef, nil] the source file reference, or nil for new/added files
+  #
+  # @!attribute [r] dst
+  #   @return [FileRef, nil] the destination file reference, or nil for deleted files
+  #
+  # @!attribute [r] patch
+  #   @return [String] the full unified diff patch text for this file
+  #
+  # @!attribute [r] status
+  #   @return [Symbol] the change status (:added, :modified, :deleted, :renamed, :copied, :type_changed)
+  #
+  # @!attribute [r] similarity
+  #   @return [Integer, nil] similarity percentage for renames/copies (0-100), nil otherwise
+  #
+  # @!attribute [r] binary
+  #   @return [Boolean] whether this is a binary file
+  #
+  # @!attribute [r] insertions
+  #   @return [Integer] number of lines inserted
+  #
+  # @!attribute [r] deletions
+  #   @return [Integer] number of lines deleted
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  DiffFilePatchInfo = Data.define(
+    :src,
+    :dst,
+    :patch,
+    :status,
+    :similarity,
+    :binary,
+    :insertions,
+    :deletions
+  ) do
+    # Get the primary file path
+    #
+    # Returns the destination path if it exists, otherwise the source path.
+    # This is the "current" or "canonical" path for the file.
+    #
+    # @return [String] the file path
+    #
+    def path
+      dst&.path || src&.path
+    end
+
+    # Get the source file path
+    #
+    # Returns the source path if it exists. Useful for renames/copies to see
+    # where the file came from.
+    #
+    # @return [String, nil] the source file path, or nil if no source (added files)
+    #
+    def src_path
+      src&.path
+    end
+
+    # Check if this is a binary file
+    #
+    # @return [Boolean] true if the file is binary
+    #
+    def binary?
+      binary
+    end
+
+    # Check if this file was renamed
+    #
+    # @return [Boolean]
+    #
+    def renamed?
+      status == :renamed
+    end
+
+    # Check if this file was copied
+    #
+    # @return [Boolean]
+    #
+    def copied?
+      status == :copied
+    end
+
+    # Check if this file was added
+    #
+    # @return [Boolean]
+    #
+    def added?
+      status == :added
+    end
+
+    # Check if this file was deleted
+    #
+    # @return [Boolean]
+    #
+    def deleted?
+      status == :deleted
+    end
+  end
+end

data/lib/git/diff_file_raw_info.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative 'file_ref'
+
+module Git
+  # Immutable value object representing status info for a single file from git raw diff output
+  #
+  # Contains the source and destination file references, change status,
+  # similarity percentage (for renames/copies), and line change statistics.
+  #
+  #
+  # @example A modified file
+  #   info = Git::DiffFileRawInfo.new(
+  #     src: Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/foo.rb'),
+  #     dst: Git::FileRef.new(mode: '100644', sha: 'def5678', path: 'lib/foo.rb'),
+  #     status: :modified,
+  #     similarity: nil,
+  #     insertions: 5,
+  #     deletions: 2,
+  #     binary: false
+  #   )
+  #
+  # @example A new file (src is nil)
+  #   info = Git::DiffFileRawInfo.new(
+  #     src: nil,
+  #     dst: Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/new.rb'),
+  #     status: :added,
+  #     similarity: nil,
+  #     insertions: 10,
+  #     deletions: 0,
+  #     binary: false
+  #   )
+  #
+  # @example A renamed file
+  #   info = Git::DiffFileRawInfo.new(
+  #     src: Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/old.rb'),
+  #     dst: Git::FileRef.new(mode: '100644', sha: 'def5678', path: 'lib/new.rb'),
+  #     status: :renamed,
+  #     similarity: 95,
+  #     insertions: 2,
+  #     deletions: 1,
+  #     binary: false
+  #   )
+  #
+  # @!attribute [r] src
+  #   @return [FileRef, nil] the source file reference, or nil for new/added files
+  #
+  # @!attribute [r] dst
+  #   @return [FileRef, nil] the destination file reference, or nil for deleted files
+  #
+  # @!attribute [r] status
+  #   @return [Symbol] the change status (:added, :modified, :deleted, :renamed, :copied, :type_changed)
+  #
+  # @!attribute [r] similarity
+  #   @return [Integer, nil] similarity percentage for renames/copies (0-100), nil otherwise
+  #
+  # @!attribute [r] insertions
+  #   @return [Integer] number of lines inserted
+  #
+  # @!attribute [r] deletions
+  #   @return [Integer] number of lines deleted
+  #
+  # @!attribute [r] binary
+  #   @return [Boolean] whether this is a binary file
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  DiffFileRawInfo = Data.define(:src, :dst, :status, :similarity, :insertions, :deletions, :binary) do
+    # Get the primary file path
+    #
+    # Returns the destination path if it exists, otherwise the source path.
+    # This is the "current" or "canonical" path for the file.
+    #
+    # @return [String] the file path
+    #
+    def path
+      dst&.path || src&.path
+    end
+
+    # Get the source path (for renames/copies)
+    #
+    # @return [String, nil] the source path, or nil if file was added
+    #
+    def src_path
+      src&.path
+    end
+
+    # Check if this is a binary file
+    #
+    # @return [Boolean] true if the file is binary
+    #
+    def binary?
+      binary
+    end
+
+    # Check if this file was renamed
+    #
+    # @return [Boolean]
+    #
+    def renamed?
+      status == :renamed
+    end
+
+    # Check if this file was copied
+    #
+    # @return [Boolean]
+    #
+    def copied?
+      status == :copied
+    end
+
+    # Check if this file was added
+    #
+    # @return [Boolean]
+    #
+    def added?
+      status == :added
+    end
+
+    # Check if this file was deleted
+    #
+    # @return [Boolean]
+    #
+    def deleted?
+      status == :deleted
+    end
+  end
+end

data/lib/git/diff_info.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object representing a single file's diff information
+  #
+  # FileDiffInfo encapsulates the parsed data from a unified diff for one file,
+  # including the file path, patch text, mode changes, object identifiers, and type.
+  #
+  # This class is used by DiffInfo for the legacy diff API.
+  #
+  #
+  # @example Create a FileDiffInfo from parsed diff output
+  #   diff_info = Git::FileDiffInfo.new(
+  #     path: 'lib/example.rb',
+  #     patch: "diff --git a/lib/example.rb b/lib/example.rb\n...",
+  #     mode: '100644',
+  #     src: 'abc1234',
+  #     dst: 'def5678',
+  #     type: 'modified',
+  #     binary: false
+  #   )
+  #
+  # @!attribute [r] path
+  #   @return [String] the file path relative to the repository root
+  #
+  # @!attribute [r] patch
+  #   @return [String] the full unified diff patch text for this file
+  #
+  # @!attribute [r] mode
+  #   @return [String] the file mode (e.g., '100644' for regular files)
+  #
+  # @!attribute [r] src
+  #   @return [String] the source blob object identifier
+  #
+  # @!attribute [r] dst
+  #   @return [String] the destination blob object identifier
+  #
+  # @!attribute [r] type
+  #   @return [String] the type of change: 'modified', 'new', 'deleted', 'renamed'
+  #
+  # @!attribute [r] binary
+  #   @return [Boolean] whether this is a binary file
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  FileDiffInfo = Data.define(
+    :path,
+    :patch,
+    :mode,
+    :src,
+    :dst,
+    :type,
+    :binary
+  ) do
+    # Check if this is a binary file
+    #
+    # @return [Boolean] true if the file is binary
+    #
+    def binary?
+      binary
+    end
+  end
+
+  # Immutable value object representing diff statistics and optional file patches
+  #
+  # DiffInfo encapsulates the parsed output from various git commands that produce
+  # diff statistics (like `git stash show --stat`). When patches are requested,
+  # it also includes the full patch information for each file.
+  #
+  # The stats hash structure:
+  # - `:total` - Hash with `:insertions`, `:deletions`, `:lines`, `:files` keys
+  # - `:files` - Hash mapping file paths to `{ insertions:, deletions: }` hashes
+  #
+  # @example Create a DiffInfo from parsed stats output
+  #   info = Git::DiffInfo.new(
+  #     stats: {
+  #       total: { insertions: 10, deletions: 5, lines: 15, files: 2 },
+  #       files: {
+  #         'lib/foo.rb' => { insertions: 8, deletions: 3 },
+  #         'lib/bar.rb' => { insertions: 2, deletions: 2 }
+  #       }
+  #     },
+  #     file_patches: []
+  #   )
+  #
+  # @example Access statistics
+  #   info.insertions  # => 10
+  #   info.deletions   # => 5
+  #   info.lines       # => 15
+  #   info.file_count  # => 2
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  #
+  # @!attribute [r] stats
+  #   @return [Hash] the statistics hash with :total and :files keys
+  #
+  # @!attribute [r] file_patches
+  #   @return [Array<FileDiffInfo>] array of file diff info objects (empty if patch not requested)
+  #
+  DiffInfo = Data.define(:stats, :file_patches) do
+    # Total number of lines inserted
+    #
+    # @return [Integer]
+    #
+    def insertions
+      stats[:total][:insertions]
+    end
+
+    # Total number of lines deleted
+    #
+    # @return [Integer]
+    #
+    def deletions
+      stats[:total][:deletions]
+    end
+
+    # Total number of lines changed (insertions + deletions)
+    #
+    # @return [Integer]
+    #
+    def lines
+      stats[:total][:lines]
+    end
+
+    # Number of files changed
+    #
+    # @return [Integer]
+    #
+    def file_count
+      stats[:total][:files]
+    end
+
+    # Per-file statistics hash
+    #
+    # @return [Hash<String, Hash>] mapping file paths to `{ insertions:, deletions: }` hashes
+    #
+    def file_stats
+      stats[:files]
+    end
+
+    # Check if patch information is available
+    #
+    # @return [Boolean] true if file_patches were loaded
+    #
+    def patches?
+      !file_patches.empty?
+    end
+
+    # Get patch info for a specific file
+    #
+    # @param path [String] the file path
+    #
+    # @return [FileDiffInfo, nil] the diff info or nil if not found
+    #
+    def patch_for(path)
+      file_patches.find { |p| p.path == path }
+    end
+  end
+end

data/lib/git/diff_path_status.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Git
+  # The files and their status (e.g., added, modified, deleted) between two commits
+  #
+  # @example Iterate over path statuses
+  #   git = Git.open('/path/to/repo')
+  #   git.diff_path_status.each { |path, status| puts "#{path}: #{status}" }
+  #
+  # @api public
+  #
+  class DiffPathStatus
+    include Enumerable
+
+    # @private
+    #
+    # @param base_or_hash [Git::Repository, Hash{String => String}] either a
+    #   repository object for legacy initialization or a pre-fetched name-status hash
+    #
+    # @param from [String, nil] the first commit/object to compare when using
+    #   legacy initialization
+    #
+    # @param to [String, nil] the second commit/object to compare when using
+    #   legacy initialization
+    #
+    # @param path_limiter [String, Pathname, Array, nil] path(s) to limit the
+    #   diff when using legacy initialization
+    #
+    def initialize(base_or_hash, from = nil, to = nil, path_limiter = nil)
+      if base_or_hash.is_a?(Hash)
+        # New form: pre-fetched hash passed directly from Git::Repository::Diffing
+        @fetch_path_status = base_or_hash
+      else
+        # Legacy form: (base, from, to, path_limiter)
+        # Used by Git::Diff#path_status_provider and direct instantiation in tests.
+        initialize_legacy(base_or_hash, from, to, path_limiter)
+      end
+    end
+
+    # Iterates over each file path and its status code
+    #
+    # @example Print each path and status
+    #   diff_path_status.each { |path, status| puts "#{path}: #{status}" }
+    #
+    # @return [Enumerator, Hash{String => String}] an `Enumerator` when no block
+    #   is given; the name-status hash when a block is given
+    #
+    # @yield [path, status] each file path with its git status code
+    #
+    # @yieldparam path [String] the file path relative to the repository root
+    #
+    # @yieldparam status [String] the git status code (e.g. `"M"`, `"A"`, `"D"`)
+    #
+    # @yieldreturn [void]
+    #
+    def each(&)
+      return to_enum(__method__) unless block_given?
+
+      fetch_path_status.each(&)
+    end
+
+    # Returns the name-status report as a hash
+    #
+    # @example Basic usage
+    #   diff_path_status.to_h #=> { "README.md" => "M", "lib/foo.rb" => "A" }
+    #
+    # @return [Hash{String => String}] a mapping of file paths to their status codes
+    #
+    def to_h
+      fetch_path_status
+    end
+
+    private
+
+    # Lazily fetches and caches the path status from the git lib
+    #
+    # @return [Hash{String => String}] a mapping of file paths to status codes
+    #
+    def fetch_path_status
+      @fetch_path_status ||= @base.diff_name_status(@from, @to, path_limiter: @path_limiter).to_h
+    end
+
+    # Sets up legacy (base, from, to, path_limiter) instance state
+    #
+    # @param base [Git::Repository] the git object
+    #
+    # @param from [String] the first commit or object to compare
+    #
+    # @param to [String, nil] the second commit or object to compare
+    #
+    # @param path_limiter [String, Pathname, Array, nil] path(s) to limit the diff
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] when `from` or `to` starts with `"-"`
+    #
+    def initialize_legacy(base, from, to, path_limiter)
+      [from, to].compact.each do |arg|
+        raise ArgumentError, "Invalid argument: '#{arg}'" if arg.start_with?('-')
+      end
+      @base = base
+      @from = from
+      @to = to
+      @path_limiter = path_limiter
+    end
+  end
+end

data/lib/git/diff_result.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'dirstat_info'
+
+module Git
+  # Immutable result object from git diff commands
+  #
+  # Contains summary statistics and per-file information from various diff formats.
+  # The `files` array contains one of:
+  # - DiffFileNumstatInfo (from --numstat)
+  # - DiffFileRawInfo (from --raw)
+  # - DiffFilePatchInfo (from --patch)
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  #
+  # @!attribute [r] files_changed
+  #   @return [Integer] number of files changed (from --shortstat)
+  #
+  # @!attribute [r] total_insertions
+  #   @return [Integer] total lines inserted across all files (from --shortstat)
+  #
+  # @!attribute [r] total_deletions
+  #   @return [Integer] total lines deleted across all files (from --shortstat)
+  #
+  # @!attribute [r] files
+  #   @return [Array<DiffFileNumstatInfo, DiffFileRawInfo, DiffFilePatchInfo>] per-file information
+  #
+  # @!attribute [r] dirstat
+  #   @return [DirstatInfo, nil] directory statistics if requested, nil otherwise
+  #
+  DiffResult = Data.define(:files_changed, :total_insertions, :total_deletions, :files, :dirstat)
+end

data/lib/git/diff_stats.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Git
+  # 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
+    # Initializes diff-stats state for a tree comparison.
+    #
+    # @private
+    #
+    # @param base [Git::Repository] the git object used to fetch diff stats
+    #
+    # @param from [String] the first commit or object to compare
+    #
+    # @param to [String, nil] the second commit or object to compare
+    #
+    # @param path_limiter [String, Pathname, Array<String, Pathname>, nil]
+    #   path(s) to limit the diff
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] when `from` or `to` starts with `"-"`
+    def initialize(base, from, to, path_limiter = nil)
+      # Eagerly check for invalid arguments
+      [from, to].compact.each do |arg|
+        raise ArgumentError, "Invalid argument: '#{arg}'" if arg.start_with?('-')
+      end
+
+      @base = base
+      @from = from
+      @to = to
+      @path_limiter = path_limiter
+      @fetch_stats = nil
+    end
+
+    # 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
+    #
+    # @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)
+    #
+    # @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
+    #
+    # @example Get per-file statistics
+    #   stats = repo.diff_stats
+    #   stats.files #=> { "lib/foo.rb" => { insertions: 3, deletions: 1 } }
+    #
+    # @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
+    #
+    # @example Get total statistics
+    #   stats = repo.diff_stats
+    #   stats.total #=> { insertions: 3, deletions: 1, lines: 4, files: 1 }
+    #
+    # @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
+    #
+    # @return [Hash] the fetched stats hash
+    def fetch_stats
+      @fetch_stats ||= @base.diff_numstat(@from, @to, path_limiter: @path_limiter)
+    end
+  end
+end