git 5.2.0 → 5.4.0

data/lib/git/stashes.rb

@@ -3,12 +3,23 @@
 module Git
   # Collection of stash entries for a Git repository
   #
-  # @example Iterate over stash entries
+  # This class is deprecated and will be removed in v6.0.0. Use the
+  # {Git::Repository} stash methods and {Git::StashInfo} instead:
+  # {Git::Repository#stash_infos} replaces the collection, and
+  # {Git::Repository#stash_push}, {Git::Repository#stash_apply}, and
+  # {Git::Repository#stash_clear} replace {#save}, {#apply}, and {#clear}.
+  #
+  # @example Iterate over stash entries (deprecated)
   #   git.stashes.each { |s| puts s.message }
   #
-  # @example Check and apply a stash
-  #   git.stashes.size   #=> 2
-  #   git.stashes.apply
+  # @example The replacement
+  #   repo.stash_infos.each { |info| puts info.message }
+  #   repo.stash_infos.size   #=> 2
+  #   repo.stash_apply
+  #
+  # @deprecated Use {Git::Repository#stash_infos} and {Git::StashInfo} instead
+  #
+  # @see Git::Repository#stash_infos
   #
   # @api public
   #
@@ -18,6 +29,7 @@ module Git
     # Initialize the stashes collection
     #
     # Loads all existing stash entries from the repository at construction time.
+    # Emits one deprecation warning per object.
     #
     # @example Load stashes for a repository
     #   stashes = Git::Stashes.new(repo)
@@ -28,14 +40,20 @@ module Git
     # @return [void]
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @deprecated Use {Git::Repository#stash_infos} and {Git::StashInfo} instead
+    #
     def initialize(base)
+      Git::Deprecation.warn(
+        'Git::Stashes is deprecated and will be removed in v6.0.0. ' \
+        'Use the Git::Repository stash methods (stash_infos, stash_push, stash_apply, stash_clear) ' \
+        'and Git::StashInfo instead.'
+      )
       @stashes = []
       @base = base
-
-      stash_repository.stashes_all.each do |stash|
-        message = stash[1]
-        @stashes.unshift(Git::Stash.new(@base, message, existing: true))
-      end
+      # stashes_all and Git::Stash are deprecated too; silence them so one
+      # Git::Stashes.new emits one warning
+      Git::Deprecation.silence { load_stashes }
     end
 
     # Returns all stash entries as an array of index and message pairs
@@ -51,7 +69,8 @@ module Git
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
     def all
-      stash_repository.stashes_all
+      # stashes_all is deprecated too; silence it so this call emits no second warning
+      Git::Deprecation.silence { stash_repository.stashes_all }
     end
 
     # Saves the current working-directory state to a new stash entry
@@ -65,8 +84,10 @@ module Git
     # @return [void]
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def save(message)
-      s = Git::Stash.new(@base, message)
+      # Git::Stash is deprecated too; silence it so this call emits no second warning
+      s = Git::Deprecation.silence { Git::Stash.new(@base, message) }
       @stashes.unshift(s) if s.saved?
     end
 
@@ -83,6 +104,7 @@ module Git
     # @return [String] the output from the git stash apply command
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def apply(index = nil)
       stash_repository.stash_apply(index)
     end
@@ -96,6 +118,7 @@ module Git
     # @return [void]
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def clear
       stash_repository.stash_clear
       @stashes = []
@@ -108,6 +131,7 @@ module Git
     #   git.stashes.size  #=> 2
     #
     # @return [Integer] the number of stashes
+    #
     def size
       @stashes.size
     end
@@ -145,12 +169,24 @@ module Git
     # @param index [Integer, #to_i] the stash index (0 = most recent)
     #
     # @return [Git::Stash, nil] the stash entry, or `nil` if the index is out of bounds
+    #
     def [](index)
       @stashes[index.to_i]
     end
 
     private
 
+    # Wraps every entry from the repository in a Git::Stash, newest first
+    #
+    # @return [void]
+    #
+    def load_stashes
+      stash_repository.stashes_all.each do |stash|
+        message = stash[1]
+        @stashes.unshift(Git::Stash.new(@base, message, existing: true))
+      end
+    end
+
     # Returns the facade interface for stash operations
     #
     # @return [Git::Repository]

data/lib/git/status.rb

@@ -13,6 +13,9 @@ module Git
   #   status.deleted.each { |path, _file| puts "Deleted: #{path}" }
   #   status.untracked.each { |path, _file| puts "Untracked: #{path}" }
   #
+  # @deprecated Use {Git::StatusInfo}, returned by {Git::Repository#status_info},
+  #   instead; this class will be removed in v6.0.0
+  #
   # @api public
   #
   class Status
@@ -22,7 +25,15 @@ module Git
     #
     # @param base [Git::Repository] the git object backing this status
     #
+    # @deprecated Use {Git::Repository#status_info} instead
+    #
     def initialize(base)
+      if defined?(Git::Deprecation)
+        Git::Deprecation.warn(
+          'Git::Status is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#status_info instead.'
+        )
+      end
       @base = base
       # The factory returns a hash of file paths to StatusFile objects.
       @files = StatusFileFactory.new(base).construct_files
@@ -204,6 +215,9 @@ module Git
     # Represents a single file's status in the git repository. Each instance
     # holds information about a file's state in the index and working tree.
     #
+    # @deprecated Use {Git::StatusFileInfo}, held by {Git::StatusInfo#files},
+    #   instead; this class will be removed in v6.0.0
+    #
     # @api public
     #
     class StatusFile

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