git 4.4.0 → 5.0.0.beta.1

data/lib/git/status.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# These would be required by the main `git.rb` file
+
 module Git
   # The Status class gets the status of a git repository. It identifies which
   # files have been modified, added, or deleted, including untracked files.
@@ -10,37 +12,112 @@ module Git
   class Status
     include Enumerable
 
-    # @param base [Git::Base] The base git object
+    # Create a new Status for the given repository
+    #
+    # @param base [Git::Base, Git::Repository] the git object backing this status
+    #
     def initialize(base)
       @base = base
       # The factory returns a hash of file paths to StatusFile objects.
       @files = StatusFileFactory.new(base).construct_files
     end
 
-    # File status collections, memoized for performance.
+    # Return files modified in the index and/or working tree
+    #
+    # Includes both staged modifications (index vs HEAD) and unstaged modifications
+    # (working tree vs index).
+    #
+    # @return [Hash{String => Git::Status::StatusFile}] changed files keyed by path
+    #
     def changed   = @changed ||= select_files { |f| f.type == 'M' }
+
+    # Return files added to the index that are not yet in HEAD
+    #
+    # @return [Hash{String => Git::Status::StatusFile}] added files keyed by path
+    #
     def added     = @added ||= select_files { |f| f.type == 'A' }
+
+    # Return files deleted from the index
+    #
+    # @return [Hash{String => Git::Status::StatusFile}] deleted files keyed by path
+    #
     def deleted   = @deleted ||= select_files { |f| f.type == 'D' }
-    # This works with `true` or `nil`
+
+    # Return files present in the working tree but not tracked by git
+    #
+    # @return [Hash{String => Git::Status::StatusFile}] untracked files keyed by path
+    #
     def untracked = @untracked ||= select_files(&:untracked)
 
-    # Predicate methods to check the status of a specific file.
+    # Return `true` if `file` has been modified in the index or working tree
+    #
+    # @param file [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` if the file has been modified
+    #
     def changed?(file)   = file_in_collection?(:changed, file)
+
+    # Return `true` if `file` has been added to the index
+    #
+    # @param file [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` if the file has been added
+    #
     def added?(file)     = file_in_collection?(:added, file)
+
+    # Return `true` if `file` has been deleted from the index
+    #
+    # @param file [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` if the file has been deleted
+    #
     def deleted?(file)   = file_in_collection?(:deleted, file)
+
+    # Return `true` if `file` is not tracked by git
+    #
+    # @param file [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` if the file is untracked
+    #
     def untracked?(file) = file_in_collection?(:untracked, file)
 
-    # Access a status file by path, or iterate over all status files.
+    # Return the {Git::Status::StatusFile} for the given path
+    #
+    # @param file [String] the repository-relative path
+    #
+    # @return [Git::Status::StatusFile, nil] the status file, or `nil` if not found
+    #
     def [](file) = @files[file]
+
+    # Iterate over all status files
+    #
+    # @yield [file] each {Git::Status::StatusFile} in the repository
+    #
+    # @yieldparam file [Git::Status::StatusFile] a single file's status
+    #
+    # @return [Enumerator<Git::Status::StatusFile>] if no block is given
+    #
+    # @return [Array<Git::Status::StatusFile>] if a block is given
+    #
     def each(&) = @files.values.each(&)
 
-    # Returns a formatted string representation of the status.
+    # Return a formatted multi-line string representation of the status
+    #
+    # @return [String] one indented block per file showing its SHA, mode, type,
+    #   stage, and untracked flag
+    #
     def pretty
       map { |file| pretty_file(file) }.join << "\n"
     end
 
     private
 
+    # Format a single file's status as an indented multi-line string
+    #
+    # @param file [Git::Status::StatusFile] the file to format
+    #
+    # @return [String] the formatted status block for this file
+    #
     def pretty_file(file)
       <<~FILE
         #{file.path}
@@ -52,10 +129,26 @@ module Git
       FILE
     end
 
+    # Return a hash of files for which the block returns a truthy value
+    #
+    # @yield [file] each {Git::Status::StatusFile} in the repository
+    #
+    # @yieldparam file [Git::Status::StatusFile] a single file's status
+    #
+    # @return [Hash{String => Git::Status::StatusFile}] matching files keyed by path
+    #
     def select_files(&block)
       @files.select { |_path, file| block.call(file) }
     end
 
+    # Return `true` if `file_path` exists in the named status collection
+    #
+    # @param collection_name [Symbol] the collection to check (e.g. `:changed`)
+    #
+    # @param file_path [String] the repository-relative path to look up
+    #
+    # @return [Boolean] `true` if the path is present in the collection
+    #
     def file_in_collection?(collection_name, file_path)
       collection = public_send(collection_name)
       if ignore_case?
@@ -65,12 +158,25 @@ module Git
       end
     end
 
+    # Return a memoized set of downcased keys for the named collection
+    #
+    # @param collection_name [Symbol] the collection whose keys to downcase
+    #
+    # @return [Set<String>] the lowercased path keys
+    #
     def downcased_keys(collection_name)
       @_downcased_keys ||= {}
       @_downcased_keys[collection_name] ||=
         public_send(collection_name).keys.to_set(&:downcase)
     end
 
+    # Return `true` when git is configured to ignore filename case
+    #
+    # Reads `core.ignoreCase` from the repository config. Returns `false` if
+    # the config value is absent or if reading it raises {Git::FailedError}.
+    #
+    # @return [Boolean] `true` when `core.ignoreCase` is `"true"`
+    #
     def ignore_case?
       return @_ignore_case if defined?(@_ignore_case)
 
@@ -78,13 +184,65 @@ module Git
     rescue Git::FailedError
       @_ignore_case = false
     end
+  end
+end
 
+module Git
+  class Status
     # Represents a single file's status in the git repository. Each instance
     # holds information about a file's state in the index and working tree.
+    #
+    # @api public
+    #
     class StatusFile
-      attr_reader :path, :type, :stage, :mode_index, :mode_repo,
-                  :sha_index, :sha_repo, :untracked
+      # The repository-relative file path
+      #
+      # @return [String] the path
+      attr_reader :path
 
+      # The change type for this file
+      #
+      # @return [String, nil] `"M"` for modified, `"A"` for added, `"D"` for deleted,
+      #   or `nil` when not applicable
+      attr_reader :type
+
+      # The merge stage for this file
+      #
+      # @return [String, nil] `"0"` for normal entries, or a non-zero value during
+      #   a merge conflict
+      attr_reader :stage
+
+      # The file mode recorded in the index
+      #
+      # @return [String, nil] the octal file mode (e.g. `"100644"`), or `nil`
+      attr_reader :mode_index
+
+      # The file mode recorded in HEAD
+      #
+      # @return [String, nil] the octal file mode (e.g. `"100644"`), or `nil`
+      attr_reader :mode_repo
+
+      # The SHA of the index version of this file
+      #
+      # @return [String, nil] the SHA-1 hex digest, or `nil` if unavailable
+      attr_reader :sha_index
+
+      # The SHA of the HEAD version of this file
+      #
+      # @return [String, nil] the SHA-1 hex digest, or `nil` if unavailable
+      attr_reader :sha_repo
+
+      # Whether this file is untracked
+      #
+      # @return [Boolean, nil] `true` when the file is not tracked by git
+      attr_reader :untracked
+
+      # Initialize a new StatusFile with the given git object and data hash
+      #
+      # @param base [Git::Base, Git::Repository] the git object
+      #
+      # @param hash [Hash] raw status data for this file
+      #
       def initialize(base, hash)
         @base       = base
         @path       = hash[:path]
@@ -97,24 +255,51 @@ module Git
         @untracked  = hash[:untracked]
       end
 
-      # Returns a Git::Object::Blob for either the index or repo version of the file.
+      # Return a blob object for the index or repo version of this file
+      #
+      # @param type [Symbol] `:index` (default) for the index version, or
+      #   `:repo` for the HEAD version
+      #
+      # @return [Git::Object::Blob, nil] the blob object, or `nil` if no SHA
+      #   is available for the requested version
+      #
       def blob(type = :index)
         sha = type == :repo ? sha_repo : (sha_index || sha_repo)
         @base.object(sha) if sha
       end
     end
+  end
+end
 
+module Git
+  class Status
     # A factory class responsible for fetching git status data and building
     # a hash of StatusFile objects.
+    #
     # @api private
+    #
     class StatusFileFactory
+      # Create a new factory backed by the given git object
+      #
+      # When `base` is a {Git::Repository} (which exposes `#diff_index`
+      # directly), it is used as the data provider. When `base` is a
+      # {Git::Base} (the legacy path), `base.lib` is used instead.
+      #
+      # @param base [Git::Base, Git::Repository] the git object used as the
+      #   status data provider
+      #
       def initialize(base)
         @base = base
-        @lib = base.lib
+        # When base is Git::Repository (which exposes #diff_index directly),
+        # use it as the data provider. Otherwise use base.lib (legacy path).
+        @provider = base.respond_to?(:diff_index) ? base : base.lib
       end
 
-      # Gathers all status data and builds a hash of file paths to
-      # StatusFile objects.
+      # Gather all status data and build a hash of file paths to StatusFile objects
+      #
+      # @return [Hash{String => Git::Status::StatusFile}] file paths mapped to
+      #   their status objects
+      #
       def construct_files
         files_data = fetch_all_files_data
         files_data.transform_values do |data|
@@ -124,33 +309,56 @@ module Git
 
       private
 
-      # Fetches and merges status information from multiple git commands.
+      # Fetch and merge status information from multiple git commands
+      #
+      # @return [Hash{String => Hash}] raw per-file status data keyed by path
+      #
       def fetch_all_files_data
-        files = @lib.ls_files # Start with files tracked in the index.
+        files = @provider.ls_files # Start with files tracked in the index.
         merge_untracked_files(files)
         merge_modified_files(files)
         merge_head_diffs(files)
         files
       end
 
+      # Merge untracked working-tree files into `files`
+      #
+      # @param files [Hash] the in-progress files hash to update in place
+      #
+      # @return [void]
+      #
       def merge_untracked_files(files)
-        @lib.untracked_files.each do |file|
+        @provider.untracked_files.each do |file|
           files[file] = { path: file, untracked: true }
         end
       end
 
+      # Merge index-versus-working-tree diff data into `files`
+      #
+      # @param files [Hash] the in-progress files hash to update in place
+      #
+      # @return [void]
+      #
       def merge_modified_files(files)
         # Merge changes between the index and the working directory.
-        @lib.diff_files.each do |path, data|
+        @provider.diff_files.each do |path, data|
           (files[path] ||= {}).merge!(data)
         end
       end
 
+      # Merge HEAD-versus-index diff data into `files`, if commits exist
+      #
+      # @param files [Hash] the in-progress files hash to update in place
+      #
+      # @return [void]
+      #
       def merge_head_diffs(files)
-        return if @lib.empty?
+        # Git::Repository exposes #no_commits?; Git::Lib exposes #empty?.
+        is_empty = @provider.respond_to?(:no_commits?) ? @provider.no_commits? : @provider.empty?
+        return if is_empty
 
         # Merge changes between HEAD and the index.
-        @lib.diff_index('HEAD').each do |path, data|
+        @provider.diff_index('HEAD').each do |path, data|
           (files[path] ||= {}).merge!(data)
         end
       end

data/lib/git/tag_delete_failure.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents a tag that failed to be deleted
+  #
+  # This is an immutable data object returned as part of {Git::TagDeleteResult}
+  # when one or more tags could not be deleted.
+  #
+  # @example
+  #   failure = Git::TagDeleteFailure.new(
+  #     name: 'nonexistent',
+  #     error_message: "tag 'nonexistent' not found."
+  #   )
+  #   failure.name          #=> 'nonexistent'
+  #   failure.error_message #=> "tag 'nonexistent' not found."
+  #
+  # @see Git::TagDeleteResult
+  # @see Git::Commands::Tag::Delete
+  #
+  # @api public
+  #
+  # @!attribute [r] name
+  #   The name of the tag that failed to be deleted
+  #   @return [String]
+  #
+  # @!attribute [r] error_message
+  #   The error message from git explaining why the tag could not be deleted
+  #   @return [String]
+  #
+  TagDeleteFailure = Data.define(:name, :error_message)
+end

data/lib/git/tag_delete_result.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'git/tag_info'
+require 'git/tag_delete_failure'
+
+module Git
+  # Represents the result of a tag delete operation
+  #
+  # This is an immutable data object returned by {Git::Commands::Tag::Delete#call}.
+  # It contains information about which tags were successfully deleted and which
+  # failed to be deleted, along with the reason for each failure.
+  #
+  # Git's `git tag -d` command uses "best effort" semantics - it deletes as many
+  # tags as possible and reports errors for those that couldn't be deleted. This
+  # result object reflects that behavior, allowing callers to inspect both
+  # successes and failures.
+  #
+  # @example Successful deletion of all tags
+  #   result = tag_delete.call('v1.0.0', 'v2.0.0')
+  #   result.success?            #=> true
+  #   result.deleted.map(&:name) #=> ['v1.0.0', 'v2.0.0']
+  #   result.not_deleted         #=> []
+  #
+  # @example Partial failure (some tags deleted, some not found)
+  #   result = tag_delete.call('v1.0.0', 'nonexistent', 'v2.0.0')
+  #   result.success?                    #=> false
+  #   result.deleted.map(&:name)         #=> ['v1.0.0', 'v2.0.0']
+  #   result.not_deleted.first.name          #=> 'nonexistent'
+  #   result.not_deleted.first.error_message #=> "tag 'nonexistent' not found."
+  #
+  # @see Git::TagInfo
+  # @see Git::TagDeleteFailure
+  # @see Git::Commands::Tag::Delete
+  #
+  # @api public
+  #
+  # @!attribute [r] deleted
+  #   Tags that were successfully deleted
+  #   @return [Array<Git::TagInfo>]
+  #
+  # @!attribute [r] not_deleted
+  #   Tags that could not be deleted, with the reason for each failure
+  #   @return [Array<Git::TagDeleteFailure>]
+  #
+  TagDeleteResult = Data.define(:deleted, :not_deleted) do
+    # Returns true if all requested tags were successfully deleted
+    #
+    # @return [Boolean] true if no tags failed to delete, false otherwise
+    #
+    # @example
+    #   result = tag_delete.call('v1.0.0')
+    #   if result.success?
+    #     puts "All tags deleted successfully"
+    #   else
+    #     puts "Some tags could not be deleted:"
+    #     result.not_deleted.each { |f| puts "  #{f.name}: #{f.error_message}" }
+    #   end
+    #
+    def success?
+      not_deleted.empty?
+    end
+  end
+end

data/lib/git/tag_info.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'git/author'
+
+module Git
+  # Value object representing tag metadata from git tag output
+  #
+  # This is a lightweight, immutable data structure returned by tag listing
+  # commands. It contains only the data parsed from git output without any
+  # repository context or operations.
+  #
+  # @example Annotated tag
+  #   info = Git::TagInfo.new(
+  #     name: 'v1.0.0',
+  #     oid: 'abc123def456',        # tag object's ID
+  #     target_oid: 'def456abc789', # commit it points to
+  #     objecttype: 'tag',
+  #     tagger_name: 'John Doe',
+  #     tagger_email: '<john@example.com>',
+  #     tagger_date: '2024-01-15T10:30:00-08:00',
+  #     message: 'Release version 1.0.0'
+  #   )
+  #   info.annotated?   #=> true
+  #   info.tagger.name  #=> 'John Doe'
+  #
+  # @example Lightweight tag
+  #   info = Git::TagInfo.new(
+  #     name: 'v1.0.0',
+  #     oid: nil,                   # no tag object exists
+  #     target_oid: 'def456abc789', # commit ID
+  #     objecttype: 'commit',
+  #     tagger_name: nil,
+  #     tagger_email: nil,
+  #     tagger_date: nil,
+  #     message: nil
+  #   )
+  #   info.lightweight?  #=> true
+  #   info.tagger        #=> nil
+  #
+  # @see Git::Tag for the full-featured tag object with operations
+  # @see Git::Commands::Tag::List for the command that produces these
+  #
+  # @api public
+  #
+  # @!attribute [r] name
+  #   @return [String] the tag name (e.g., 'v1.0.0')
+  #
+  # @!attribute [r] oid
+  #   The object ID of the tag object itself.
+  #
+  #   For annotated tags, this is the tag object's ID. For lightweight tags,
+  #   this is nil because lightweight tags are not objects in the git database.
+  #
+  #   @return [String, nil] the tag object's ID, or nil for lightweight tags
+  #
+  # @!attribute [r] target_oid
+  #   The object ID of the commit this tag ultimately points to.
+  #
+  #   For both annotated and lightweight tags, this is the commit ID that the
+  #   tag resolves to (i.e., the dereferenced target).
+  #
+  #   @return [String] the commit ID this tag points to
+  #
+  # @!attribute [r] objecttype
+  #   @return [String] 'tag' for annotated tags, 'commit' for lightweight tags
+  #
+  # @!attribute [r] tagger_name
+  #   @return [String, nil] the tagger's name, or nil for lightweight tags
+  #
+  # @!attribute [r] tagger_email
+  #   @return [String, nil] the tagger's email, or nil for lightweight tags
+  #
+  # @!attribute [r] tagger_date
+  #   @return [String, nil] the tag date in ISO 8601 format, or nil for lightweight tags
+  #
+  # @!attribute [r] message
+  #   @return [String, nil] the tag message, or nil for lightweight tags
+  #
+  TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
+    # @return [Boolean] true if this is an annotated tag (oid is present)
+    def annotated?
+      !oid.nil?
+    end
+
+    # @return [Boolean] true if this is a lightweight tag (oid is nil)
+    def lightweight?
+      oid.nil?
+    end
+
+    # Return the tagger as an Author object
+    #
+    # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
+    def tagger
+      return nil unless annotated? && tagger_name && tagger_email
+
+      # Git::Author expects format "Name <email> timestamp timezone"
+      # We construct a minimal format that will parse correctly
+      author = Git::Author.new('')
+      author.name = tagger_name
+      # Remove angle brackets if present
+      author.email = tagger_email.gsub(/\A<|>\z/, '')
+      author
+    end
+  end
+end

data/lib/git/version.rb

@@ -2,6 +2,113 @@
 
 module Git
   # The current gem version
-  # @return [String] the current gem version.
-  VERSION = '4.4.0'
+  #
+  # @return [String] the current gem version
+  VERSION = '5.0.0.beta.1'
+
+  # Represents a git version with major, minor, and patch components
+  #
+  # Git versions follow a strict major.minor.patch format. This class provides
+  # parsing from git command output (which may include platform suffixes) and
+  # comparison operations for version gating.
+  #
+  # @!attribute [r] major
+  #   The major version number
+  #   @return [Integer]
+  #
+  # @!attribute [r] minor
+  #   The minor version number
+  #   @return [Integer]
+  #
+  # @!attribute [r] patch
+  #   The patch version number
+  #   @return [Integer]
+  #
+  # @example Creating a version directly
+  #   version = Git::Version.new(2, 42, 1)
+  #   version.to_s  #=> "2.42.1"
+  #
+  # @example Parsing from git version output
+  #   Git::Version.parse('git version 2.42.1')  #=> Git::Version.new(2, 42, 1)
+  #   Git::Version.parse('2.39.2 (Apple Git-143)')  #=> Git::Version.new(2, 39, 2)
+  #
+  # @example Parsing versions with platform suffixes
+  #   Git::Version.parse('2.42.0.windows.1')  #=> Git::Version.new(2, 42, 0)
+  #
+  # @example Comparing versions
+  #   Git::Version.new(2, 42, 1) > Git::Version.new(2, 28, 0)  #=> true
+  #
+  # @api public
+  #
+  Version = Data.define(:major, :minor, :patch) do
+    include Comparable
+
+    # Parse a version string into a Version object
+    #
+    # Handles git's version output format, stripping platform suffixes
+    # (like `.windows.1` or `.vfs.0`) and padding two-segment versions
+    # to three segments.
+    #
+    # @example Parse various version string formats
+    #   Git::Version.parse('2.42.1')  #=> Git::Version.new(2, 42, 1)
+    #   Git::Version.parse('git version 2.42.1')  #=> Git::Version.new(2, 42, 1)
+    #   Git::Version.parse('2.42.0.windows.1')  #=> Git::Version.new(2, 42, 0)
+    #
+    # @param string [String] version string to parse
+    #
+    # @return [Git::Version] the parsed version
+    #
+    # @raise [Git::UnexpectedResultError] if the string cannot be parsed as a version
+    #
+    def self.parse(string)
+      version_match = string&.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
+      raise Git::UnexpectedResultError, "Invalid version: #{string.inspect}" unless version_match
+
+      major = version_match[1].to_i
+      minor = version_match[2].to_i
+      patch = (version_match[3] || '0').to_i
+
+      new(major, minor, patch)
+    end
+
+    # Compare this version to another
+    #
+    # @param other [Git::Version] the version to compare to
+    #
+    # @return [Integer] -1, 0, or 1
+    #
+    def <=>(other)
+      [major, minor, patch] <=> [other.major, other.minor, other.patch]
+    end
+
+    # Return the version as a dotted string
+    #
+    # @return [String] the version in "major.minor.patch" format
+    #
+    def to_s
+      "#{major}.#{minor}.#{patch}"
+    end
+
+    # Return a readable representation
+    #
+    # @return [String] inspect string
+    #
+    def inspect
+      "#<Git::Version #{self}>"
+    end
+
+    # Return the version as an array of integers
+    #
+    # Useful when legacy code expects the array shape returned by the
+    # deprecated {Git::Lib#current_command_version} method.
+    #
+    # @return [Array<Integer>] [major, minor, patch]
+    #
+    # @example
+    #   Git.git_version.to_a  #=> [2, 42, 0]
+    #
+    def to_a
+      deconstruct
+    end
+  end
 end