git 5.2.0 → 5.3.0

data/lib/git/repository/remote_operations.rb

@@ -525,7 +525,37 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
+      # @deprecated Use `remote_list.find { |r| r.name == name }` for the fields
+      #   {Git::RemoteInfo} models, or filter {Git::Configuring#config_list} on
+      #   the `remote.<name>.` key prefix to keep every entry
+      #
+      #   {#remote_list} returns a {Git::RemoteInfo} per remote. Its `url` and
+      #   `fetch` members hold every configured value as `Array<String>`,
+      #   whereas this method returns a flat hash in which a repeated `url` or
+      #   `fetch` key overwrites the earlier value.
+      #
+      #   {Git::RemoteInfo} models only the remote variables git defines and
+      #   drops any other `remote.<name>.*` entry, whereas this method returns
+      #   every entry. Callers that read custom keys should filter
+      #   {Git::Configuring#config_list} instead, which returns the same hash
+      #   (shown here for the `origin` remote):
+      #
+      #     prefix = 'remote.origin.'
+      #     repo.config_list
+      #         .select { |entry| entry.key.start_with?(prefix) }
+      #         .to_h { |entry| [entry.key.delete_prefix(prefix), entry.value] }
+      #
+      # @see #remote_list
+      #
+      # @see Git::Configuring#config_list
+      #
       def config_remote(name)
+        Git::Deprecation.warn(
+          'Git::Repository#config_remote is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_list.find { |r| r.name == name } for the fields ' \
+          'Git::RemoteInfo models, or filter Git::Repository#config_list on the ' \
+          '"remote.<name>." key prefix to keep every entry.'
+        )
         prefix = "remote.#{name}."
         Private.config_list(@execution_context).each_with_object({}) do |(key, value), hsh|
           hsh[key.delete_prefix(prefix)] = value if key.start_with?(prefix)
@@ -574,7 +604,19 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use `remote_list.find { |r| r.name == name }` instead
+      #
+      #   {#remote_list} returns immutable {Git::RemoteInfo} value objects
+      #   rather than {Git::Remote}. Call the corresponding {Git::Repository}
+      #   method (e.g. {#fetch}, {#remote_remove}) for operations on a remote.
+      #
+      # @see #remote_list
+      #
       def remote(name = 'origin')
+        Git::Deprecation.warn(
+          'Git::Repository#remote is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_list.find { |r| r.name == name } instead.'
+        )
         Git::Remote.new(self, name)
       end
 
@@ -589,7 +631,22 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use {#remote_list} instead
+      #
+      #   {#remote_list} returns `Array<Git::RemoteInfo>` (immutable value
+      #   objects) rather than `Array<Git::Remote>`. Call the corresponding
+      #   {Git::Repository} method (e.g. {#fetch}, {#remote_remove}) for
+      #   operations on a remote. Each {Git::Remote} this method constructs
+      #   emits its own deprecation warning, so a call produces one warning
+      #   for this method plus one per remote returned.
+      #
+      # @see #remote_list
+      #
       def remotes
+        Git::Deprecation.warn(
+          'Git::Repository#remotes is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_list instead.'
+        )
         result = Git::Commands::Remote::List.new(@execution_context).call
         result.stdout.split("\n").map { |name| Git::Remote.new(self, name) }
       end

data/lib/git/repository/shared_private.rb

@@ -46,6 +46,73 @@ module Git
 
         raise ArgumentError, "Unknown options: #{unknown.join(', ')}"
       end
+
+      # Raise unless `branch` names an existing local branch
+      #
+      # Used by facade methods that check out a branch, do work on it, and switch
+      # back. {Git::Repository#checkout} also accepts commit SHAs, tags, and
+      # remote-tracking branches, all of which detach HEAD; work committed there
+      # would be left dangling once the original branch is restored, and git has
+      # no way to report that.
+      #
+      # @example With an existing local branch
+      #   SharedPrivate.assert_local_branch!(repo, 'feature') #=> nil
+      #
+      # @example With a tag
+      #   SharedPrivate.assert_local_branch!(repo, 'v1.0.0')
+      #   #=> raises ArgumentError: 'v1.0.0' is not an existing local branch
+      #
+      # @param repository [Git::Repository] the repository to check
+      #
+      # @param branch [String] the branch name to verify
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] when `branch` is not an existing local branch
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def assert_local_branch!(repository, branch)
+        return if repository.local_branch?(branch)
+
+        raise ArgumentError, "'#{branch}' is not an existing local branch"
+      end
+
+      # Returns a revision that restores the current HEAD after switching branches
+      #
+      # Used by facade methods that temporarily check out another branch and
+      # then switch back. On a branch, the branch name is enough. When HEAD is
+      # detached, {Git::Repository#current_branch} reports `'HEAD'`, which after
+      # a checkout resolves to the new branch rather than the original commit,
+      # so the commit SHA is captured instead. An unborn branch (one with no
+      # commits yet) has no ref to check out by name, so it is rejected here,
+      # before the caller switches away from it.
+      #
+      # @example On a branch
+      #   SharedPrivate.head_restore_point(repo) #=> "main"
+      #
+      # @example With a detached HEAD
+      #   SharedPrivate.head_restore_point(repo) #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
+      #
+      # @param repository [Git::Repository] the repository whose HEAD to record
+      #
+      # @return [String] the current branch name, or the full HEAD commit SHA
+      #   when HEAD is detached
+      #
+      # @raise [Git::Error] when HEAD is on an unborn branch
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def head_restore_point(repository)
+        head = repository.current_branch_state
+        case head.state
+        when :detached then repository.rev_parse('HEAD').strip
+        when :unborn
+          raise Git::Error, "HEAD is on the unborn branch '#{head.name}', which cannot be restored " \
+                            'after switching branches; make a commit on it first'
+        else head.name
+        end
+      end
     end
 
     private_constant :SharedPrivate

data/lib/git/stash_info.rb

@@ -1,13 +1,19 @@
 # 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, author/committer
-  # details, and timestamps.
+  # 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(
@@ -17,12 +23,16 @@ module Git
   #     short_oid: 'abc123d',
   #     branch: 'main',
   #     message: 'WIP on main: abc123 Initial commit',
-  #     author_name: 'Jane Doe',
-  #     author_email: 'jane@example.com',
-  #     author_date: '2026-01-24T10:30:00-08:00',
-  #     committer_name: 'Jane Doe',
-  #     committer_email: 'jane@example.com',
-  #     committer_date: '2026-01-24T10:30:00-08:00'
+  #     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
@@ -31,12 +41,12 @@ module Git
   #   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-24T10:30:00-08:00'
-  #   info.committer_name  # => 'Jane Doe'
-  #   info.committer_email # => 'jane@example.com'
-  #   info.committer_date  # => '2026-01-24T10:30:00-08:00'
+  #   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
   #
@@ -59,23 +69,15 @@ module Git
   # @!attribute [r] message
   #   @return [String] the stash message (e.g., 'WIP on main: abc123 commit msg')
   #
-  # @!attribute [r] author_name
-  #   @return [String] the name of the stash author
-  #
-  # @!attribute [r] author_email
-  #   @return [String] the email of the stash author
-  #
-  # @!attribute [r] author_date
-  #   @return [String] the author date in ISO 8601 format
+  # @!attribute [r] author
+  #   The identity of the stash author; the nested `date` is a `Time`.
   #
-  # @!attribute [r] committer_name
-  #   @return [String] the name of the stash committer
+  #   @return [Git::AuthorInfo] the author of the stash commit
   #
-  # @!attribute [r] committer_email
-  #   @return [String] the email of the stash committer
+  # @!attribute [r] committer
+  #   The identity of the stash committer; the nested `date` is a `Time`.
   #
-  # @!attribute [r] committer_date
-  #   @return [String] the committer date in ISO 8601 format
+  #   @return [Git::AuthorInfo] the committer of the stash commit
   #
   StashInfo = Data.define(
     :index,
@@ -84,12 +86,8 @@ module Git
     :short_oid,
     :branch,
     :message,
-    :author_name,
-    :author_email,
-    :author_date,
-    :committer_name,
-    :committer_email,
-    :committer_date
+    :author,
+    :committer
   ) do
     # Returns the stash reference name
     #

data/lib/git/tag_info.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require 'git/author'
+require 'time'
+
+require 'git/author_info'
 
 module Git
   # Value object representing tag metadata from git tag output
@@ -9,19 +11,25 @@ module Git
   # commands. It contains only the data parsed from git output without any
   # repository context or operations.
   #
+  # The tagger identity is a nested {Git::AuthorInfo}. Its `date` is a `Time`
+  # parsed from git's strict ISO 8601 output, not an ISO 8601 string.
+  #
   # @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',
+  #     tagger: Git::AuthorInfo.new(
+  #       name: 'John Doe',
+  #       email: 'john@example.com',
+  #       date: Time.iso8601('2024-01-15T10:30:00-08:00')
+  #     ),
   #     message: 'Release version 1.0.0'
   #   )
   #   info.annotated?   #=> true
   #   info.tagger.name  #=> 'John Doe'
+  #   info.tagger.date  #=> 2024-01-15 10:30:00 -0800
   #
   # @example Lightweight tag
   #   info = Git::TagInfo.new(
@@ -29,9 +37,7 @@ module Git
   #     oid: nil,                   # no tag object exists
   #     target_oid: 'def456abc789', # commit ID
   #     objecttype: 'commit',
-  #     tagger_name: nil,
-  #     tagger_email: nil,
-  #     tagger_date: nil,
+  #     tagger: nil,
   #     message: nil
   #   )
   #   info.lightweight?  #=> true
@@ -41,6 +47,8 @@ module Git
   #
   # @see Git::Commands::Tag::List for the command that produces these
   #
+  # @see Git::AuthorInfo for the nested tagger identity
+  #
   # @api public
   #
   # @!attribute [r] name
@@ -65,19 +73,18 @@ module Git
   # @!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
+  #   The identity of the person who created the tag object.
   #
-  # @!attribute [r] tagger_email
-  #   @return [String, nil] the tagger's email, or nil for lightweight tags
+  #   Lightweight tags have no tag object and therefore no tagger. The nested
+  #   `email` has no angle brackets and the nested `date` is a `Time`.
   #
-  # @!attribute [r] tagger_date
-  #   @return [String, nil] the tag date in ISO 8601 format, or nil for lightweight tags
+  #   @return [Git::AuthorInfo, nil] the tagger, 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
+  TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger, :message) do
     # @return [Boolean] true if this is an annotated tag (oid is present)
     def annotated?
       !oid.nil?
@@ -87,20 +94,5 @@ module Git
     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

@@ -4,7 +4,7 @@ module Git
   # The current gem version
   #
   # @return [String] the current gem version
-  VERSION = '5.2.0'
+  VERSION = '5.3.0'
 
   # Represents a git version with major, minor, and patch components
   #

data/lib/git.rb

@@ -46,6 +46,7 @@ module Git
 end
 
 require 'git/author'
+require 'git/author_info'
 require 'git/branch'
 require 'git/branch_info'
 require 'git/branches'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.3.0
 platform: ruby
 authors:
 - Scott Chacon and others
@@ -311,6 +311,7 @@ files:
 - git.gemspec
 - lib/git.rb
 - lib/git/author.rb
+- lib/git/author_info.rb
 - lib/git/branch.rb
 - lib/git/branch_delete_failure.rb
 - lib/git/branch_delete_result.rb
@@ -542,8 +543,8 @@ licenses:
 metadata:
   homepage_uri: http://github.com/ruby-git/ruby-git
   source_code_uri: http://github.com/ruby-git/ruby-git
-  changelog_uri: https://rubydoc.info/gems/git/5.2.0/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/5.2.0
+  changelog_uri: https://rubydoc.info/gems/git/5.3.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/5.3.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: