git 1.19.1 → 5.5.0

data/lib/git/status_file_info.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object for the status of one path in the index and working tree
+  #
+  # Each member holds one field of the entry `git status --porcelain=v2` reports
+  # for the path. `index_status` and `worktree_status` are the `X` and `Y`
+  # characters of that entry: `.` unmodified, `M` modified, `T` type changed, `A`
+  # added, `D` deleted, `R` renamed, `C` copied, or `U` unmerged. Untracked
+  # entries carry `?` in both and ignored entries carry `!` in both, mirroring
+  # the `??` and `!!` codes of the short status format.
+  #
+  # The mode and SHA members are `nil` for untracked and ignored entries. For
+  # unmerged entries the per-stage modes and SHAs live in `unmerged_stages` and
+  # `mode_head`, `mode_index`, `sha_head`, and `sha_index` are `nil`.
+  # `original_path` and `rename_score` are set only for rename and copy entries.
+  #
+  # The predicates follow these rules: `added?` when `index_status` is `A`,
+  # `deleted?` when either status is `D`, `changed?` when either status is `M`
+  # or `T`, `renamed?` when either status is `R`, `untracked?` and `ignored?`
+  # from the `?` and `!` codes, and `unmerged?` when `unmerged_stages` is set.
+  #
+  # Every String member is a frozen copy of the value given, and
+  # `unmerged_stages` is a deeply frozen copy, so an entry cannot be changed
+  # through a member the caller still references.
+  #
+  # @example Inspect the status of one path
+  #   file = repo.status_info['lib/foo.rb']
+  #   file.index_status    #=> "M"
+  #   file.worktree_status #=> "."
+  #   file.changed?        #=> true
+  #   file.sha_index       #=> "2bdf67abb163a4ffb2d7f3f0880c9fe5068ce782"
+  #
+  # @example Read the original path of a rename
+  #   file = repo.status_info['lib/new_name.rb']
+  #   file.renamed?      #=> true
+  #   file.original_path #=> "lib/old_name.rb"
+  #   file.rename_score  #=> 100
+  #
+  # @example Read the stages of a merge conflict
+  #   file = repo.status_info['lib/conflict.rb']
+  #   file.unmerged?             #=> true
+  #   file.unmerged_stages[2]    #=> { mode: "100644", sha: "ba2906d0666c..." }
+  #
+  # @see Git::StatusInfo
+  #
+  # @see Git::Repository#status_info
+  #
+  # @see https://git-scm.com/docs/git-status#_porcelain_format_version_2
+  #
+  # @api public
+  #
+  # @!attribute [r] path
+  #
+  #   @return [String] the repository-relative path
+  #
+  # @!attribute [r] index_status
+  #
+  #   @return [String] the `X` status character (HEAD versus index), `?` for
+  #     untracked and `!` for ignored entries
+  #
+  # @!attribute [r] worktree_status
+  #
+  #   @return [String] the `Y` status character (index versus working tree), `?`
+  #     for untracked and `!` for ignored entries
+  #
+  # @!attribute [r] submodule
+  #
+  #   @return [String, nil] the four-character submodule state (`N...` for a
+  #     regular file), or `nil` for untracked and ignored entries
+  #
+  # @!attribute [r] mode_head
+  #
+  #   @return [String, nil] the octal file mode in HEAD (`000000` when the path
+  #     is not in HEAD), or `nil` for untracked, ignored, and unmerged entries
+  #
+  # @!attribute [r] mode_index
+  #
+  #   @return [String, nil] the octal file mode in the index (`000000` when the
+  #     path is not in the index), or `nil` for untracked, ignored, and unmerged
+  #     entries
+  #
+  # @!attribute [r] mode_worktree
+  #
+  #   @return [String, nil] the octal file mode in the working tree (`000000`
+  #     when the path is not in the working tree), or `nil` for untracked and
+  #     ignored entries
+  #
+  # @!attribute [r] sha_head
+  #
+  #   @return [String, nil] the object name of the blob in HEAD (all zeros when
+  #     the path is not in HEAD), or `nil` for untracked, ignored, and unmerged
+  #     entries
+  #
+  # @!attribute [r] sha_index
+  #
+  #   @return [String, nil] the object name of the blob in the index (all zeros
+  #     when the path is not in the index), or `nil` for untracked, ignored, and
+  #     unmerged entries
+  #
+  # @!attribute [r] original_path
+  #
+  #   @return [String, nil] the path the entry was renamed or copied from, or
+  #     `nil` for every other entry
+  #
+  # @!attribute [r] rename_score
+  #
+  #   @return [Integer, nil] the similarity score of a rename or copy entry, or
+  #     `nil` for every other entry
+  #
+  # @!attribute [r] unmerged_stages
+  #
+  #   @return [Hash{Integer => Hash{Symbol => String}}, nil] the mode and SHA of
+  #     each conflict stage keyed by stage number (1 for the merge base, 2 for
+  #     "ours", 3 for "theirs"), as frozen `\\{ mode:, sha: }` hashes, or `nil`
+  #     for every other entry
+  #
+  StatusFileInfo = Data.define(
+    :path,
+    :index_status,
+    :worktree_status,
+    :submodule,
+    :mode_head,
+    :mode_index,
+    :mode_worktree,
+    :sha_head,
+    :sha_index,
+    :original_path,
+    :rename_score,
+    :unmerged_stages
+  ) do
+    # Creates a file status value object holding frozen copies of its members
+    #
+    # String members are duplicated and frozen, and `unmerged_stages` is
+    # duplicated and frozen down to its mode and SHA strings, so neither this
+    # value nor a {Git::StatusInfo} holding it can be changed through a member
+    # the caller still references.
+    #
+    # @example Build an entry from parsed fields
+    #   Git::StatusFileInfo.new(path: 'lib/foo.rb', index_status: 'M', worktree_status: '.', ...)
+    #
+    # @param members [Hash{Symbol => Object}] one value per member; every
+    #   member is required
+    #
+    # @option members [String] :path the repository-relative path
+    #
+    # @option members [String] :index_status the `X` status character
+    #
+    # @option members [String] :worktree_status the `Y` status character
+    #
+    # @option members [String, nil] :submodule the four-character submodule state
+    #
+    # @option members [String, nil] :mode_head the octal file mode in HEAD
+    #
+    # @option members [String, nil] :mode_index the octal file mode in the index
+    #
+    # @option members [String, nil] :mode_worktree the octal file mode in the working tree
+    #
+    # @option members [String, nil] :sha_head the object name of the blob in HEAD
+    #
+    # @option members [String, nil] :sha_index the object name of the blob in the index
+    #
+    # @option members [String, nil] :original_path the path a rename or copy came from
+    #
+    # @option members [Integer, nil] :rename_score the similarity score of a rename or copy
+    #
+    # @option members [Hash{Integer => Hash{Symbol => String}}, nil] :unmerged_stages
+    #   the mode and SHA of each conflict stage keyed by stage number
+    #
+    def initialize(**members)
+      super(**members.transform_values { |value| deep_frozen(value) })
+    end
+
+    # Returns `true` when the path is not tracked by git
+    #
+    # @example Check an untracked path
+    #   repo.status_info['new.rb'].untracked? #=> true
+    #
+    # @return [Boolean] `true` when both status characters are `?`
+    #
+    def untracked? = index_status == '?' && worktree_status == '?'
+
+    # Returns `true` when the path is ignored
+    #
+    # Ignored entries are reported only when `git status` runs with `--ignored`.
+    # {Git::Repository#status_info} does not pass that option, so this is
+    # `false` for every entry it returns.
+    #
+    # @example Check an ignored entry
+    #   file = Git::Parsers::Status.parse("! tmp/debug.log\0").first
+    #   file.ignored? #=> true
+    #
+    # @return [Boolean] `true` when both status characters are `!`
+    #
+    def ignored? = index_status == '!' && worktree_status == '!'
+
+    # Returns `true` when the path has merge conflicts
+    #
+    # @example Check a conflicted path
+    #   repo.status_info['lib/conflict.rb'].unmerged? #=> true
+    #
+    # @return [Boolean] `true` when `unmerged_stages` is set
+    #
+    def unmerged? = !unmerged_stages.nil?
+
+    # Returns `true` when the path was renamed in the index or working tree
+    #
+    # @example Check a renamed path
+    #   repo.status_info['lib/new_name.rb'].renamed? #=> true
+    #
+    # @return [Boolean] `true` when either status character is `R`
+    #
+    def renamed? = index_status == 'R' || worktree_status == 'R'
+
+    # Returns `true` when the path was added to the index and is not in HEAD
+    #
+    # @example Check a newly staged path
+    #   repo.status_info['lib/new.rb'].added? #=> true
+    #
+    # @return [Boolean] `true` when `index_status` is `A`
+    #
+    def added? = index_status == 'A'
+
+    # Returns `true` when the path was deleted from the index or working tree
+    #
+    # @example Check a deleted path
+    #   repo.status_info['lib/old.rb'].deleted? #=> true
+    #
+    # @return [Boolean] `true` when either status character is `D`
+    #
+    def deleted? = index_status == 'D' || worktree_status == 'D'
+
+    # Returns `true` when the path's content or type changed in the index or working tree
+    #
+    # @example Check a modified path
+    #   repo.status_info['lib/foo.rb'].changed? #=> true
+    #
+    # @return [Boolean] `true` when either status character is `M` or `T`
+    #
+    def changed? = [index_status, worktree_status].intersect?(%w[M T])
+
+    private
+
+    # Returns a frozen copy of `value`, freezing the contents of a Hash recursively
+    #
+    # @param value [Object] a member value
+    #
+    # @return [Object] a frozen copy of a String or Hash; any other value as given
+    #
+    def deep_frozen(value)
+      case value
+      when String then value.dup.freeze
+      when Hash then value.to_h { |key, item| [key, deep_frozen(item)] }.freeze
+      else value
+      end
+    end
+  end
+end

data/lib/git/status_info.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'git/status_file_info'
+
+module Git
+  # Immutable value object for the status of a repository's index and working tree
+  #
+  # Holds one {Git::StatusFileInfo} per path that `git status` reports, in the
+  # order git listed them, together with the repository's `core.ignoreCase`
+  # setting. The derived readers (`changed`, `added`, `deleted`, `untracked`,
+  # `unmerged`) return the matching files keyed by path and are computed on each
+  # call. The path predicates (`changed?`, `added?`, `deleted?`, `untracked?`)
+  # compare paths case-insensitively when `ignore_case` is `true`.
+  #
+  # @example Inspect repository status
+  #   status = repo.status_info
+  #   status.changed.each_key { |path| puts "Modified: #{path}" }
+  #   status.added.each_key { |path| puts "Added: #{path}" }
+  #   status.deleted.each_key { |path| puts "Deleted: #{path}" }
+  #   status.untracked.each_key { |path| puts "Untracked: #{path}" }
+  #
+  # @example Check one path
+  #   status = repo.status_info
+  #   status.changed?('lib/foo.rb')       #=> true
+  #   status['lib/foo.rb'].worktree_status #=> "M"
+  #
+  # @see Git::StatusFileInfo
+  #
+  # @see Git::Repository#status_info
+  #
+  # @api public
+  #
+  # @!attribute [r] files
+  #
+  #   @return [Array<Git::StatusFileInfo>] every reported path in git's output
+  #     order; the array is frozen
+  #
+  # @!attribute [r] ignore_case
+  #
+  #   @return [Boolean] `true` when the repository's `core.ignoreCase` is true,
+  #     making the path predicates compare paths case-insensitively
+  #
+  StatusInfo = Data.define(:files, :ignore_case) do
+    # Creates a status value object holding a frozen copy of the given files
+    #
+    # @example Build a status from parsed files
+    #   Git::StatusInfo.new(files: files, ignore_case: false)
+    #
+    # @param files [Array<Git::StatusFileInfo>] the reported paths in git's
+    #   output order
+    #
+    # @param ignore_case [Boolean] whether path predicates ignore case
+    #
+    def initialize(files:, ignore_case:)
+      super(files: files.dup.freeze, ignore_case: ignore_case)
+    end
+
+    # Returns the files modified or type-changed in the index or working tree
+    #
+    # @example List modified paths
+    #   repo.status_info.changed.keys #=> ["lib/foo.rb"]
+    #
+    # @return [Hash{String => Git::StatusFileInfo}] changed files keyed by path
+    #
+    def changed = files_by_path(&:changed?)
+
+    # Returns the files added to the index that are not in HEAD
+    #
+    # @example List added paths
+    #   repo.status_info.added.keys #=> ["lib/new.rb"]
+    #
+    # @return [Hash{String => Git::StatusFileInfo}] added files keyed by path
+    #
+    def added = files_by_path(&:added?)
+
+    # Returns the files deleted from the index or working tree
+    #
+    # @example List deleted paths
+    #   repo.status_info.deleted.keys #=> ["lib/old.rb"]
+    #
+    # @return [Hash{String => Git::StatusFileInfo}] deleted files keyed by path
+    #
+    def deleted = files_by_path(&:deleted?)
+
+    # Returns the files in the working tree that git does not track
+    #
+    # @example List untracked paths
+    #   repo.status_info.untracked.keys #=> ["notes.txt"]
+    #
+    # @return [Hash{String => Git::StatusFileInfo}] untracked files keyed by path
+    #
+    def untracked = files_by_path(&:untracked?)
+
+    # Returns the files with merge conflicts
+    #
+    # @example List conflicted paths
+    #   repo.status_info.unmerged.keys #=> ["lib/conflict.rb"]
+    #
+    # @return [Hash{String => Git::StatusFileInfo}] unmerged files keyed by path
+    #
+    def unmerged = files_by_path(&:unmerged?)
+
+    # Returns `true` if `path` is modified in the index or working tree
+    #
+    # @example Check a path
+    #   repo.status_info.changed?('lib/foo.rb') #=> true
+    #
+    # @param path [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` when the path is in {#changed}
+    #
+    def changed?(path) = path_in?(changed, path)
+
+    # Returns `true` if `path` was added to the index
+    #
+    # @example Check a path
+    #   repo.status_info.added?('lib/new.rb') #=> true
+    #
+    # @param path [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` when the path is in {#added}
+    #
+    def added?(path) = path_in?(added, path)
+
+    # Returns `true` if `path` was deleted from the index or working tree
+    #
+    # @example Check a path
+    #   repo.status_info.deleted?('lib/old.rb') #=> true
+    #
+    # @param path [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` when the path is in {#deleted}
+    #
+    def deleted?(path) = path_in?(deleted, path)
+
+    # Returns `true` if `path` is not tracked by git
+    #
+    # @example Check a path
+    #   repo.status_info.untracked?('notes.txt') #=> true
+    #
+    # @param path [String] the repository-relative path to check
+    #
+    # @return [Boolean] `true` when the path is in {#untracked}
+    #
+    def untracked?(path) = path_in?(untracked, path)
+
+    # Returns the {Git::StatusFileInfo} for the given path
+    #
+    # The path is matched exactly, regardless of `ignore_case`.
+    #
+    # @example Look up a path
+    #   repo.status_info['lib/foo.rb'] #=> #<data Git::StatusFileInfo path="lib/foo.rb", ...>
+    #   repo.status_info['clean.rb']   #=> nil
+    #
+    # @param path [String] the repository-relative path
+    #
+    # @return [Git::StatusFileInfo, nil] the file, or `nil` when git did not report it
+    #
+    def [](path) = files.find { |file| file.path == path }
+
+    private
+
+    # Returns the files for which the block is truthy, keyed by path
+    #
+    # @return [Hash{String => Git::StatusFileInfo}] the selected files keyed by path
+    #
+    # @yield [file] each {Git::StatusFileInfo} in `files`
+    #
+    # @yieldparam file [Git::StatusFileInfo] one reported path
+    #
+    # @yieldreturn [Boolean] truthy to include the file
+    #
+    def files_by_path(&) = files.select(&).to_h { |file| [file.path, file] }
+
+    # Returns `true` when `path` is a key of `collection`, honoring `ignore_case`
+    #
+    # @param collection [Hash{String => Git::StatusFileInfo}] files keyed by path
+    #
+    # @param path [String] the repository-relative path to look for
+    #
+    # @return [Boolean] `true` when the path is present
+    #
+    def path_in?(collection, path)
+      return collection.key?(path) unless ignore_case
+
+      collection.each_key.any? { |key| key.casecmp?(path) }
+    end
+  end
+end

data/lib/git/tag_delete_failure.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents a tag that failed to be deleted
+  #
+  # This is an immutable data object returned as part of {Git::TagDeleteResult}
+  # when one or more tags could not be deleted.
+  #
+  # @example
+  #   failure = Git::TagDeleteFailure.new(
+  #     name: 'nonexistent',
+  #     error_message: "tag 'nonexistent' not found."
+  #   )
+  #   failure.name          #=> 'nonexistent'
+  #   failure.error_message #=> "tag 'nonexistent' not found."
+  #
+  # @see Git::TagDeleteResult
+  #
+  # @see Git::Commands::Tag::Delete
+  #
+  # @api public
+  #
+  # @!attribute [r] name
+  #   The name of the tag that failed to be deleted
+  #
+  #   @return [String]
+  #
+  # @!attribute [r] error_message
+  #   The error message from git explaining why the tag could not be deleted
+  #
+  #   @return [String]
+  #
+  TagDeleteFailure = Data.define(:name, :error_message)
+end

data/lib/git/tag_delete_result.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'git/tag_info'
+require 'git/tag_delete_failure'
+
+module Git
+  # Represents the result of a tag delete operation
+  #
+  # This is an immutable data object returned by {Git::Commands::Tag::Delete#call}.
+  # It contains information about which tags were successfully deleted and which
+  # failed to be deleted, along with the reason for each failure.
+  #
+  # Git's `git tag -d` command uses "best effort" semantics - it deletes as many
+  # tags as possible and reports errors for those that couldn't be deleted. This
+  # result object reflects that behavior, allowing callers to inspect both
+  # successes and failures.
+  #
+  # @example Successful deletion of all tags
+  #   result = tag_delete.call('v1.0.0', 'v2.0.0')
+  #   result.success?            #=> true
+  #   result.deleted.map(&:name) #=> ['v1.0.0', 'v2.0.0']
+  #   result.not_deleted         #=> []
+  #
+  # @example Partial failure (some tags deleted, some not found)
+  #   result = tag_delete.call('v1.0.0', 'nonexistent', 'v2.0.0')
+  #   result.success?                    #=> false
+  #   result.deleted.map(&:name)         #=> ['v1.0.0', 'v2.0.0']
+  #   result.not_deleted.first.name          #=> 'nonexistent'
+  #   result.not_deleted.first.error_message #=> "tag 'nonexistent' not found."
+  #
+  # @see Git::TagInfo
+  #
+  # @see Git::TagDeleteFailure
+  #
+  # @see Git::Commands::Tag::Delete
+  #
+  # @api public
+  #
+  # @!attribute [r] deleted
+  #   Tags that were successfully deleted
+  #
+  #   @return [Array<Git::TagInfo>]
+  #
+  # @!attribute [r] not_deleted
+  #   Tags that could not be deleted, with the reason for each failure
+  #
+  #   @return [Array<Git::TagDeleteFailure>]
+  #
+  TagDeleteResult = Data.define(:deleted, :not_deleted) do
+    # Returns true if all requested tags were successfully deleted
+    #
+    # @example Check if the delete operation succeeded
+    #   result = tag_delete.call('v1.0.0')
+    #   if result.success?
+    #     puts "All tags deleted successfully"
+    #   else
+    #     puts "Some tags could not be deleted:"
+    #     result.not_deleted.each { |f| puts "  #{f.name}: #{f.error_message}" }
+    #   end
+    #
+    # @return [Boolean] true if no tags failed to delete, false otherwise
+    def success?
+      not_deleted.empty?
+    end
+  end
+end

data/lib/git/tag_info.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'time'
+
+require 'git/author_info'
+
+module Git
+  # Value object representing tag metadata from git tag output
+  #
+  # This is a lightweight, immutable data structure returned by tag listing
+  # 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: 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(
+  #     name: 'v1.0.0',
+  #     oid: nil,                   # no tag object exists
+  #     target_oid: 'def456abc789', # commit ID
+  #     objecttype: 'commit',
+  #     tagger: nil,
+  #     message: nil
+  #   )
+  #   info.lightweight?  #=> true
+  #   info.tagger        #=> nil
+  #
+  # @see Git::Repository::ObjectOperations#tag_list for the repository method
+  #   that returns these
+  #
+  # @see Git::Commands::Tag::List for the command that produces these
+  #
+  # @see Git::AuthorInfo for the nested tagger identity
+  #
+  # @api public
+  #
+  # @!attribute [r] name
+  #   @return [String] the tag name (e.g., 'v1.0.0')
+  #
+  # @!attribute [r] oid
+  #   The object ID of the tag object itself.
+  #
+  #   For annotated tags, this is the tag object's ID. For lightweight tags,
+  #   this is nil because lightweight tags are not objects in the git database.
+  #
+  #   @return [String, nil] the tag object's ID, or nil for lightweight tags
+  #
+  # @!attribute [r] target_oid
+  #   The object ID of the commit this tag ultimately points to.
+  #
+  #   For both annotated and lightweight tags, this is the commit ID that the
+  #   tag resolves to (i.e., the dereferenced target).
+  #
+  #   @return [String] the commit ID this tag points to
+  #
+  # @!attribute [r] objecttype
+  #   @return [String] 'tag' for annotated tags, 'commit' for lightweight tags
+  #
+  # @!attribute [r] tagger
+  #   The identity of the person who created the tag object.
+  #
+  #   Lightweight tags have no tag object and therefore no tagger. The nested
+  #   `email` has no angle brackets and the nested `date` is a `Time`.
+  #
+  #   @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, :message) do
+    # @return [Boolean] true if this is an annotated tag (oid is present)
+    def annotated?
+      !oid.nil?
+    end
+
+    # @return [Boolean] true if this is a lightweight tag (oid is nil)
+    def lightweight?
+      oid.nil?
+    end
+  end
+end