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:



223
224
225
226
227
228
229
230
231
232
 
# File 'lib/git/parsers/tag.rb', line 223

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:



148
149
150
151
 
# File 'lib/git/parsers/tag.rb', line 148

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)

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. 



157
158
159
160
161
162
163
 
# File 'lib/git/parsers/tag.rb', line 157

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



195
196
197
 
# File 'lib/git/parsers/tag.rb', line 195

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



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

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:



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

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



181
182
183
184
 
# File 'lib/git/parsers/tag.rb', line 181

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



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

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:



125
126
127
128
129
130
131
132
133
 
# File 'lib/git/parsers/tag.rb', line 125

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)

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. 



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

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



241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/git/parsers/tag.rb', line 241

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