git 5.2.0 → 5.4.0

data/lib/git/repository/status_operations.rb

@@ -2,8 +2,11 @@
 
 require 'git/commands/ls_files'
 require 'git/commands/rev_parse'
+require 'git/commands/status'
 require 'git/escaped_path'
+require 'git/parsers/status'
 require 'git/status'
+require 'git/status_info'
 
 module Git
   class Repository
@@ -87,6 +90,47 @@ module Git
         ).stdout.split("\n").map { |f| Private.unescape_quoted_path(f) }
       end
 
+      # Returns a {Git::StatusInfo} describing the index and working tree state
+      #
+      # Runs `git status` in porcelain v2 format with NUL-separated entries and
+      # every untracked file listed individually, then reads `core.ignoreCase`
+      # as a boolean so that the path predicates on the result compare paths the
+      # way git does in this repository. Every entry type git reports is
+      # represented, including renames, copies, and merge conflicts. Clean
+      # tracked paths are not reported by `git status`, so they are absent from
+      # the result; the deprecated {#status} listed them, and {#ls_files} still
+      # does.
+      #
+      # @example Check which files are modified
+      #   repo.status_info.changed
+      #   #=> { "lib/foo.rb" => #<data Git::StatusFileInfo path="lib/foo.rb", ...> }
+      #
+      # @example Check for untracked files
+      #   repo.status_info.untracked.keys #=> ["new_file.rb"]
+      #
+      # @example Check one path
+      #   repo.status_info.changed?('lib/foo.rb') #=> true
+      #
+      # @example Iterate over every entry
+      #   repo.status_info.files.each do |file|
+      #     puts "#{file.index_status}#{file.worktree_status} #{file.path}"
+      #   end
+      #
+      # @return [Git::StatusInfo] the status of the repository
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-status git-status
+      #
+      def status_info
+        result = Git::Commands::Status.new(@execution_context).call(
+          porcelain: 'v2', z: true, untracked_files: 'all'
+        )
+        files = Git::Parsers::Status.parse(result.stdout)
+        ignore_case = config_get('core.ignoreCase', type: 'bool')&.value == 'true'
+        Git::StatusInfo.new(files: files, ignore_case: ignore_case)
+      end
+
       # Returns a {Git::Status} object describing the working tree and index state
       #
       # Constructs a {Git::Status} for this repository by collecting information from
@@ -95,22 +139,26 @@ module Git
       # result identifies which files have been modified, added, deleted, or are
       # untracked.
       #
-      # @example Check which files are modified
-      #   repo.status.changed #=> { "lib/foo.rb" => <Git::Status::StatusFile ...> }
-      #
-      # @example Check for untracked files
-      #   repo.status.untracked #=> { "new_file.rb" => <Git::Status::StatusFile ...> }
+      # Emits one deprecation warning per call. The {Git::Status} it constructs is
+      # built with warnings silenced so the caller does not see a second one.
       #
-      # @example Iterate over all status files
-      #   repo.status.each { |file| puts "#{file.path}: #{file.type}" }
+      # @example Check which files are modified (deprecated; use status_info)
+      #   repo.status.changed.keys      #=> ["lib/foo.rb"]
+      #   repo.status_info.changed.keys #=> ["lib/foo.rb"]
       #
       # @return [Git::Status] the status of the repository
       #
       # @raise [Git::FailedError] if any underlying git command exits with a
       #   non-zero exit status
       #
+      # @deprecated Use {#status_info} instead
+      #
       def status
-        Git::Status.new(self)
+        Git::Deprecation.warn(
+          'Git::Repository#status is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#status_info instead.'
+        )
+        Git::Deprecation.silence { Git::Status.new(self) }
       end
 
       # List all files tracked in the index

data/lib/git/repository/worktree_operations.rb

@@ -1,22 +1,55 @@
 # frozen_string_literal: true
 
 require 'git/commands/worktree'
+require 'git/parsers/worktree'
 require 'git/worktree'
+require 'git/worktree_info'
 require 'git/worktrees'
 
 module Git
   class Repository
-    # Facade methods for worktree operations
+    # Facade methods for worktree operations: listing, adding, removing, moving,
+    # locking, repairing, and pruning worktrees
     #
     # Included by {Git::Repository}.
     #
     # @api private
     #
     module WorktreeOperations
+      # Returns every worktree attached to the repository
+      #
+      # Lists the main worktree first, then each linked worktree, in the order
+      # git reports them. The main worktree of a bare repository is included
+      # with {Git::WorktreeInfo#bare?} true and no head or branch.
+      #
+      # @example List all worktrees
+      #   repo.worktree_list.map(&:path)
+      #   #=> ["/path/to/main", "/tmp/feature"]
+      #
+      # @example Find the worktree that has a branch checked out
+      #   info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
+      #   info.path     #=> "/tmp/feature"
+      #   info.head     #=> "b8c63202c3c0ebd37b7e45fd0c22e6c20d5bead1"
+      #   info.locked?  #=> false
+      #
+      # @return [Array<Git::WorktreeInfo>] one entry per worktree
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @raise [Git::UnexpectedResultError] if the worktree listing cannot be
+      #   parsed
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_list
+        result = Git::Commands::Worktree::List.new(@execution_context).call(porcelain: true)
+        Git::Parsers::Worktree.parse_list(result.stdout)
+      end
+
       # Returns all worktrees as an array of directory and SHA pairs
       #
-      # Lists all worktrees attached to the repository, including the main
-      # worktree and all linked worktrees.
+      # Lists the main worktree and all linked worktrees. The main worktree of
+      # a bare repository has no checked-out commit and is omitted.
       #
       # @example List all worktrees
       #   repo.worktrees_all
@@ -30,20 +63,22 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use {#worktree_list} instead
+      #
+      #   {#worktree_list} returns one {Git::WorktreeInfo} per worktree, with
+      #   `path` and `head` in place of the pair, and includes the main worktree
+      #   of a bare repository.
+      #
+      # @see #worktree_list
+      #
       # @see https://git-scm.com/docs/git-worktree git-worktree documentation
       #
       def worktrees_all
-        worktree_entries = []
-        current_directory = ''
-        command_output = Git::Commands::Worktree::List.new(@execution_context).call(porcelain: true).stdout
-
-        command_output.each_line(chomp: true) do |line|
-          key, value = line.split(' ', 2)
-          current_directory = value if key == 'worktree'
-          worktree_entries << [current_directory, value] if key == 'HEAD'
-        end
-
-        worktree_entries
+        Git::Deprecation.warn(
+          'Git::Repository#worktrees_all is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#worktree_list instead.'
+        )
+        worktree_list.reject { |worktree| worktree.head.nil? }.map { |worktree| [worktree.path, worktree.head] }
       end
 
       # Create a new linked worktree at the given directory
@@ -75,10 +110,15 @@ module Git
 
       # Remove a linked worktree
       #
-      # @example Remove a worktree
+      # @example Remove a worktree by path
       #   repo.worktree_remove('/tmp/feature')
       #
-      # @param dir [String] filesystem path of the worktree to remove
+      # @example Remove a worktree from the list
+      #   info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
+      #   repo.worktree_remove(info)
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   remove, or its entry from {#worktree_list}
       #
       # @return [String] the output from the git worktree remove command
       #   (typically empty)
@@ -87,8 +127,120 @@ module Git
       #
       # @see https://git-scm.com/docs/git-worktree git-worktree documentation
       #
-      def worktree_remove(dir)
-        Git::Commands::Worktree::Remove.new(@execution_context).call(dir).stdout
+      def worktree_remove(worktree)
+        Git::Commands::Worktree::Remove.new(@execution_context).call(worktree.to_s).stdout
+      end
+
+      # Move a linked worktree to a new location
+      #
+      # @example Move a worktree
+      #   repo.worktree_move('/tmp/feature', '/tmp/feature-moved')
+      #
+      # @example Move a locked worktree
+      #   repo.worktree_move('/tmp/feature', '/tmp/feature-moved', force: 2)
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   move, or its entry from {#worktree_list}
+      #
+      # @param new_path [String] the destination path
+      #
+      # @param opts [Hash] options for the move
+      #
+      # @option opts [Boolean, Integer, nil] :force (nil) override git's
+      #   safeguards; git refuses to move a locked worktree unless the flag is
+      #   given twice, so pass `2` for that
+      #
+      # @return [String] the output from the git worktree move command
+      #   (typically empty)
+      #
+      # @raise [ArgumentError] if unsupported options are provided
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_move(worktree, new_path, opts = {})
+        Git::Commands::Worktree::Move.new(@execution_context).call(worktree.to_s, new_path, **opts).stdout
+      end
+
+      # Lock a linked worktree so that `git worktree prune` leaves it alone
+      #
+      # Lock a worktree whose directory is on removable media or a network
+      # share that is not always mounted.
+      #
+      # @example Lock a worktree
+      #   repo.worktree_lock('/tmp/feature')
+      #
+      # @example Lock a worktree with a reason
+      #   repo.worktree_lock('/tmp/feature', reason: 'on an external drive')
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   lock, or its entry from {#worktree_list}
+      #
+      # @param opts [Hash] options for the lock
+      #
+      # @option opts [String, nil] :reason (nil) an explanation stored with the
+      #   lock and reported as {Git::WorktreeInfo#lock_reason}
+      #
+      # @return [String] the output from the git worktree lock command
+      #   (typically empty)
+      #
+      # @raise [ArgumentError] if unsupported options are provided
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_lock(worktree, opts = {})
+        Git::Commands::Worktree::Lock.new(@execution_context).call(worktree.to_s, **opts).stdout
+      end
+
+      # Unlock a linked worktree
+      #
+      # @example Unlock a worktree
+      #   repo.worktree_unlock('/tmp/feature')
+      #
+      # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
+      #   unlock, or its entry from {#worktree_list}
+      #
+      # @return [String] the output from the git worktree unlock command
+      #   (typically empty)
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_unlock(worktree)
+        Git::Commands::Worktree::Unlock.new(@execution_context).call(worktree.to_s).stdout
+      end
+
+      # Repair the links between the repository and its linked worktrees
+      #
+      # With no paths, repairs the link from each linked worktree back to the
+      # repository, which is needed after the repository directory was moved.
+      # Given the current paths of linked worktrees that were moved without
+      # {#worktree_move}, also repairs the repository's links to them.
+      #
+      # @example Repair after the repository directory was moved
+      #   repo.worktree_repair
+      #
+      # @example Repair after a linked worktree was moved by hand
+      #   repo.worktree_repair('/new/path/to/feature')
+      #
+      # @param paths [Array<String, Git::WorktreeInfo>] the current paths of the
+      #   worktrees to repair, or their entries from {#worktree_list}
+      #
+      # @return [String] the output from the git worktree repair command, which
+      #   reports each repair made
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @raise [Git::VersionError] if the installed git is older than 2.29.0
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      def worktree_repair(*paths)
+        Git::Commands::Worktree::Repair.new(@execution_context).call(*paths.map(&:to_s)).stdout
       end
 
       # Prune stale worktree administrative files
@@ -128,7 +280,22 @@ module Git
       #
       # @return [Git::Worktree] a worktree domain object for the given path
       #
+      # @deprecated Use {#worktree_add} and {#worktree_remove} instead
+      #
+      #   `repo.worktree(dir, commitish).add` becomes
+      #   `repo.worktree_add(dir, commitish)` and `repo.worktree(dir).remove`
+      #   becomes `repo.worktree_remove(dir)`. Read a worktree's checked-out
+      #   commit from {Git::WorktreeInfo#head} via {#worktree_list}.
+      #
+      # @see #worktree_add
+      #
+      # @see #worktree_remove
+      #
       def worktree(dir, commitish = nil)
+        Git::Deprecation.warn(
+          'Git::Repository#worktree is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#worktree_add and Git::Repository#worktree_remove instead.'
+        )
         Git::Worktree.new(self, dir, commitish)
       end
 
@@ -151,7 +318,20 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use {#worktree_list} instead
+      #
+      #   {#worktree_list} returns `Array<Git::WorktreeInfo>`. Look a worktree up
+      #   by path with `worktree_list.find { |w| w.path == path }` in place of
+      #   `worktrees[path]`, and call {#worktree_prune} in place of
+      #   `worktrees.prune`. Calling this method emits one deprecation warning.
+      #
+      # @see #worktree_list
+      #
       def worktrees
+        Git::Deprecation.warn(
+          'Git::Repository#worktrees is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#worktree_list instead.'
+        )
         Git::Worktrees.new(self)
       end
     end

data/lib/git/stash.rb

@@ -3,11 +3,25 @@
 module Git
   # Represents a single stash entry in a Git repository
   #
-  # @example Create a stash and inspect the result
+  # 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_push} replaces `Git::Stash.new(repo, message)` and
+  # returns a {Git::StashInfo}, or `nil` when there was nothing to stash.
+  #
+  # @example Create a stash and inspect the result (deprecated)
   #   stash = Git::Stash.new(repo, 'WIP: feature work')
   #   stash.message  #=> "WIP: feature work"
   #   stash.saved?   #=> true
   #
+  # @example The replacement
+  #   info = repo.stash_push(message: 'WIP: feature work')
+  #   info.message   #=> "On main: WIP: feature work"
+  #   info.nil?      #=> false
+  #
+  # @deprecated Use {Git::Repository#stash_push} and {Git::StashInfo} instead
+  #
+  # @see Git::Repository#stash_push
+  #
   # @api public
   #
   class Stash
@@ -16,6 +30,8 @@ module Git
     # When `existing` is `false` (the default), immediately calls {#save} to push
     # the current working-directory state onto the stash stack.
     #
+    # Emits one deprecation warning per object.
+    #
     # @example Create a new stash entry
     #   stash = Git::Stash.new(repo, 'WIP: feature work')
     #   stash.saved?  #=> true
@@ -32,7 +48,15 @@ module Git
     #   without pushing any changes
     #
     # @return [void]
+    #
+    # @deprecated Use {Git::Repository#stash_push} and {Git::StashInfo} instead
+    #
     def initialize(base, message, existing: false)
+      Git::Deprecation.warn(
+        'Git::Stash is deprecated and will be removed in v6.0.0. ' \
+        'Use the Git::Repository stash methods (stash_push, stash_infos, stash_apply) ' \
+        'and Git::StashInfo instead.'
+      )
       @base = base
       @message = message
       save unless existing
@@ -48,8 +72,10 @@ module Git
     #   local changes to save
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def save
-      @saved = stash_repository.stash_save(@message)
+      # stash_save is deprecated too; silence it so one Git::Stash call emits one warning
+      @saved = Git::Deprecation.silence { stash_repository.stash_save(@message) }
     end
 
     # Returns whether the stash was saved successfully
@@ -60,6 +86,7 @@ module Git
     #
     # @return [Boolean, nil] `true` if changes were stashed, `false` if there were no
     #   local changes, `nil` if {#save} has not been called (e.g. `existing: true`)
+    #
     def saved?
       @saved
     end
@@ -71,6 +98,7 @@ module Git
     #   stash.message  #=> "WIP: feature work"
     #
     # @return [String] the stash message
+    #
     attr_reader :message
 
     # Returns the stash description as a string
@@ -80,6 +108,7 @@ module Git
     #   stash.to_s  #=> "WIP: feature work"
     #
     # @return [String] the stash message
+    #
     def to_s
       message
     end

data/lib/git/stash_info.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
+require 'time'
+
+require 'git/author_info'
+
 module Git
   # Immutable value object representing stash entry information
   #
   # StashInfo encapsulates the parsed data from `git stash list` output.
   # Each entry contains comprehensive information about the stash including
-  # its index, reference name, commit SHA, branch, message, author/committer
-  # details, and timestamps.
+  # its index, reference name, commit SHA, branch, message, and the author and
+  # committer identities.
   #
+  # The author and committer are nested {Git::AuthorInfo} values. Their `date`
+  # is a `Time` parsed from git's ISO 8601 output, not an ISO 8601 string.
   #
   # @example Create a StashInfo from parsed stash list output
   #   info = Git::StashInfo.new(
@@ -17,12 +23,16 @@ module Git
   #     short_oid: 'abc123d',
   #     branch: 'main',
   #     message: 'WIP on main: abc123 Initial commit',
-  #     author_name: 'Jane Doe',
-  #     author_email: 'jane@example.com',
-  #     author_date: '2026-01-24T10:30:00-08:00',
-  #     committer_name: 'Jane Doe',
-  #     committer_email: 'jane@example.com',
-  #     committer_date: '2026-01-24T10:30:00-08:00'
+  #     author: Git::AuthorInfo.new(
+  #       name: 'Jane Doe',
+  #       email: 'jane@example.com',
+  #       date: Time.iso8601('2026-01-24T10:30:00-08:00')
+  #     ),
+  #     committer: Git::AuthorInfo.new(
+  #       name: 'Jane Doe',
+  #       email: 'jane@example.com',
+  #       date: Time.iso8601('2026-01-24T10:30:00-08:00')
+  #     )
   #   )
   #
   #   info.index           # => 0
@@ -31,12 +41,12 @@ module Git
   #   info.short_oid       # => 'abc123d'
   #   info.branch          # => 'main'
   #   info.message         # => 'WIP on main: abc123 Initial commit'
-  #   info.author_name     # => 'Jane Doe'
-  #   info.author_email    # => 'jane@example.com'
-  #   info.author_date     # => '2026-01-24T10:30:00-08:00'
-  #   info.committer_name  # => 'Jane Doe'
-  #   info.committer_email # => 'jane@example.com'
-  #   info.committer_date  # => '2026-01-24T10:30:00-08:00'
+  #   info.author.name     # => 'Jane Doe'
+  #   info.author.email    # => 'jane@example.com'
+  #   info.author.date     # => 2026-01-24 10:30:00 -0800
+  #   info.committer.name  # => 'Jane Doe'
+  #
+  # @see Git::AuthorInfo for the nested author and committer identities
   #
   # @api public
   #
@@ -59,23 +69,15 @@ module Git
   # @!attribute [r] message
   #   @return [String] the stash message (e.g., 'WIP on main: abc123 commit msg')
   #
-  # @!attribute [r] author_name
-  #   @return [String] the name of the stash author
-  #
-  # @!attribute [r] author_email
-  #   @return [String] the email of the stash author
-  #
-  # @!attribute [r] author_date
-  #   @return [String] the author date in ISO 8601 format
+  # @!attribute [r] author
+  #   The identity of the stash author; the nested `date` is a `Time`.
   #
-  # @!attribute [r] committer_name
-  #   @return [String] the name of the stash committer
+  #   @return [Git::AuthorInfo] the author of the stash commit
   #
-  # @!attribute [r] committer_email
-  #   @return [String] the email of the stash committer
+  # @!attribute [r] committer
+  #   The identity of the stash committer; the nested `date` is a `Time`.
   #
-  # @!attribute [r] committer_date
-  #   @return [String] the committer date in ISO 8601 format
+  #   @return [Git::AuthorInfo] the committer of the stash commit
   #
   StashInfo = Data.define(
     :index,
@@ -84,12 +86,8 @@ module Git
     :short_oid,
     :branch,
     :message,
-    :author_name,
-    :author_email,
-    :author_date,
-    :committer_name,
-    :committer_email,
-    :committer_date
+    :author,
+    :committer
   ) do
     # Returns the stash reference name
     #