git 5.3.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/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