git 1.19.1 → 5.5.0

data/lib/git/stash_info.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'time'
+
+require 'git/author_info'
+
+module Git
+  # Immutable value object representing stash entry information
+  #
+  # StashInfo encapsulates the parsed data from `git stash list` output.
+  # Each entry contains comprehensive information about the stash including
+  # its index, reference name, commit SHA, branch, message, and the author and
+  # committer identities.
+  #
+  # The author and committer are nested {Git::AuthorInfo} values. Their `date`
+  # is a `Time` parsed from git's ISO 8601 output, not an ISO 8601 string.
+  #
+  # @example Create a StashInfo from parsed stash list output
+  #   info = Git::StashInfo.new(
+  #     index: 0,
+  #     name: 'stash@{0}',
+  #     oid: 'abc123def456789...',
+  #     short_oid: 'abc123d',
+  #     branch: 'main',
+  #     message: 'WIP on main: abc123 Initial commit',
+  #     author: Git::AuthorInfo.new(
+  #       name: 'Jane Doe',
+  #       email: 'jane@example.com',
+  #       date: Time.iso8601('2026-01-24T10:30:00-08:00')
+  #     ),
+  #     committer: Git::AuthorInfo.new(
+  #       name: 'Jane Doe',
+  #       email: 'jane@example.com',
+  #       date: Time.iso8601('2026-01-24T10:30:00-08:00')
+  #     )
+  #   )
+  #
+  #   info.index           # => 0
+  #   info.name            # => 'stash@{0}'
+  #   info.oid             # => 'abc123def456789...'
+  #   info.short_oid       # => 'abc123d'
+  #   info.branch          # => 'main'
+  #   info.message         # => 'WIP on main: abc123 Initial commit'
+  #   info.author.name     # => 'Jane Doe'
+  #   info.author.email    # => 'jane@example.com'
+  #   info.author.date     # => 2026-01-24 10:30:00 -0800
+  #   info.committer.name  # => 'Jane Doe'
+  #
+  # @see Git::AuthorInfo for the nested author and committer identities
+  #
+  # @api public
+  #
+  # @!attribute [r] index
+  #   @return [Integer] the stash index (0, 1, 2, ...)
+  #
+  # @!attribute [r] name
+  #   @return [String] the stash reference name (e.g., 'stash@\\{0\\}')
+  #
+  # @!attribute [r] oid
+  #   @return [String] the full 40-character object identifier of the stash
+  #
+  # @!attribute [r] short_oid
+  #   @return [String] the abbreviated object identifier (typically 7 characters)
+  #
+  # @!attribute [r] branch
+  #   @return [String, nil] the branch name where the stash was created,
+  #     or nil for custom stash messages
+  #
+  # @!attribute [r] message
+  #   @return [String] the stash message (e.g., 'WIP on main: abc123 commit msg')
+  #
+  # @!attribute [r] author
+  #   The identity of the stash author; the nested `date` is a `Time`.
+  #
+  #   @return [Git::AuthorInfo] the author of the stash commit
+  #
+  # @!attribute [r] committer
+  #   The identity of the stash committer; the nested `date` is a `Time`.
+  #
+  #   @return [Git::AuthorInfo] the committer of the stash commit
+  #
+  StashInfo = Data.define(
+    :index,
+    :name,
+    :oid,
+    :short_oid,
+    :branch,
+    :message,
+    :author,
+    :committer
+  ) do
+    # Returns the stash reference name
+    #
+    # @example Convert to string
+    #   info.to_s # => 'stash@{0}'
+    #
+    # @return [String] the stash name (e.g., 'stash@\\{0}')
+    def to_s
+      name
+    end
+  end
+end

data/lib/git/stashes.rb

@@ -1,55 +1,198 @@
+# frozen_string_literal: true
+
 module Git
-  
-  # object that holds all the available stashes
+  # Collection of stash entries for a Git repository
+  #
+  # This class is deprecated and will be removed in v6.0.0. Use the
+  # {Git::Repository} stash methods and {Git::StashInfo} instead:
+  # {Git::Repository#stash_infos} replaces the collection, and
+  # {Git::Repository#stash_push}, {Git::Repository#stash_apply}, and
+  # {Git::Repository#stash_clear} replace {#save}, {#apply}, and {#clear}.
+  #
+  # @example Iterate over stash entries (deprecated)
+  #   git.stashes.each { |s| puts s.message }
+  #
+  # @example The replacement
+  #   repo.stash_infos.each { |info| puts info.message }
+  #   repo.stash_infos.size   #=> 2
+  #   repo.stash_apply
+  #
+  # @deprecated Use {Git::Repository#stash_infos} and {Git::StashInfo} instead
+  #
+  # @see Git::Repository#stash_infos
+  #
+  # @api public
+  #
   class Stashes
     include Enumerable
-    
+
+    # Initialize the stashes collection
+    #
+    # Loads all existing stash entries from the repository at construction time.
+    # Emits one deprecation warning per object.
+    #
+    # @example Load stashes for a repository
+    #   stashes = Git::Stashes.new(repo)
+    #   stashes.size  #=> 2
+    #
+    # @param base [Git::Repository] the git repository
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @deprecated Use {Git::Repository#stash_infos} and {Git::StashInfo} instead
+    #
     def initialize(base)
+      Git::Deprecation.warn(
+        'Git::Stashes is deprecated and will be removed in v6.0.0. ' \
+        'Use the Git::Repository stash methods (stash_infos, stash_push, stash_apply, stash_clear) ' \
+        'and Git::StashInfo instead.'
+      )
       @stashes = []
-      
       @base = base
-            
-      @base.lib.stashes_all.each do |id, message|
-        @stashes.unshift(Git::Stash.new(@base, message, true))
-      end
+      # stashes_all and Git::Stash are deprecated too; silence them so one
+      # Git::Stashes.new emits one warning
+      Git::Deprecation.silence { load_stashes }
     end
 
+    # Returns all stash entries as an array of index and message pairs
+    #
+    # Entries are listed in oldest-first order matching {Git::Repository#stashes_all}.
+    #
+    # @example List all stash entries
+    #   git.stashes.all  #=> [[0, "testing-stash-all"], [1, "another-stash"]]
     #
-    # Returns an multi-dimensional Array of elements that have been stash saved.
-    # Array is based on position and name. See Example
+    # @return [Array<Array(Integer, String)>] array of `[index, message]` pairs where
+    #   index 0 is the oldest stash
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
-    # @example Returns Array of items that have been stashed
-    #     .all - [0, "testing-stash-all"]]
-    # @return [Array]
     def all
-      @base.lib.stashes_all
+      # stashes_all is deprecated too; silence it so this call emits no second warning
+      Git::Deprecation.silence { stash_repository.stashes_all }
     end
-    
+
+    # Saves the current working-directory state to a new stash entry
+    #
+    # @example Save current changes to the stash
+    #   git.stashes.save('WIP: feature work')
+    #   git.stashes.size  #=> 1
+    #
+    # @param message [String] the stash message
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def save(message)
-      s = Git::Stash.new(@base, message)
+      # Git::Stash is deprecated too; silence it so this call emits no second warning
+      s = Git::Deprecation.silence { Git::Stash.new(@base, message) }
       @stashes.unshift(s) if s.saved?
     end
-    
-    def apply(index=nil)
-      @base.lib.stash_apply(index)
+
+    # Applies a stash entry to the working directory
+    #
+    # @example Apply the most recent stash
+    #   git.stashes.apply
+    #
+    # @example Apply a specific stash by index
+    #   git.stashes.apply(1)
+    #
+    # @param index [Integer, nil] the stash index to apply (default: latest)
+    #
+    # @return [String] the output from the git stash apply command
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def apply(index = nil)
+      stash_repository.stash_apply(index)
     end
-    
+
+    # Removes all stash entries
+    #
+    # @example Clear all stashes
+    #   git.stashes.clear
+    #   git.stashes.size  #=> 0
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def clear
-      @base.lib.stash_clear
+      stash_repository.stash_clear
       @stashes = []
+      nil
     end
 
+    # Returns the number of stash entries
+    #
+    # @example Check how many stashes exist
+    #   git.stashes.size  #=> 2
+    #
+    # @return [Integer] the number of stashes
+    #
     def size
       @stashes.size
     end
-    
-    def each(&block)
-      @stashes.each(&block)
+
+    # Iterates over each stash entry in newest-first order
+    #
+    # @example Iterate over stashes
+    #   git.stashes.each { |s| puts s.message }
+    #
+    # @overload each
+    #
+    #   @return [Enumerator<Git::Stash>] an enumerator over stash entries
+    #
+    # @overload each(&block)
+    #
+    #   @yield [stash] each stash entry
+    #
+    #   @yieldparam stash [Git::Stash] the current stash entry
+    #
+    #   @yieldreturn [void]
+    #
+    #   @return [Array<Git::Stash>] the stash entries
+    #
+    def each(&)
+      @stashes.each(&)
     end
-    
+
+    # Returns the stash entry at the given index
+    #
+    # Stashes are stored in newest-first order; index 0 is the most recent stash.
+    #
+    # @example Access the most recent stash
+    #   git.stashes[0].message  #=> "WIP: feature work"
+    #
+    # @param index [Integer, #to_i] the stash index (0 = most recent)
+    #
+    # @return [Git::Stash, nil] the stash entry, or `nil` if the index is out of bounds
+    #
     def [](index)
       @stashes[index.to_i]
     end
-    
+
+    private
+
+    # Wraps every entry from the repository in a Git::Stash, newest first
+    #
+    # @return [void]
+    #
+    def load_stashes
+      stash_repository.stashes_all.each do |stash|
+        message = stash[1]
+        @stashes.unshift(Git::Stash.new(@base, message, existing: true))
+      end
+    end
+
+    # Returns the facade interface for stash operations
+    #
+    # @return [Git::Repository]
+    #
+    def stash_repository
+      @base
+    end
   end
 end