git 5.7.0 → 6.0.0

data/lib/git/repository/stashing.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'git/commands/rev_parse'
 require 'git/commands/stash'
 require 'git/parsers/stash'
 require 'git/repository/shared_private'
@@ -9,7 +10,7 @@ module Git
     # Facade methods for stash operations
     #
     # Each method maps onto a `git stash` subcommand. Methods that identify or
-    # create a stash entry ({#stash_infos}, {#stash_push}, {#stash_store}) return
+    # create a stash entry ({#stash_list}, {#stash_push}, {#stash_store}) return
     # {Git::StashInfo} values; methods that only change or display the stash
     # return git's stdout. Every method that takes a stash ({#stash_apply},
     # {#stash_pop}, {#stash_drop}, {#stash_show}, {#stash_branch}) accepts a
@@ -19,9 +20,6 @@ module Git
     # `repo.stash_apply(index: true)` and `repo.stash_apply(nil, opts)` with a
     # stored `opts` Hash both work.
     #
-    # {#stashes_all}, {#stash_save}, and {#stash_list} are the legacy surface.
-    # They are deprecated and will be removed in v6.0.0.
-    #
     # Included by {Git::Repository}.
     #
     # @api private
@@ -33,10 +31,10 @@ module Git
       # `stash@{0}`, the most recent entry.
       #
       # @example List stash entries (newest first)
-      #   repo.stash_infos.map(&:name) #=> ["stash@{0}", "stash@{1}"]
+      #   repo.stash_list.map(&:name) #=> ["stash@{0}", "stash@{1}"]
       #
       # @example Apply the oldest entry
-      #   repo.stash_apply(repo.stash_infos.last)
+      #   repo.stash_apply(repo.stash_list.last)
       #
       # @return [Array<Git::StashInfo>] the stash entries, newest first; empty
       #   when there are none
@@ -45,11 +43,16 @@ module Git
       #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
-      def stash_infos
+      def stash_list
         result = Git::Commands::Stash::List.new(@execution_context).call
         Git::Parsers::Stash.parse_list(result.stdout)
       end
 
+      # Alias for {#stash_list}
+      #
+      # @see #stash_list
+      alias stash_infos stash_list
+
       # Option keys accepted by {#stash_push}
       STASH_PUSH_ALLOWED_OPTS = %i[
         patch p staged S keep_index k no_keep_index quiet q include_untracked u all a
@@ -88,10 +91,9 @@ module Git
       #   @option options [Boolean, nil] :p (nil) alias for `:patch`
       #
       #   @option options [Boolean, nil] :staged (nil) stash only the staged changes
-      #     (alias: `:S`; requires git 2.35+)
+      #     (alias: `:S`)
       #
-      #   @option options [Boolean, nil] :S (nil) alias for `:staged` (requires git
-      #     2.35+)
+      #   @option options [Boolean, nil] :S (nil) alias for `:staged`
       #
       #   @option options [Boolean, nil] :keep_index (nil) keep the staged changes
       #     in the index (alias: `:k`)
@@ -138,9 +140,9 @@ module Git
       def stash_push(*pathspec)
         pathspec, opts = Private.split_pathspec_and_opts(pathspec)
         SharedPrivate.assert_valid_opts!(STASH_PUSH_ALLOWED_OPTS, **opts)
-        previous_count = stash_infos.size
+        previous_count = stash_list.size
         Git::Commands::Stash::Push.new(@execution_context).call(*pathspec, **opts)
-        entries = stash_infos
+        entries = stash_list
         entries.first if entries.size > previous_count
       end
 
@@ -153,8 +155,8 @@ module Git
       # @example Apply the most recent entry
       #   repo.stash_apply #=> "On branch main\nChanges not staged for commit:..."
       #
-      # @example Apply an entry from {#stash_infos}
-      #   repo.stash_apply(repo.stash_infos.last)
+      # @example Apply an entry from {#stash_list}
+      #   repo.stash_apply(repo.stash_list.last)
       #
       # @example Apply an entry by name and restore the index too
       #   repo.stash_apply('stash@{1}', index: true)
@@ -179,6 +181,11 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note If git exits non-zero, nothing is unwound: whatever git applied stays
+      #   in the working tree and index, including untracked files restored from
+      #   the entry even when git refused to touch the tracked files, and on a
+      #   conflict the conflicted paths are left for the caller to resolve.
+      #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
       def stash_apply(stash = nil, opts = {})
@@ -196,8 +203,8 @@ module Git
       # @example Pop the most recent entry
       #   repo.stash_pop #=> "On branch main\n...Dropped refs/stash@{0} (abc1234...)"
       #
-      # @example Pop an entry from {#stash_infos}
-      #   repo.stash_pop(repo.stash_infos.last)
+      # @example Pop an entry from {#stash_list}
+      #   repo.stash_pop(repo.stash_list.last)
       #
       # @param stash [Git::StashInfo, String, Integer, nil] the entry to pop: a
       #   {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the most
@@ -219,6 +226,10 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note If git exits non-zero, nothing is unwound, as described at
+      #   {#stash_apply}, and the entry is kept in the stash list rather than
+      #   dropped.
+      #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
       def stash_pop(stash = nil, opts = {})
@@ -236,8 +247,8 @@ module Git
       # @example Drop the most recent entry
       #   repo.stash_drop #=> "Dropped refs/stash@{0} (abc1234...)"
       #
-      # @example Drop an entry from {#stash_infos}
-      #   repo.stash_drop(repo.stash_infos.last)
+      # @example Drop an entry from {#stash_list}
+      #   repo.stash_drop(repo.stash_list.last)
       #
       # @param stash [Git::StashInfo, String, Integer, nil] the entry to drop: a
       #   {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the most
@@ -279,8 +290,8 @@ module Git
       # @example Show the diffstat of the most recent entry
       #   repo.stash_show #=> " file.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)"
       #
-      # @example Show the full patch of an entry from {#stash_infos}
-      #   repo.stash_show(repo.stash_infos.last, patch: true)
+      # @example Show the full patch of an entry from {#stash_list}
+      #   repo.stash_show(repo.stash_list.last, patch: true)
       #
       # @param stash [Git::StashInfo, String, Integer, nil] the entry to show: a
       #   {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the most
@@ -304,16 +315,15 @@ module Git
       # @option opts [Integer, String] :U (nil) alias for `:unified`
       #
       # @option opts [Boolean, nil] :include_untracked (nil) include the
-      #   untracked files recorded in the entry (alias: `:u`; requires git 2.30+)
+      #   untracked files recorded in the entry (alias: `:u`)
       #
       # @option opts [Boolean, nil] :u (nil) alias for `:include_untracked`
-      #   (requires git 2.30+)
       #
       # @option opts [Boolean, nil] :no_include_untracked (nil) exclude the
-      #   untracked files recorded in the entry (requires git 2.30+)
+      #   untracked files recorded in the entry
       #
       # @option opts [Boolean, nil] :only_untracked (nil) show only the
-      #   untracked files recorded in the entry (requires git 2.30+)
+      #   untracked files recorded in the entry
       #
       # @option opts [Boolean, Integer, nil] :find_renames (nil) detect
       #   renames, optionally with a similarity threshold (alias: `:M`)
@@ -356,8 +366,8 @@ module Git
       # @example Branch from the most recent entry
       #   repo.stash_branch('feature') #=> "Switched to a new branch 'feature'\n..."
       #
-      # @example Branch from an entry from {#stash_infos}
-      #   repo.stash_branch('feature', repo.stash_infos.last)
+      # @example Branch from an entry from {#stash_list}
+      #   repo.stash_branch('feature', repo.stash_list.last)
       #
       # @param branch_name [String] the name of the branch to create
       #
@@ -369,6 +379,10 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note If applying the entry fails, `branch_name` has already been created
+      #   and checked out, so the repository is left on it with whatever git could
+      #   apply in the working tree, and the entry stays in the stash list.
+      #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
       def stash_branch(branch_name, stash = nil)
@@ -407,7 +421,13 @@ module Git
 
       # Add a stash commit created by {#stash_create} to the stash list
       #
-      # The stash list is read after the store to return the new top entry.
+      # `commit` is resolved to the full object id of the commit with
+      # `git rev-parse` and that id is what is stored, so an annotated tag stores
+      # the tagged commit rather than the tag object (which `git stash store`
+      # accepts but `git stash list` cannot show). Because the id is what git
+      # sees, a failure from `git stash store` names the resolved id rather than
+      # the revision as it was given. The stash list is read after the store and
+      # the entry whose object id equals that id is returned.
       #
       # @example Store a stash commit
       #   oid = repo.stash_create
@@ -415,7 +435,17 @@ module Git
       #   info.name    #=> "stash@{0}"
       #   info.message #=> "saved for later"
       #
-      # @param commit [String] the object id of the stash commit to store
+      # @example Store a stash commit named by a ref
+      #   repo.stash_store('refs/tmp/wip').oid #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
+      #
+      # @param commit [String, #to_s] the stash commit to store, as any revision
+      #   that resolves to it
+      #
+      #   Full or abbreviated object ids, branch, tag, and other ref names,
+      #   `stash@{N}`, and `:/<text>` searches all resolve with `git rev-parse`,
+      #   and a {Git::StashInfo} resolves through its `#to_s`. A `:/<text>` search
+      #   finds only commits reachable from a ref, so it cannot name a commit from
+      #   {#stash_create} until that commit is stored or a ref points at it.
       #
       # @param opts [Hash] options for the store
       #
@@ -429,18 +459,34 @@ module Git
       #
       # @option opts [Boolean, nil] :q (nil) alias for `:quiet`
       #
-      # @return [Git::StashInfo] the stored entry, now at the top of the stash list
+      # @return [Git::StashInfo] the stored entry
       #
       # @raise [ArgumentError] if unsupported options are provided
       #
+      # @raise [ArgumentError] if `commit` is `nil` or starts with a hyphen or a
+      #   caret
+      #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @raise [Git::UnexpectedResultError] if the stash listing cannot be parsed
+      #   or does not contain the stored commit
+      #
+      #   The entry is missing when another process dropped or cleared it between
+      #   the store and the lookup.
+      #
+      # @note Storing the commit that is already at the top of the stash list
+      #   adds no entry: `git stash store` writes nothing to the `refs/stash`
+      #   reflog, any `:message` given is discarded, and the existing top entry
+      #   is returned.
+      #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
       def stash_store(commit, opts = {})
         SharedPrivate.assert_valid_opts!(STASH_STORE_ALLOWED_OPTS, **opts)
-        Git::Commands::Stash::Store.new(@execution_context).call(commit, **opts)
-        stash_infos.first
+        oid = Private.resolve_commit_oid(@execution_context, commit)
+        Git::Commands::Stash::Store.new(@execution_context).call(oid, **opts)
+        stash_list.find { |entry| entry.oid == oid } ||
+          raise(Git::UnexpectedResultError, "stash was stored but not found in the stash list: #{oid}")
       end
 
       # Remove all stash entries
@@ -462,105 +508,6 @@ module Git
         Git::Commands::Stash::Clear.new(@execution_context).call.stdout
       end
 
-      # Returns all stash entries as an array of index and message pairs
-      #
-      # Lists all stash entries in the repository ordered from oldest to newest.
-      # The index is a sequential number starting from 0 for the oldest stash. The
-      # message is the stash description with the leading branch prefix (e.g.
-      # `"On main:"` or `"WIP on main:"`) stripped.
-      #
-      # @example List all stashes (oldest first)
-      #   repo.stashes_all #=> [[0, "Fix bug"], [1, "Add feature"]]
-      #
-      # @return [Array<Array(Integer, String)>] array of `[index, message]` pairs
-      #   where index is the sequential position (0 is oldest) and message is the
-      #   stash description with the branch prefix stripped
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @note The sequential index returned here is **not** the same as git's
-      #   `stash@{N}` reference used by {#stash_apply}. In git, `stash@{0}` is the
-      #   **most recent** stash, while index `0` here is the **oldest**. To apply a
-      #   specific stash from this list, convert the entry's position to a git
-      #   reference: `'stash@{%d}' % (total - 1 - index)`, or pass the string
-      #   reference directly to {#stash_apply}.
-      #
-      # @deprecated Use {#stash_infos} instead. It returns {Git::StashInfo} entries
-      #   newest first with git's own `stash@{N}` indices and the full message.
-      #   This method will be removed in v6.0.0.
-      #
-      # @see #stash_infos
-      #
-      # @see https://git-scm.com/docs/git-stash git-stash documentation
-      #
-      def stashes_all
-        Git::Deprecation.warn(
-          'Git::Repository#stashes_all is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#stash_infos instead.'
-        )
-        stash_infos.reverse.each_with_index.map do |info, i|
-          message = info.message.sub(/^(?:WIP on|On)\s+[^:]+:\s*/, '')
-          [i, message]
-        end
-      end
-
-      # Returns stash entries as a formatted string matching `git stash list` output
-      #
-      # @example List stashes as a formatted string
-      #   repo.stash_list #=> "stash@{0}: On main: WIP\nstash@{1}: On feature: Fix bug"
-      #
-      # @return [String] newline-joined `"stash@{n}: <full message>"` entries, or an
-      #   empty string when there are no stashes; the format matches `git stash list`
-      #   output
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#stash_infos} instead and format the entries yourself:
-      #   `repo.stash_infos.map { |s| "#{s.name}: #{s.message}" }.join("\n")`.
-      #   This method will be removed in v6.0.0, and a later release will reuse
-      #   the name for a method returning `Array<Git::StashInfo>`.
-      #
-      # @see #stash_infos
-      #
-      # @see https://git-scm.com/docs/git-stash git-stash documentation
-      #
-      def stash_list
-        Git::Deprecation.warn(
-          'Git::Repository#stash_list is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#stash_infos instead.'
-        )
-        stash_infos.map { |info| "#{info.name}: #{info.message}" }.join("\n")
-      end
-
-      # Save the current working directory and index state to a new stash
-      #
-      # @example Save current changes
-      #   repo.stash_save('WIP: feature work') #=> true
-      #
-      # @param message [String] the stash message
-      #
-      # @return [Boolean] true if changes were stashed, false if there were no
-      #   local changes to save
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#stash_push} with the `:message` option instead. It
-      #   returns the new {Git::StashInfo}, or `nil` when there were no local
-      #   changes to save. This method will be removed in v6.0.0.
-      #
-      # @see #stash_push
-      #
-      # @see https://git-scm.com/docs/git-stash git-stash documentation
-      #
-      def stash_save(message) # rubocop:disable Naming/PredicateMethod
-        Git::Deprecation.warn(
-          'Git::Repository#stash_save is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#stash_push(message: ...) instead.'
-        )
-        result = Git::Commands::Stash::Push.new(@execution_context).call(message: message)
-        !result.stdout.include?('No local changes to save')
-      end
-
       # Private helpers local to {Git::Repository::Stashing}
       #
       # @api private
@@ -568,6 +515,55 @@ module Git
       module Private
         module_function
 
+        # Resolve a commit-ish to the full object id of the commit it names
+        #
+        # The revision is peeled with `git rev-parse --verify <commit>^{commit}`,
+        # so an annotated tag yields the tagged commit, an abbreviated or uppercase
+        # id yields the full lowercase id, and an id that names no object fails
+        # (a bare `--verify <id>` echoes a well-formed id back without looking it
+        # up). A `:/<text>` search consumes the rest of the revision string, so it
+        # is passed without the suffix; such a search only ever names a commit.
+        # {Git::Repository::ObjectOperations#rev_parse} is not used because it
+        # runs `--revs-only`, which prints both ends of a range and exits zero
+        # instead of failing.
+        #
+        # {Git::Commands::RevParse} places its operand after `--end-of-options`,
+        # so the arguments DSL does not reject a `nil` or option-like operand, and
+        # `--verify` accepts a negated revision such as `^HEAD` and prints the id
+        # back with its caret. This method raises `ArgumentError` for all three
+        # before running git.
+        #
+        # @example With an annotated tag
+        #   Private.resolve_commit_oid(execution_context, 'v1.0.0')
+        #   #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
+        #
+        # @example With a range
+        #   Private.resolve_commit_oid(execution_context, 'main..topic')
+        #   #=> raises Git::FailedError
+        #
+        # @param execution_context [Git::ExecutionContext] the context to run git in
+        #
+        # @param commit [String, #to_s] a revision that resolves to a commit or
+        #   peels to one
+        #
+        # @return [String] the full object id of the commit
+        #
+        # @raise [ArgumentError] if `commit` is `nil` or starts with a hyphen or a
+        #   caret
+        #
+        # @raise [Git::FailedError] when `commit` does not resolve to a single
+        #   revision or does not peel to a commit
+        #
+        def resolve_commit_oid(execution_context, commit)
+          raise ArgumentError, 'commit is required' if commit.nil?
+
+          commit = commit.to_s
+          raise ArgumentError, "Invalid commit: '#{commit}'" if commit.start_with?('-', '^')
+
+          revision = commit.start_with?(':/') ? commit : "#{commit}^{commit}"
+          Git::Commands::RevParse.new(execution_context).call(revision, verify: true).stdout.strip
+        end
+
         # Separate the stash operand from a positional options Hash
         #
         # The stash-taking facade methods are declared `(stash = nil, opts = {})`.

data/lib/git/repository/status_operations.rb

@@ -5,7 +5,6 @@ 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
@@ -46,27 +45,6 @@ module Git
         true
       end
 
-      # Returns `true` if the repository has no commits yet
-      #
-      # @example Check whether a repository is empty
-      #   repo.empty? #=> true   # freshly initialized, no commits yet
-      #   repo.empty? #=> false  # at least one commit exists
-      #
-      # @return [Boolean] `true` when the repository has no commits, `false` otherwise
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status other
-      #   than when the repository has no commits
-      #
-      # @deprecated Use {#no_commits?} instead
-      #
-      def empty?
-        Git::Deprecation.warn(
-          'Git::Repository#empty? is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#no_commits? instead.'
-        )
-        no_commits?
-      end
-
       # List all files in the working tree that are not tracked by git
       #
       # Runs `git ls-files --others --exclude-standard` from the working tree
@@ -98,8 +76,7 @@ module Git
       # 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.
+      # the result; {#ls_files} lists them.
       #
       # @example Check which files are modified
       #   repo.status_info.changed
@@ -131,36 +108,6 @@ module Git
         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
-      # `git ls-files --stage`, `git ls-files --others`, `git diff-files`, and
-      # `git diff-index HEAD` (the last only when at least one commit exists). The
-      # result identifies which files have been modified, added, deleted, or are
-      # untracked.
-      #
-      # 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 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::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
       #
       # Runs `git ls-files --stage` under the given `location` and returns a