Module: Git::Parsers::Tag Private

Defined in:
lib/git/parsers/tag.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Note:

Known limitation: If a tag message contains the field delimiter character (\x1f, ASCII unit separator), it will be preserved correctly since the message is the last field. However, messages are rarely crafted with non-printable control characters.

Parser for git tag command output

Handles parsing of git tag --list and git tag --delete output into structured data objects.

Design Note: Namespace Organization

This parser creates and returns TagInfo and TagDeleteResult 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/Result classes are public API - returned by commands and used throughout the codebase
  • Info classes are domain entities - represent core git concepts (tags as data)
  • Result classes are operation outcomes - represent command results, not parsing details

Keeping Info/Result classes at Git:: improves discoverability and correctly reflects their role as public types rather than parser internals.

Constant Summary collapse

FIELD_DELIMITER =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Delimiter for separating fields in git tag --format output Field separator used in custom format output Using the ASCII unit separator (US, 0x1F / "\x1f"), a non-printable character, minimizes the chance of collisions with tag names or messages and remains safe to pass through Process.spawn and shell argument boundaries.

"\x1f"
RECORD_DELIMITER =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Delimiter for separating records (tags) in output Using the ASCII record separator (RS, 0x1E / "\x1e") to delimit complete tag records. This allows multi-line messages (which contain newlines) to be parsed correctly since we split by record separator first, then by field delimiter.

"\x1e"
FIELD_COUNT =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Number of fields expected in the parsed output

8
FORMAT_STRING =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Format string for git tag --format

Fields:

  • %(refname:short) - tag name
  • %(objectname) - SHA of the tag object (for annotated) or commit (for lightweight)
  • %(*objectname) - Dereferenced SHA (commit ID for annotated tags, empty for lightweight)
  • %(objecttype) - 'tag' for annotated tags, target object type (commit/tree/blob/etc.) for lightweight tags
  • %(taggername) - tagger name (empty for lightweight tags)
  • %(taggeremail) - tagger email (empty for lightweight tags)
  • %(taggerdate:iso8601-strict) - tagger date in strict ISO 8601 format
  • %(contents) - full tag message (can be multi-line)

Each tag record is terminated by the RECORD_DELIMITER to allow multi-line messages.

[
  '%(refname:short)',
  '%(objectname)',
  '%(*objectname)',
  '%(objecttype)',
  '%(taggername)',
  '%(taggeremail)',
  '%(taggerdate:iso8601-strict)',
  '%(contents)'
].join(FIELD_DELIMITER) + RECORD_DELIMITER
DELETED_TAG_REGEX =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Regex to parse successful deletion lines from stdout Matches: Deleted tag 'tagname' (was abc123)

/^Deleted tag '([^']+)'/
ERROR_TAG_REGEX =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Regex to parse error messages from stderr Matches: error: tag 'tagname' not found.

/^error: tag '([^']+)'(.*)$/

Class Method Summary collapse

Class Method Details

.build_delete_result(requested_names, existing_tags, deleted_names, error_map) ⇒ Git::TagDeleteResult

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Build the TagDeleteResult from parsed data

Parameters:

  • requested_names (Array<String>) —

    originally requested tag names

  • existing_tags (Hash<String, Git::TagInfo>) —

    tags that existed before delete

  • deleted_names (Array<String>) —

    names confirmed deleted in stdout

  • error_map (Hash<String, String>) —

    map of tag name to error message

Returns:



258
259
260
261
262
263
264
265
266
267
 
# File 'lib/git/parsers/tag.rb', line 258

def build_delete_result(requested_names, existing_tags, deleted_names, error_map)
  deleted = deleted_names.filter_map { |name| existing_tags[name] }

  not_deleted = (requested_names - deleted_names).map do |name|
    error_message = error_map[name] || "tag '#{name}' could not be deleted"
    Git::TagDeleteFailure.new(name: name, error_message: error_message)
  end

  Git::TagDeleteResult.new(deleted: deleted, not_deleted: not_deleted)
end

.build_tag_info(parts) ⇒ Git::TagInfo

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

For annotated tags:

  • oid = %(objectname) (the tag object's ID)
  • target_oid = %(*objectname) (the dereferenced commit ID)
Note:

For lightweight tags:

  • oid = nil (lightweight tags are not objects)
  • target_oid = %(objectname) (the commit ID)

Build a TagInfo object from parsed parts

Parameters:

  • parts (Array<String>) —

    the parsed format fields

Returns:



153
154
155
156
 
# File 'lib/git/parsers/tag.rb', line 153

def build_tag_info(parts)
  oid, target_oid = resolve_oids(parts[3], parts[1], parts[2])
  build_tag_info_object(parts, oid, target_oid)
end

.build_tag_info_object(parts, oid, target_oid) ⇒ Git::TagInfo

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds a TagInfo object from normalized parser values

Parameters:

  • parts (Array<String>) —

    the parsed format fields

  • oid (String, nil) —

    the tag object's OID or nil for lightweight tags

  • target_oid (String) —

    the target object OID

Returns:



183
184
185
186
187
188
189
 
# File 'lib/git/parsers/tag.rb', line 183

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])
  )
end

.parse_deleted_tags(stdout) ⇒ Array<String>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parse deleted tag names from stdout

Examples:

TagParser.parse_deleted_tags("Deleted tag 'v1.0.0' (was abc123)\n")
# => ["v1.0.0"]

Parameters:

  • stdout (String) —

    command stdout

Returns:

  • (Array<String>) —

    names of successfully deleted tags



225
226
227
 
# File 'lib/git/parsers/tag.rb', line 225

def parse_deleted_tags(stdout)
  stdout.scan(DELETED_TAG_REGEX).flatten
end

.parse_error_messages(stderr) ⇒ Hash<String, String>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parse error messages from stderr into a map

Examples:

TagParser.parse_error_messages("error: tag 'missing' not found.\n")
# => {"missing" => "error: tag 'missing' not found."}

Parameters:

  • stderr (String) —

    command stderr

Returns:

  • (Hash<String, String>) —

    map of tag name to error message



239
240
241
242
243
244
 
# File 'lib/git/parsers/tag.rb', line 239

def parse_error_messages(stderr)
  stderr.each_line.with_object({}) do |line, hash|
    match = line.match(ERROR_TAG_REGEX)
    hash[match[1]] = line.strip if match
  end
end

.parse_list(stdout) ⇒ Array<Git::TagInfo>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parse git tag --list output into TagInfo objects

Examples:

TagParser.parse_list("v1.0.0\x1f...\x1e\n")
# => [#<Git::TagInfo name: "v1.0.0", ...>]

Parameters:

  • stdout (String) —

    output from git tag --list --format=...

Returns:

Raises:



102
103
104
105
106
107
108
 
# File 'lib/git/parsers/tag.rb', line 102

def parse_list(stdout)
  # Split by record separator
  # Each record may have a leading newline from the previous record's %(contents) output
  # Use lstrip to remove leading whitespace (which includes the newline) from each record
  records = stdout.split(RECORD_DELIMITER).map(&:lstrip).reject(&:empty?)
  records.map.with_index { |record, index| parse_tag_record(record, index, records) }
end

.parse_message(objecttype, message) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parse message field, returning nil for lightweight tags or empty messages Strips trailing newlines that git adds to %(contents) output

Parameters:

  • objecttype (String) —

    the object type ('tag' or 'commit')

  • message (String) —

    the raw message field

Returns:

  • (String, nil) —

    the message or nil



210
211
212
213
 
# File 'lib/git/parsers/tag.rb', line 210

def parse_message(objecttype, message)
  stripped = message.chomp
  objecttype == 'tag' && !stripped.empty? ? stripped : nil
end

.parse_optional_field(value) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parse an optional field, returning nil if empty

Parameters:

  • value (String) —

    the field value

Returns:

  • (String, nil) —

    the value or nil if empty



197
198
199
 
# File 'lib/git/parsers/tag.rb', line 197

def parse_optional_field(value)
  value.empty? ? nil : value
end

.parse_tag_record(record, index, all_records) ⇒ Git::TagInfo

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parse a single formatted tag record

The record format is: nameshaderefobjecttypetagger_nametagger_emailtagger_datemessage where 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.

Parameters:

  • record (String) —

    a single tag record from git tag --format output

  • index (Integer) —

    record index for error reporting

  • all_records (Array<String>) —

    all output records for error messages

Returns:

Raises:



129
130
131
132
133
134
135
136
137
 
# File 'lib/git/parsers/tag.rb', line 129

def parse_tag_record(record, index, all_records)
  parts = record.split(FIELD_DELIMITER, FIELD_COUNT)

  unless parts.length == FIELD_COUNT
    raise Git::UnexpectedResultError, unexpected_tag_record_error(all_records, record, index)
  end

  build_tag_info(parts)
end

.resolve_oids(objecttype, objectname, dereferenced) ⇒ Array((String, nil), String)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Resolves canonical and target object OIDs from git tag format fields

Parameters:

  • objecttype (String) —

    the object type from git output

  • objectname (String) —

    the object OID from %(objectname)

  • dereferenced (String) —

    the object OID from %(*objectname)

Returns:

  • (Array((String, nil), String)) —

    the two-element tuple [oid, target_oid]



169
170
171
 
# File 'lib/git/parsers/tag.rb', line 169

def resolve_oids(objecttype, objectname, dereferenced)
  objecttype == 'tag' ? [objectname, dereferenced] : [nil, objectname]
end

.unexpected_tag_record_error(records, record, index) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generate error message for unexpected tag record format

Parameters:

  • records (Array<String>) —

    all output records

  • record (String) —

    the problematic record

  • index (Integer) —

    the record index

Returns:

  • (String) —

    formatted error message



279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/git/parsers/tag.rb', line 279

def unexpected_tag_record_error(records, record, index)
  format_str = FORMAT_STRING.gsub(FIELD_DELIMITER, '<FS>').gsub(RECORD_DELIMITER, '<RS>')
  <<~ERROR
    Unexpected record in output from `git tag --list --format=#{format_str}`, at index #{index}

    Expected #{FIELD_COUNT} fields separated by '\\x1f' (unit separator), got #{record.split(FIELD_DELIMITER, -1).length}

    Full output:
      #{records.join("\n  ")}

    Record at index #{index}:
      "#{record}"
  ERROR
end