git 5.3.0 → 5.4.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_info.rb

@@ -43,7 +43,8 @@ module Git
   #   info.lightweight?  #=> true
   #   info.tagger        #=> nil
   #
-  # @see Git::Tag for the full-featured tag object with operations
+  # @see Git::Repository::ObjectOperations#tag_list for the repository method
+  #   that returns these
   #
   # @see Git::Commands::Tag::List for the command that produces these
   #

data/lib/git/version.rb

@@ -4,7 +4,7 @@ module Git
   # The current gem version
   #
   # @return [String] the current gem version
-  VERSION = '5.3.0'
+  VERSION = '5.4.0'
 
   # Represents a git version with major, minor, and patch components
   #

data/lib/git/worktree.rb

@@ -12,6 +12,17 @@ module Git
   #   worktree.add
   #   worktree.remove
   #
+  # @deprecated Use {Git::Repository::WorktreeOperations#worktree_list} and the
+  #   path-based worktree operations on {Git::Repository} instead
+  #
+  #   {Git::Repository::WorktreeOperations#worktree_list} returns immutable
+  #   {Git::WorktreeInfo} value objects. Operations that lived on this class are
+  #   called on the repository with the worktree path instead (for example
+  #   {Git::Repository::WorktreeOperations#worktree_add} and
+  #   {Git::Repository::WorktreeOperations#worktree_remove}). {#gcommit},
+  #   {#add}, and {#remove} each emit a deprecation warning; the `dir`, `full`,
+  #   `to_s`, and `to_a` readers do not.
+  #
   # @api public
   #
   class Worktree
@@ -69,7 +80,19 @@ module Git
     # @raise [Git::FailedError] if git must resolve the commit and exits with a
     #   non-zero exit status
     #
+    # @deprecated Use {Git::WorktreeInfo#head} from
+    #   {Git::Repository::WorktreeOperations#worktree_list} instead
+    #
+    #   `head` is always the commit SHA as a `String` (or `nil` for a bare main
+    #   worktree). Call `repo.gcommit(info.head)` for the commit object.
+    #
+    # @see Git::WorktreeInfo#head
+    #
     def gcommit
+      Git::Deprecation.warn(
+        'Git::Worktree#gcommit is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::WorktreeInfo#head from Git::Repository#worktree_list instead.'
+      )
       @gcommit ||= worktree_repository.gcommit(@full)
       @gcommit
     end
@@ -87,7 +110,15 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_add} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_add
+    #
     def add
+      Git::Deprecation.warn(
+        'Git::Worktree#add is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_add instead.'
+      )
       worktree_repository.worktree_add(@dir, @gcommit)
     end
 
@@ -102,7 +133,15 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_remove} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_remove
+    #
     def remove
+      Git::Deprecation.warn(
+        'Git::Worktree#remove is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_remove instead.'
+      )
       worktree_repository.worktree_remove(@dir)
     end
 

data/lib/git/worktree_info.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object for one entry of `git worktree list`
+  #
+  # Each entry carries what `git worktree list --porcelain` reports for a
+  # worktree: its path, the checked-out HEAD and branch, and whether it is bare,
+  # detached, locked, or prunable, with the reason git gives for the last two.
+  #
+  # @example A locked linked worktree with a branch checked out
+  #   info = Git::WorktreeInfo.new(
+  #     path: '/tmp/wt/linked',
+  #     head: 'f3e2c1ffb860086504eeb27b77a1d0028b68fd8f',
+  #     branch: 'refs/heads/linked',
+  #     bare: false,
+  #     detached: false,
+  #     locked: true,
+  #     lock_reason: 'on purpose',
+  #     prunable: false,
+  #     prune_reason: nil
+  #   )
+  #
+  #   info.path         # => '/tmp/wt/linked'
+  #   info.head         # => 'f3e2c1ffb860086504eeb27b77a1d0028b68fd8f'
+  #   info.branch       # => 'refs/heads/linked'
+  #   info.locked?      # => true
+  #   info.lock_reason  # => 'on purpose'
+  #   info.detached?    # => false
+  #   info.to_s         # => '/tmp/wt/linked'
+  #
+  # @example Pass an entry back to a worktree operation
+  #   info = repo.worktree_list.find { |w| w.branch == 'refs/heads/linked' }
+  #   repo.worktree_remove(info)
+  #
+  # @see Git::Repository::WorktreeOperations#worktree_list for the repository
+  #   method that returns these
+  #
+  # @api public
+  #
+  # @!attribute [r] path
+  #   @return [String] the worktree directory as git reports it
+  #
+  # @!attribute [r] head
+  #   @return [String, nil] the full object ID of the checked-out HEAD commit
+  #     (the all-zero object ID when the branch has no commits yet), or nil for a
+  #     bare main worktree
+  #
+  # @!attribute [r] branch
+  #   @return [String, nil] the full refname of the checked-out branch (e.g.,
+  #     'refs/heads/main'), or nil when the worktree is bare or detached
+  #
+  # @!attribute [r] bare
+  #   @return [Boolean] true if this is the main worktree of a bare repository
+  #
+  # @!attribute [r] detached
+  #   @return [Boolean] true if HEAD is detached in this worktree
+  #
+  # @!attribute [r] locked
+  #   @return [Boolean] true if the worktree is locked
+  #
+  # @!attribute [r] lock_reason
+  #   @return [String, nil] the reason given when the worktree was locked, or nil
+  #     when it is not locked or was locked without a reason
+  #
+  # @!attribute [r] prunable
+  #   @return [Boolean] true if `git worktree prune` would remove this entry
+  #
+  # @!attribute [r] prune_reason
+  #   @return [String, nil] git's explanation of why the entry is prunable, or
+  #     nil when it is not prunable
+  #
+  WorktreeInfo = Data.define(
+    :path,
+    :head,
+    :branch,
+    :bare,
+    :detached,
+    :locked,
+    :lock_reason,
+    :prunable,
+    :prune_reason
+  ) do
+    # Whether this is the main worktree of a bare repository
+    #
+    # @example
+    #   info.bare? # => false
+    #
+    # @return [Boolean] true if the worktree is bare
+    def bare? = bare
+
+    # Whether HEAD is detached in this worktree
+    #
+    # @example
+    #   info.detached? # => false
+    #
+    # @return [Boolean] true if HEAD is detached
+    def detached? = detached
+
+    # Whether the worktree is locked
+    #
+    # @example
+    #   info.locked? # => true
+    #
+    # @return [Boolean] true if the worktree is locked
+    def locked? = locked
+
+    # Whether `git worktree prune` would remove this entry
+    #
+    # @example
+    #   info.prunable? # => false
+    #
+    # @return [Boolean] true if the entry is prunable
+    def prunable? = prunable
+
+    # Returns the worktree path
+    #
+    # Lets an entry be passed directly to the worktree operations that take a
+    # path, such as {Git::Repository::WorktreeOperations#worktree_remove}.
+    #
+    # @example Convert to string
+    #   info.to_s # => '/tmp/wt/linked'
+    #
+    # @return [String] the worktree path
+    def to_s
+      path
+    end
+  end
+end

data/lib/git/worktrees.rb

@@ -10,6 +10,15 @@ module Git
   #   worktrees = repo.worktrees
   #   worktrees.each { |wt| puts wt.dir }
   #
+  # @deprecated Use {Git::Repository::WorktreeOperations#worktree_list} instead
+  #
+  #   {Git::Repository::WorktreeOperations#worktree_list} returns
+  #   `Array<Git::WorktreeInfo>` (immutable value objects). Look a worktree up
+  #   by path with `worktree_list.find { |w| w.path == path }` in place of
+  #   {#[]}, and call {Git::Repository::WorktreeOperations#worktree_prune} in
+  #   place of {#prune}. Constructing a `Git::Worktrees` emits a deprecation
+  #   warning.
+  #
   # @api public
   #
   class Worktrees
@@ -24,12 +33,21 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_list} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_list
+    #
     def initialize(base)
+      Git::Deprecation.warn(
+        'Git::Worktrees is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_list instead.'
+      )
       @worktrees = {}
 
       @base = base
 
-      worktree_repository.worktrees_all.each do |w|
+      # worktrees_all is deprecated too; silence it so one Git::Worktrees.new emits one warning
+      Git::Deprecation.silence { worktree_repository.worktrees_all }.each do |w|
         @worktrees[w[0]] = Git::Worktree.new(@base, w[0], w[1])
       end
     end