git 5.3.0 → 5.4.1

data/lib/git/object.rb

@@ -538,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
       #
@@ -551,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
@@ -558,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
@@ -609,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]
@@ -663,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/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/worktree.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'git/worktree_info'
+
+module Git
+  module Parsers
+    # Parser for git worktree command output
+    #
+    # Handles parsing of `git worktree list --porcelain` output into structured
+    # data objects.
+    #
+    # @note Known limitation: git C-quotes a lock or prune reason that contains
+    #   unusual characters such as a newline or a non-ASCII byte (see the
+    #   `--porcelain` description in the git-worktree documentation). The reason
+    #   is returned as git prints it, quotes and escapes included; it is not
+    #   unquoted.
+    #
+    # ## Design Note: Namespace Organization
+    #
+    # This parser creates and returns {Git::WorktreeInfo} objects, which live at
+    # the top-level `Git::` namespace rather than within `Git::Parsers::`. This
+    # is intentional:
+    #
+    # - **Parsers are infrastructure** - marked `@api private`, users shouldn't
+    #   interact with them directly
+    # - **Info classes are public API** - returned by commands and used throughout
+    #   the codebase
+    # - **Info classes are domain entities** - represent core git concepts
+    #   (worktrees as data)
+    #
+    # Keeping Info classes at `Git::` improves discoverability and correctly
+    # reflects their role as public types rather than parser internals.
+    #
+    # @api private
+    #
+    module Worktree
+      # Pattern splitting a porcelain line into its key and optional value
+      #
+      # The key is everything before the first space and the value is everything
+      # after it, so a path or reason that contains spaces is kept intact. The
+      # pattern matches every line; a line with no space has a nil value.
+      LINE_PATTERN = /\A(?<key>[^ ]*)(?: (?<value>.*))?\z/
+
+      # Attribute values for a worktree with no flags set
+      #
+      # @return [Hash{Symbol => Object}]
+      DEFAULT_ATTRS = {
+        head: nil, branch: nil, bare: false, detached: false,
+        locked: false, lock_reason: nil, prunable: false, prune_reason: nil
+      }.freeze
+
+      module_function
+
+      # Parse git worktree list --porcelain output into WorktreeInfo objects
+      #
+      # Records are separated by a blank line. Each record starts with a
+      # `worktree <path>` line followed by any of `HEAD <sha>`, `branch <ref>`,
+      # `bare`, `detached`, `locked [<reason>]`, and `prunable <reason>`.
+      #
+      # @example
+      #   Git::Parsers::Worktree.parse_list(
+      #     "worktree /tmp/wt/main\nHEAD f3e2c1f...\nbranch refs/heads/main\n"
+      #   )
+      #   # => [#<data Git::WorktreeInfo path="/tmp/wt/main", ...>]
+      #
+      # @param stdout [String] output from `git worktree list --porcelain`
+      #
+      # @return [Array<Git::WorktreeInfo>] one entry per worktree, in the order
+      #   git listed them (the main worktree first)
+      #
+      # @raise [Git::UnexpectedResultError] if a record does not start with a
+      #   `worktree` line or contains an unrecognized key
+      #
+      def parse_list(stdout)
+        records(stdout).map { |lines| parse_record(lines, stdout) }
+      end
+
+      # Split the output into records, each an array of chomped non-blank lines
+      #
+      # Blank lines separate records. `chunk` drops every run of lines whose
+      # block value is `:_separator`, so only the non-blank runs are returned.
+      #
+      # @param stdout [String] output from `git worktree list --porcelain`
+      #
+      # @return [Array<Array<String>>] the lines of each record
+      #
+      def records(stdout)
+        stdout.each_line(chomp: true).chunk { |line| line.empty? ? :_separator : true }.map { |_, lines| lines }
+      end
+
+      # Parse one record into a WorktreeInfo
+      #
+      # @param lines [Array<String>] the lines of the record
+      #
+      # @param stdout [String] the full output (for error messages)
+      #
+      # @return [Git::WorktreeInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the record does not start with a
+      #   `worktree` line or contains an unrecognized key
+      #
+      def parse_record(lines, stdout)
+        key, path = split_line(lines.first)
+        unless key == 'worktree' && path
+          raise Git::UnexpectedResultError,
+                unexpected_line_error(stdout, lines.first, 'expected a record to start with "worktree <path>"')
+        end
+
+        Git::WorktreeInfo.new(path: path, **DEFAULT_ATTRS, **record_attrs(lines.drop(1), stdout))
+      end
+
+      # Collect the attributes set by the lines that follow the `worktree` line
+      #
+      # @param lines [Array<String>] the record's lines after the first
+      #
+      # @param stdout [String] the full output (for error messages)
+      #
+      # @return [Hash{Symbol => Object}] the attributes to override in DEFAULT_ATTRS
+      #
+      # @raise [Git::UnexpectedResultError] if a line has an unrecognized key
+      #
+      def record_attrs(lines, stdout)
+        lines.each_with_object({}) { |line, attrs| attrs.merge!(line_attrs(line, stdout)) }
+      end
+
+      # Map one porcelain line to the WorktreeInfo attributes it sets
+      #
+      # @param line [String] a chomped line of porcelain output
+      #
+      # @param stdout [String] the full output (for error messages)
+      #
+      # @return [Hash{Symbol => Object}] the attributes set by the line
+      #
+      # @raise [Git::UnexpectedResultError] if the line has an unrecognized key
+      #
+      def line_attrs(line, stdout)
+        key, value = split_line(line)
+
+        case key
+        when 'HEAD' then { head: value }
+        when 'branch' then { branch: value }
+        when 'bare' then { bare: true }
+        when 'detached' then { detached: true }
+        when 'locked' then { locked: true, lock_reason: value }
+        when 'prunable' then { prunable: true, prune_reason: value }
+        else raise Git::UnexpectedResultError, unexpected_line_error(stdout, line, 'unrecognized key')
+        end
+      end
+
+      # Split a porcelain line into its key and optional value
+      #
+      # @param line [String] a chomped line of porcelain output
+      #
+      # @return [Array(String, String), Array(String, nil)] the key and the
+      #   value, or nil when the line has no value
+      #
+      def split_line(line)
+        match = LINE_PATTERN.match(line)
+        [match[:key], match[:value]]
+      end
+
+      # Generate the error message for a line the parser cannot handle
+      #
+      # @param stdout [String] the full output
+      #
+      # @param line [String] the problematic line
+      #
+      # @param reason [String] why the line is unexpected
+      #
+      # @return [String] the formatted error message
+      #
+      def unexpected_line_error(stdout, line, reason)
+        <<~ERROR
+          Unexpected line in output from `git worktree list --porcelain`: #{reason}
+
+          Line:
+            "#{line}"
+
+          Full output:
+            #{stdout.gsub("\n", "\n  ")}
+        ERROR
+      end
+    end
+  end
+end