git 5.2.0 → 5.4.0

data/lib/git/object.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'git/author'
+require 'git/author_info'
 require 'git/diff'
 require 'git/errors'
 require 'git/log'
@@ -438,7 +438,10 @@ module Git
         @parents
       end
 
-      # git author
+      # Returns the commit author identity
+      #
+      # @return [Git::AuthorInfo] the author name, email, and author date
+      #
       def author
         check_commit
         @author
@@ -452,7 +455,10 @@ module Git
         author.date
       end
 
-      # git author
+      # Returns the commit committer identity
+      #
+      # @return [Git::AuthorInfo] the committer name, email, and commit date
+      #
       def committer
         check_commit
         @committer
@@ -499,8 +505,8 @@ module Git
       #
       def from_data(data)
         @sha ||= data['sha']
-        @committer = Git::Author.new(data['committer'])
-        @author = Git::Author.new(data['author'])
+        @committer = Git::AuthorInfo.parse(data['committer'])
+        @author = Git::AuthorInfo.parse(data['author'])
         @tree = Git::Object::Tree.new(@base, data['tree'])
         @parents = data['parent'].map { |sha| Git::Object::Commit.new(@base, sha) }
         @message = data['message'].chomp
@@ -532,6 +538,18 @@ module Git
     # Annotated tags contain additional metadata such as the tagger's name, email, and
     # the date when the tag was created, along with a message.
     #
+    # @deprecated Use {Git::Repository::ObjectOperations#tag_list} and
+    #   {Git::TagInfo} instead
+    #
+    #   {Git::TagInfo} is an immutable value object carrying the tag's `name`,
+    #   `oid`, `target_oid`, `annotated?`, `message`, and `tagger`. Call the
+    #   corresponding {Git::Repository} method (e.g. `archive`, `log`, `diff`,
+    #   `cat_file_contents`) with `info.oid || info.target_oid` for operations
+    #   on a tag; that is the object this class resolves and pins at
+    #   construction, so a later move of the tag does not redirect an existing
+    #   object, whereas the tag name would. Constructing a `Git::Object::Tag`
+    #   emits a deprecation warning.
+    #
     class Tag < AbstractObject
       # @return [String] the tag name
       #
@@ -545,6 +563,13 @@ module Git
       #
       # @overload initialize(base, sha, name)
       #
+      #   `sha` is kept as the object that the inherited operations (`size`,
+      #   `contents`, `grep`, `diff`, `log`, `archive`) run against; `annotated?`,
+      #   `message`, and `tagger` read the ref `name`. {Git::TagInfo} describes a
+      #   ref, so there is no OID-based replacement for this form: pass `sha` to
+      #   the {Git::Repository} operation directly, or read the tag object with
+      #   {Git::Repository::ObjectOperations#cat_file_tag}.
+      #
       #   @param base [Git::Repository] the git repository
       #
       #   @param sha [String] the SHA of the tag object
@@ -552,12 +577,11 @@ module Git
       #   @param name [String] the name of the tag
       #
       def initialize(base, sha, name = nil)
-        if name.nil?
-          name = sha
-          sha = base.tag_sha(name)
-          raise Git::UnexpectedResultError, "Tag '#{name}' does not exist." if sha == ''
-        end
-
+        Git::Deprecation.warn(
+          'Git::Object::Tag is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#tag_list and Git::TagInfo instead.'
+        )
+        sha, name = resolve_sha_and_name(base, sha, name)
         super(base, sha)
 
         @name = name
@@ -593,7 +617,7 @@ module Git
 
       # Returns the tagger identity
       #
-      # @return [Git::Author, nil] the tagger for an annotated tag, or `nil`
+      # @return [Git::AuthorInfo, nil] the tagger for an annotated tag, or `nil`
       #   for a lightweight tag
       #
       def tagger
@@ -603,6 +627,31 @@ module Git
 
       private
 
+      # Resolves the two-argument constructor form to a SHA and a tag name
+      #
+      # In the two-argument form `sha` carries the tag name and the SHA is
+      # looked up from the repository.
+      #
+      # @param base [Git::Repository] the git repository
+      #
+      # @param sha [String] the SHA of the tag object, or the tag name in the
+      #   two-argument form
+      #
+      # @param name [String, nil] the tag name, or `nil` in the two-argument form
+      #
+      # @return [Array(String, String)] the resolved `[sha, name]` pair
+      #
+      # @raise [Git::UnexpectedResultError] if the tag does not exist
+      #
+      def resolve_sha_and_name(base, sha, name)
+        return [sha, name] unless name.nil?
+
+        resolved = base.tag_sha(sha)
+        raise Git::UnexpectedResultError, "Tag '#{sha}' does not exist." if resolved == ''
+
+        [resolved, sha]
+      end
+
       # Loads annotated tag data when available
       #
       # @return [void]
@@ -613,7 +662,7 @@ module Git
         if annotated?
           tdata = object_repository.cat_file_tag(@name)
           @message = tdata['message'].chomp
-          @tagger = Git::Author.new(tdata['tagger'])
+          @tagger = Git::AuthorInfo.parse(tdata['tagger'])
         else
           @message = @tagger = nil
         end
@@ -657,14 +706,19 @@ module Git
     #
     # @return [Git::Object::Tag] the tag object wrapper
     #
-    # @deprecated use `Git::Object::Tag.new` instead
+    # @deprecated Use {Git::Repository::ObjectOperations#tag_list} instead
+    #
+    #   The warning names `Git::Object::Tag.new`, the replacement this path
+    #   shipped with, and the {Git::Object::Tag} constructor is deprecated as
+    #   well; this method silences it so one call emits one warning. Go
+    #   straight to `Git::Repository#tag_list(name).first`.
     #
     private_class_method def self.new_tag(base, objectish)
       Git::Deprecation.warn(
         'Git::Object.new with is_tag argument is deprecated and will be removed in v6.0.0. ' \
         'Use Git::Object::Tag.new instead.'
       )
-      Git::Object::Tag.new(base, objectish)
+      Git::Deprecation.silence { Git::Object::Tag.new(base, objectish) }
     end
 
     # Returns the repository used for object lookup

data/lib/git/parsers/stash.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'time'
+
+require 'git/author_info'
 require 'git/stash_info'
 
 module Git
@@ -45,10 +48,10 @@ module Git
       # %gs = reflog subject (the stash message)
       # %an = author name
       # %ae = author email
-      # %aI = author date (ISO 8601 format)
+      # %aI = author date (ISO 8601 format, parsed into a Time)
       # %cn = committer name
       # %ce = committer email
-      # %cI = committer date (ISO 8601 format)
+      # %cI = committer date (ISO 8601 format, parsed into a Time)
       STASH_FORMAT = [
         '%H',  # 0: full SHA
         '%h',  # 1: short SHA
@@ -163,7 +166,7 @@ module Git
       # @return [Hash] attributes for StashInfo.new
       #
       def stash_info_attrs(parts, index)
-        core_attrs(parts, index).merge(author_attrs(parts)).merge(committer_attrs(parts))
+        core_attrs(parts, index).merge(author: author_info(parts), committer: committer_info(parts))
       end
 
       # Build core StashInfo attributes from parsed fields
@@ -182,30 +185,60 @@ module Git
         }
       end
 
-      # Build author-related StashInfo attributes from parsed fields
+      # Build the author identity from the parsed fields
       #
       # @param parts [Array<String>] the parsed format fields
       #
-      # @return [Hash<Symbol, String>] author attributes for StashInfo.new
+      # @return [Git::AuthorInfo] the stash author; its `date` is a `Time`
       #
-      def author_attrs(parts)
-        {
-          author_name: parts[Fields::AUTHOR_NAME], author_email: parts[Fields::AUTHOR_EMAIL],
-          author_date: parts[Fields::AUTHOR_DATE]
-        }
+      def author_info(parts)
+        build_author_info(parts[Fields::AUTHOR_NAME], parts[Fields::AUTHOR_EMAIL], parts[Fields::AUTHOR_DATE])
       end
 
-      # Build committer-related StashInfo attributes from parsed fields
+      # Build the committer identity from the parsed fields
       #
       # @param parts [Array<String>] the parsed format fields
       #
-      # @return [Hash<Symbol, String>] committer attributes for StashInfo.new
+      # @return [Git::AuthorInfo] the stash committer; its `date` is a `Time`
       #
-      def committer_attrs(parts)
-        {
-          committer_name: parts[Fields::COMMITTER_NAME], committer_email: parts[Fields::COMMITTER_EMAIL],
-          committer_date: parts[Fields::COMMITTER_DATE]
-        }
+      def committer_info(parts)
+        build_author_info(
+          parts[Fields::COMMITTER_NAME], parts[Fields::COMMITTER_EMAIL], parts[Fields::COMMITTER_DATE]
+        )
+      end
+
+      # Build a Git::AuthorInfo from identity fields
+      #
+      # The date is parsed with `Time.iso8601`, so the UTC offset git emits for
+      # `%aI` and `%cI` is preserved in the resulting `Time`.
+      #
+      # @param name [String] the `%an` or `%cn` field
+      #
+      # @param email [String] the `%ae` or `%ce` field
+      #
+      # @param date [String] the `%aI` or `%cI` field in ISO 8601 format
+      #
+      # @return [Git::AuthorInfo] the identity with `date` as a `Time`
+      #
+      # @raise [Git::UnexpectedResultError] if the date is not a valid ISO 8601 date
+      #
+      def build_author_info(name, email, date)
+        Git::AuthorInfo.new(name: name, email: email, date: parse_date(date))
+      end
+
+      # Parse a `%aI` or `%cI` field into a Time
+      #
+      # @param date [String] the date field in ISO 8601 format
+      #
+      # @return [Time] the parsed time, preserving the UTC offset
+      #
+      # @raise [Git::UnexpectedResultError] if the field is not a valid ISO 8601 date
+      #
+      def parse_date(date)
+        Time.iso8601(date)
+      rescue ArgumentError => e
+        raise Git::UnexpectedResultError,
+              "Unexpected date #{date.inspect} in output from `git stash list`: #{e.message}"
       end
 
       # Extract the stash index from a reflog selector

data/lib/git/parsers/status.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'git/errors'
+require 'git/status_file_info'
+
+module Git
+  module Parsers
+    # Parser for `git status --porcelain=v2 -z` output
+    #
+    # Builds one {Git::StatusFileInfo} per entry. With `-z` every entry is
+    # NUL-terminated and paths are emitted verbatim (no quoting), so a path may
+    # contain spaces but never a NUL. The original path of a rename or copy
+    # entry is the NUL-terminated token that follows the entry.
+    #
+    # Every entry type of the porcelain v2 format is handled: `1` (ordinary),
+    # `2` (rename or copy), `u` (unmerged), `?` (untracked), and `!` (ignored).
+    # `#` header lines, emitted with `--branch` or `--show-stash`, are skipped.
+    #
+    # {Git::StatusFileInfo} lives at the top-level `Git::` namespace rather than
+    # within `Git::Parsers::` because it is public API returned to callers,
+    # while this parser is infrastructure.
+    #
+    # @example Parse the output of `git status --porcelain=v2 -z`
+    #   Git::Parsers::Status.parse("? new.txt\0")
+    #   #=> [#<data Git::StatusFileInfo path="new.txt", index_status="?", ...>]
+    #
+    # @see https://git-scm.com/docs/git-status#_porcelain_format_version_2
+    #
+    # @api private
+    #
+    module Status
+      # Separator between entries (and between a rename entry and its original path)
+      ENTRY_SEPARATOR = "\0"
+
+      # Separator between the fields of one entry
+      FIELD_SEPARATOR = / /
+
+      # First character of an ordinary (changed, added, or deleted) entry
+      ORDINARY_ENTRY = '1'
+
+      # First character of a rename or copy entry
+      RENAMED_ENTRY = '2'
+
+      # First character of an unmerged entry
+      UNMERGED_ENTRY = 'u'
+
+      # First character of an untracked entry
+      UNTRACKED_ENTRY = '?'
+
+      # First character of an ignored entry
+      IGNORED_ENTRY = '!'
+
+      # First character of a header line
+      HEADER_LINE = '#'
+
+      # Field count of an ordinary entry: `1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>`
+      ORDINARY_FIELD_COUNT = 9
+
+      # Field count of a rename or copy entry, which adds `<X><score>` before the path
+      RENAMED_FIELD_COUNT = 10
+
+      # Field count of an unmerged entry: `u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>`
+      UNMERGED_FIELD_COUNT = 11
+
+      # Field count of an untracked or ignored entry: `? <path>` or `! <path>`
+      PATH_ONLY_FIELD_COUNT = 2
+
+      # Every {Git::StatusFileInfo} member set to `nil`, for entries that lack a field
+      #
+      # @return [Hash{Symbol => nil}]
+      #
+      EMPTY_MEMBERS = Git::StatusFileInfo.members.to_h { |member| [member, nil] }.freeze
+
+      module_function
+
+      # Parse `git status --porcelain=v2 -z` output into StatusFileInfo objects
+      #
+      # @example Parse two entries
+      #   Git::Parsers::Status.parse(
+      #     "1 .M N... 100644 100644 100644 #{sha} #{sha} lib/foo.rb\0? new.txt\0"
+      #   ).map(&:path) #=> ["lib/foo.rb", "new.txt"]
+      #
+      # @param stdout [String] the NUL-separated output of `git status --porcelain=v2 -z`
+      #
+      # @return [Array<Git::StatusFileInfo>] one entry per reported path, in git's order
+      #
+      # @raise [Git::UnexpectedResultError] if an entry does not match the porcelain v2 format
+      #
+      def parse(stdout)
+        tokens = stdout.split(ENTRY_SEPARATOR)
+        files = []
+        until tokens.empty?
+          entry = tokens.shift
+          files << parse_entry(entry, tokens) unless entry.start_with?(HEADER_LINE)
+        end
+        files
+      end
+
+      # Parse one entry, consuming its original path from `tokens` for renames and copies
+      #
+      # @param entry [String] the entry line without its NUL terminator
+      #
+      # @param tokens [Array<String>] the entries that follow; a rename or copy
+      #   entry's original path is shifted off the front
+      #
+      # @return [Git::StatusFileInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the entry type is not recognized
+      #
+      def parse_entry(entry, tokens)
+        case entry[0]
+        when ORDINARY_ENTRY then parse_ordinary(entry)
+        when RENAMED_ENTRY then parse_renamed(entry, tokens.shift)
+        when UNMERGED_ENTRY then parse_unmerged(entry)
+        when UNTRACKED_ENTRY, IGNORED_ENTRY then parse_path_only(entry)
+        else raise Git::UnexpectedResultError, unexpected_entry_error(entry)
+        end
+      end
+
+      # Parse an ordinary (`1`) entry
+      #
+      # @param entry [String] the entry line
+      #
+      # @return [Git::StatusFileInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have nine fields
+      #
+      def parse_ordinary(entry)
+        _type, xy, submodule, mode_head, mode_index, mode_worktree, sha_head, sha_index, path =
+          split_fields(entry, ORDINARY_FIELD_COUNT)
+        build_file_info(xy, path:, submodule:, mode_head:, mode_index:, mode_worktree:, sha_head:, sha_index:)
+      end
+
+      # Parse a rename or copy (`2`) entry
+      #
+      # @param entry [String] the entry line
+      #
+      # @param original_path [String, nil] the NUL-terminated token that followed
+      #   the entry, or `nil` when the output ended
+      #
+      # @return [Git::StatusFileInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have ten fields
+      #   or the original path is missing
+      #
+      def parse_renamed(entry, original_path)
+        _type, xy, submodule, mode_head, mode_index, mode_worktree, sha_head, sha_index, score, path =
+          split_fields(entry, RENAMED_FIELD_COUNT)
+        raise Git::UnexpectedResultError, unexpected_entry_error(entry) if original_path.nil?
+
+        build_file_info(
+          xy,
+          path:, submodule:, mode_head:, mode_index:, mode_worktree:, sha_head:, sha_index:,
+          original_path:, rename_score: score[1..].to_i
+        )
+      end
+
+      # Parse an unmerged (`u`) entry
+      #
+      # @param entry [String] the entry line
+      #
+      # @return [Git::StatusFileInfo] the parsed entry with its stage data in
+      #   `unmerged_stages`
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have eleven fields
+      #
+      def parse_unmerged(entry)
+        _type, xy, submodule, mode1, mode2, mode3, mode_worktree, sha1, sha2, sha3, path =
+          split_fields(entry, UNMERGED_FIELD_COUNT)
+        stages = unmerged_stages([mode1, mode2, mode3], [sha1, sha2, sha3])
+        build_file_info(xy, path:, submodule:, mode_worktree:, unmerged_stages: stages)
+      end
+
+      # Parse an untracked (`?`) or ignored (`!`) entry
+      #
+      # The entry's single status character is used for both status positions,
+      # matching the `??` and `!!` codes of the short format.
+      #
+      # @param entry [String] the entry line
+      #
+      # @return [Git::StatusFileInfo] the parsed entry with `nil` metadata
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have two fields
+      #
+      def parse_path_only(entry)
+        type, path = split_fields(entry, PATH_ONLY_FIELD_COUNT)
+        build_file_info(type * 2, path: path)
+      end
+
+      # Split an entry into exactly `count` fields, the last of which is the path
+      #
+      # The path may contain spaces, so the split is limited to `count` fields.
+      #
+      # @param entry [String] the entry line
+      #
+      # @param count [Integer] the number of fields the entry type has
+      #
+      # @return [Array<String>] the fields
+      #
+      # @raise [Git::UnexpectedResultError] if the entry has fewer fields
+      #
+      def split_fields(entry, count)
+        fields = entry.split(FIELD_SEPARATOR, count)
+        return fields if fields.length == count
+
+        raise Git::UnexpectedResultError, unexpected_entry_error(entry)
+      end
+
+      # Build the frozen stage hash of an unmerged entry
+      #
+      # @param modes [Array<String>] the stage 1, 2, and 3 modes
+      #
+      # @param shas [Array<String>] the stage 1, 2, and 3 object names
+      #
+      # @return [Hash{Integer => Hash{Symbol => String}}] frozen `\\{ mode:, sha: }`
+      #   hashes keyed by stage number
+      #
+      def unmerged_stages(modes, shas)
+        modes.zip(shas).each_with_index.to_h do |(mode, sha), index|
+          [index + 1, { mode: mode, sha: sha }.freeze]
+        end.freeze
+      end
+
+      # Build a {Git::StatusFileInfo}, defaulting every member not given to `nil`
+      #
+      # @param statuses [String] the two status characters, `X` then `Y`
+      #
+      # @param members [Hash{Symbol => Object}] the members that the entry provides
+      #
+      # @option members [String] :path the repository-relative path
+      #
+      # @return [Git::StatusFileInfo] the value object
+      #
+      def build_file_info(statuses, **members)
+        Git::StatusFileInfo.new(
+          **EMPTY_MEMBERS, index_status: statuses[0], worktree_status: statuses[1], **members
+        )
+      end
+
+      # Generate the error message for an entry that does not match the format
+      #
+      # @param entry [String] the offending entry line
+      #
+      # @return [String] the message
+      #
+      def unexpected_entry_error(entry)
+        "Unexpected entry in output from `git status --porcelain=v2 -z`: #{entry.inspect}"
+      end
+    end
+  end
+end

data/lib/git/parsers/tag.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'time'
+
+require 'git/author_info'
 require 'git/tag_info'
 require 'git/tag_delete_result'
 require 'git/tag_delete_failure'
@@ -114,7 +117,7 @@ module Git
       # where <FS> is the unit separator character ("\x1f").
       #
       # For lightweight tags, Git emits empty strings for the tagger fields and message;
-      # these are converted to nil by {#parse_optional_field} and {#parse_message}.
+      # these are converted to nil by {#parse_tagger} and {#parse_message}.
       #
       # @param record [String] a single tag record from git tag --format output
       #
@@ -183,19 +186,62 @@ module Git
       def build_tag_info_object(parts, oid, target_oid)
         Git::TagInfo.new(
           name: parts[0], oid: oid, target_oid: target_oid, objecttype: parts[3],
-          tagger_name: parse_optional_field(parts[4]), tagger_email: parse_optional_field(parts[5]),
-          tagger_date: parse_optional_field(parts[6]), message: parse_message(parts[3], parts[7])
+          tagger: parse_tagger(parts[4], parts[5], parts[6]), message: parse_message(parts[3], parts[7])
         )
       end
 
-      # Parse an optional field, returning nil if empty
+      # Build the tagger identity from the tagger name, email, and date fields
+      #
+      # Git emits empty strings for all three fields when there is no tag object
+      # (lightweight tags) or the tag object has no tagger header, in which case
+      # the tagger is nil. Otherwise the angle brackets git wraps around
+      # `%(taggeremail)` are stripped and the strict ISO 8601
+      # `%(taggerdate:iso8601-strict)` value is parsed into a `Time` that
+      # preserves the UTC offset. A partially populated identity (for example an
+      # empty name with an email and date) is kept as emitted rather than dropped,
+      # and an empty date becomes `nil`.
+      #
+      # @example An annotated tag's tagger
+      #   parse_tagger('John Doe', '<john@example.com>', '2024-01-15T10:30:00-08:00')
+      #   #=> #<data Git::AuthorInfo name="John Doe", email="john@example.com", ...>
+      #
+      # @example A lightweight tag has no tagger
+      #   parse_tagger('', '', '') #=> nil
+      #
+      # @param name [String] the `%(taggername)` field
+      #
+      # @param email [String] the `%(taggeremail)` field, including angle brackets
+      #
+      # @param date [String] the `%(taggerdate:iso8601-strict)` field
+      #
+      # @return [Git::AuthorInfo, nil] the tagger, or nil when all three fields are empty
+      #
+      # @raise [Git::UnexpectedResultError] if a non-empty date is not a valid ISO 8601
+      #   date
+      #
+      def parse_tagger(name, email, date)
+        return nil if [name, email, date].all?(&:empty?)
+
+        Git::AuthorInfo.new(
+          name: name,
+          email: email.delete_prefix('<').delete_suffix('>'),
+          date: date.empty? ? nil : parse_date(date)
+        )
+      end
+
+      # Parse a `%(taggerdate:iso8601-strict)` field into a Time
+      #
+      # @param date [String] the date field in strict ISO 8601 format
       #
-      # @param value [String] the field value
+      # @return [Time] the parsed time, preserving the UTC offset
       #
-      # @return [String, nil] the value or nil if empty
+      # @raise [Git::UnexpectedResultError] if the field is not a valid ISO 8601 date
       #
-      def parse_optional_field(value)
-        value.empty? ? nil : value
+      def parse_date(date)
+        Time.iso8601(date)
+      rescue ArgumentError => e
+        raise Git::UnexpectedResultError,
+              "Unexpected tagger date #{date.inspect} in output from `git tag --list`: #{e.message}"
       end
 
       # Parse message field, returning nil for lightweight tags or empty messages