git 5.6.0 → 6.0.0

data/lib/git/repository/object_operations.rb

@@ -17,6 +17,7 @@ require 'git/parsers/grep'
 require 'git/parsers/ls_tree'
 require 'git/parsers/tag'
 require 'git/repository/shared_private'
+require 'git/system_call_guard'
 require 'git/escaped_path'
 require 'tempfile'
 require 'zlib'
@@ -72,35 +73,34 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @raise [Git::Error] if a block is given and the object content cannot be
+      #   written to a temporary file
+      #
       # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
       #
-      def cat_file_contents(object)
+      def cat_file_contents(object, &block)
         raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
 
         return Git::Commands::CatFile::Raw.new(@execution_context).call(object, p: true).stdout unless block_given?
 
         # Stream git output directly to a tempfile to avoid buffering large
         # object content in memory when a block is given.
-        Tempfile.create do |file|
-          file.binmode
-          Git::Commands::CatFile::Raw.new(@execution_context).call(object, p: true, out: file)
-          file.rewind
-          yield file
+        Git::SystemCallGuard.call('Failed to write the object content to a temporary file') do |guard|
+          Tempfile.create do |file|
+            file.binmode
+            Git::Commands::CatFile::Raw.new(@execution_context).call(object, p: true, out: file)
+            file.rewind
+            guard.unguarded { block.call(file) }
+          end
         end
       end
 
-      # Alias for {#cat_file_contents}; retained for backward compatibility
+      # Alias for {#cat_file_contents}; kept as a legacy name and not scheduled
+      # for removal
       #
       # @see #cat_file_contents
       alias cat_file cat_file_contents
 
-      # Alias for {#cat_file_contents}
-      #
-      # @deprecated Use {#cat_file_contents} instead
-      #
-      # @see #cat_file_contents
-      alias object_contents cat_file_contents
-
       # Returns the size of a git object in bytes
       #
       # @example Get the size of a commit object
@@ -125,13 +125,6 @@ module Git
         Git::Commands::CatFile::Raw.new(@execution_context).call(object, s: true).stdout.chomp.to_i
       end
 
-      # Alias for {#cat_file_size}
-      #
-      # @deprecated Use {#cat_file_size} instead
-      #
-      # @see #cat_file_size
-      alias object_size cat_file_size
-
       # Returns the type of a git object
       #
       # @example Get the type of a commit reference
@@ -157,13 +150,6 @@ module Git
         Git::Commands::CatFile::Raw.new(@execution_context).call(object, t: true).stdout.chomp
       end
 
-      # Alias for {#cat_file_type}
-      #
-      # @deprecated Use {#cat_file_type} instead
-      #
-      # @see #cat_file_type
-      alias object_type cat_file_type
-
       # Returns parsed commit data for the given git object
       #
       # @example Get commit data for HEAD
@@ -200,13 +186,6 @@ module Git
         Git::Parsers::CatFile.parse_commit(result.stdout.split("\n"), object)
       end
 
-      # Alias for {#cat_file_commit}
-      #
-      # @deprecated Use {#cat_file_commit} instead
-      #
-      # @see #cat_file_commit
-      alias commit_data cat_file_commit
-
       # Returns parsed tag data for the given annotated tag object
       #
       # Does not work with lightweight tags. To list all annotated tags in a
@@ -256,13 +235,6 @@ module Git
         Git::Parsers::CatFile.parse_tag(tdata, object)
       end
 
-      # Alias for {#cat_file_tag}
-      #
-      # @deprecated Use {#cat_file_tag} instead
-      #
-      # @see #cat_file_tag
-      alias tag_data cat_file_tag
-
       # Resolve a revision specifier to its full object ID
       #
       # Passes the given revision specifier to `git rev-parse` and returns the
@@ -292,12 +264,14 @@ module Git
         Git::Commands::RevParse.new(@execution_context).call(objectish, '--', revs_only: true).stdout
       end
 
-      alias revparse rev_parse
-
       # Returns the SHA of a named tag
       #
       # Returns an empty string when the tag does not exist.
       #
+      # Reads the loose ref file under `refs/tags` directly when it exists and
+      # falls back to `git show-ref` otherwise, including when the file cannot
+      # be read.
+      #
       # @example Get the SHA of an existing tag
       #   repo.tag_sha('v1.0')
       #   #=> "abc1234567890abcdef1234567890abcdef123456"
@@ -315,9 +289,7 @@ module Git
       def tag_sha(tag_name)
         tags_dir = File.expand_path(File.join(@execution_context.git_dir, 'refs', 'tags'))
         head = File.expand_path(File.join(tags_dir, tag_name))
-        return File.read(head).chomp if head.start_with?("#{tags_dir}#{File::SEPARATOR}") && File.file?(head)
-
-        Private.show_ref_tag_sha(@execution_context, tag_name)
+        Private.loose_tag_sha(tags_dir, head) || Private.show_ref_tag_sha(@execution_context, tag_name)
       end
 
       # Returns all recursive entries for a given tree object
@@ -395,13 +367,6 @@ module Git
         Git::Commands::NameRev.new(@execution_context).call(commit_ish).stdout.split[1]
       end
 
-      # Alias for {#name_rev}
-      #
-      # @deprecated Use {#name_rev} instead
-      #
-      # @see #name_rev
-      alias namerev name_rev
-
       # Option keys accepted by {#ls_tree}
       LS_TREE_ALLOWED_OPTS = %i[recursive path].freeze
       private_constant :LS_TREE_ALLOWED_OPTS
@@ -621,20 +586,21 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @raise [Git::Error] if the archive file cannot be written or gzip
+      #   compression fails
+      #
+      # @note A failure leaves nothing behind: the staging and temporary files
+      #   are removed and an existing `file` is not replaced.
+      #
       # @see https://git-scm.com/docs/git-archive git-archive documentation
       #
       def archive(treeish, file = nil, opts = {})
         SharedPrivate.assert_valid_opts!(ARCHIVE_ALLOWED_OPTS, **opts)
         raise ArgumentError, "#{file.inspect} is a directory" if file && File.directory?(file)
 
-        tmp = Private.write_archive_tmp(@execution_context, treeish, opts, dest_dir: Private.staging_dir_for(file))
-        return tmp unless file
-
-        Private.atomic_replace(tmp, file)
-        file
-      rescue StandardError
-        FileUtils.rm_f(tmp) if tmp
-        raise
+        Git::SystemCallGuard.call('Failed to write the archive') do
+          Private.write_archive(@execution_context, treeish, file, opts)
+        end
       end
 
       # Returns a blob object for the given object reference
@@ -701,50 +667,6 @@ module Git
         Git::Object.new(self, objectish, 'tree')
       end
 
-      # Returns a tag object for the given tag name
-      #
-      # Returns a {Git::Object::Tag} for `tag_name`. The returned object is
-      # either an annotated or a lightweight tag depending on the underlying
-      # ref type.
-      #
-      # @example Get a tag object
-      #   repo.tag('v1.0')
-      #   #=> #<Git::Object::Tag name="v1.0" ...>
-      #
-      # @param tag_name [String] the name of the tag
-      #
-      # @return [Git::Object::Tag] the tag object
-      #
-      # @raise [Git::UnexpectedResultError] if `tag_name` does not name an
-      #   existing tag
-      #
-      # @raise [Git::FailedError] if the underlying `git show-ref` invocation
-      #   exits with an unexpected status (i.e., outside the allowed 0..1 range)
-      #
-      # @deprecated Use `tag_list(name).first` instead
-      #
-      #   {#tag_list} returns immutable {Git::TagInfo} value objects rather
-      #   than {Git::Object::Tag}. `tag_list(name).first` is `nil` when the tag
-      #   does not exist, where this method raises
-      #   {Git::UnexpectedResultError}. Call the corresponding
-      #   {Git::Repository} method (e.g. {#archive}, {#log}, {#diff},
-      #   {#cat_file_contents}) with `info.oid || info.target_oid` for
-      #   operations on a tag; that is the object this method's return value
-      #   pins at construction, so a later move of the tag does not redirect
-      #   it, whereas the tag name would. The
-      #   {Git::Object::Tag} constructor is deprecated too; this method
-      #   silences it so one call emits one warning.
-      #
-      # @see #tag_list
-      #
-      def tag(tag_name)
-        Git::Deprecation.warn(
-          'Git::Repository#tag is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#tag_list(name).first instead.'
-        )
-        Git::Deprecation.silence { Git::Object::Tag.new(self, tag_name) }
-      end
-
       # Returns the appropriate git object for the given object reference
       #
       # Runs `git cat-file -t` to determine the object type, then constructs
@@ -814,46 +736,7 @@ module Git
         Git::Parsers::Tag.parse_list(result.stdout)
       end
 
-      # Returns all tags in the repository as tag objects
-      #
-      # Runs `git tag --list` with a machine-readable format, parses the output,
-      # and returns a {Git::Object::Tag} for each tag name.
-      #
-      # @example List the names of all tags
-      #   repo.tags.map(&:name) #=> ["v1.0.0", "v2.0.0"]
-      #
-      # @example No tags exist
-      #   repo.tags #=> []
-      #
-      # @return [Array<Git::Object::Tag>] one tag object per tag in the
-      #   repository; empty when there are none
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#tag_list} instead
-      #
-      #   {#tag_list} returns `Array<Git::TagInfo>` (immutable value objects)
-      #   rather than `Array<Git::Object::Tag>`. Look a tag up by name with
-      #   `tag_list(name).first`, and call the corresponding {Git::Repository}
-      #   method (e.g. {#archive}, {#log}, {#diff}, {#cat_file_contents}) with
-      #   `info.oid || info.target_oid` for operations on a tag; that is the
-      #   object each returned {Git::Object::Tag} pins at construction, so a
-      #   later move of the tag does not redirect it, whereas the tag name
-      #   would. The {Git::Object::Tag}
-      #   constructor is deprecated too; this method silences it so one call
-      #   emits one warning.
-      #
-      # @see #tag_list
-      #
-      def tags
-        Git::Deprecation.warn(
-          'Git::Repository#tags is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#tag_list instead.'
-        )
-        Git::Deprecation.silence { tag_list.map { |info| Git::Object::Tag.new(self, info.name) } }
-      end
-
-      # Option keys accepted by {#tag_create} and {#tag_add}
+      # Option keys accepted by {#tag_create}
       TAG_CREATE_ALLOWED_OPTS = %i[
         annotate a sign s no_sign local_user u force f message m file F
         edit e no_edit trailer cleanup create_reflog
@@ -948,158 +831,28 @@ module Git
       #   @return [Git::TagInfo] the newly created tag
       #
       # @raise [ArgumentError] if unsupported options are provided, including the
-      #   `:d` and `:delete` keys that {#tag_add} accepts; use {#tag_delete} to
-      #   delete a tag
+      #   `:d` and `:delete` keys; use {#tag_delete} to delete a tag
       #
       # @raise [ArgumentError] if an annotated or signed tag is requested without
       #   a message
       #
       # @raise [ArgumentError] if more than one positional argument follows the
-      #   name (before any options hash); {#tag_add} silently ignored the extra
-      #   arguments and tagged the first
+      #   name (before any options hash)
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @raise [Git::UnexpectedResultError] if the tag listing cannot be parsed
+      #   or does not contain the new tag (for example, it was deleted by another
+      #   process before the lookup)
+      #
       # @see https://git-scm.com/docs/git-tag git-tag
       #
       def tag_create(name, *args)
-        target, options = Private.tag_target_and_options(args, strict: true)
-        SharedPrivate.assert_valid_opts!(TAG_CREATE_ALLOWED_OPTS, **options)
-        Private.create_tag(@execution_context, name, target, options)
-        tag_list(name).first
-      end
-
-      # Create a new tag
-      #
-      # @overload tag_add(name, options = {})
-      #
-      #   @example Create a lightweight tag on HEAD
-      #     repo.tag_add('v1.0.0')
-      #
-      #   @example Create an annotated tag on HEAD
-      #     repo.tag_add('v1.0.0', annotate: true, message: 'Release 1.0.0')
-      #
-      #   @example Replace an existing tag on HEAD
-      #     repo.tag_add('v1.0.0', force: true)
-      #
-      #   @param name [String] the name of the tag to create
-      #
-      #   @param options [Hash] options for creating the tag (same keys as
-      #     {#tag_create})
-      #
-      #   @return [Git::Object::Tag] the newly created tag
-      #
-      # @overload tag_add(name, target, options = {})
-      #
-      #   @example Create a lightweight tag on a specific commit
-      #     repo.tag_add('v1.0.0', 'abc123')
-      #
-      #   @example Create an annotated tag on a specific commit
-      #     repo.tag_add('v1.0.0', 'abc123', annotate: true, message: 'Release 1.0.0')
-      #
-      #   @param name [String] the name of the tag to create
-      #
-      #   @param target [String] the object to tag (commit SHA, branch name, etc.)
-      #
-      #   @param options [Hash] options for creating the tag (same keys as
-      #     {#tag_create})
-      #
-      #   @return [Git::Object::Tag] the newly created tag
-      #
-      # @overload tag_add(name, delete_options)
-      #
-      #   @deprecated Use {#tag_delete} instead.
-      #
-      #   @example Delete a tag (deprecated)
-      #     repo.tag_add('v1.0.0', d: true)
-      #
-      #   @param name [String] the name of the tag to delete
-      #
-      #   @param delete_options [Hash{Symbol => Boolean}] deletion options;
-      #     only `:d` or `:delete` (set to `true`) is accepted — no other keys
-      #     and no `target` argument may be combined with this form
-      #
-      #   @return [String] git's stdout from the delete
-      #
-      #   @raise [ArgumentError] if a target is also provided
-      #
-      #   @raise [ArgumentError] if options other than `:d`/`:delete` are also
-      #     provided
-      #
-      # @raise [ArgumentError] if unsupported options are provided
-      #
-      # @raise [ArgumentError] if an annotated or signed tag is requested without
-      #   a message
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#tag_create} instead
-      #
-      #   {#tag_create} accepts the same `name`, `target`, and options and
-      #   returns a {Git::TagInfo} (an immutable value object) rather than a
-      #   {Git::Object::Tag}. It does not accept the `:d`/`:delete` form; use
-      #   {#tag_delete} for that. The {Git::Object::Tag} constructor is
-      #   deprecated too; this method silences it so one call emits one
-      #   warning, except that the `:d`/`:delete` form emits a second warning
-      #   of its own.
-      #
-      # @see #tag_create
-      #
-      def tag_add(name, *args)
-        Git::Deprecation.warn(
-          'Git::Repository#tag_add is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#tag_create instead.'
-        )
         target, options = Private.tag_target_and_options(args)
-
-        return Private.tag_add_delete_deprecated(self, name, target, options) if options[:d] || options[:delete]
-
-        options = options.except(:d, :delete)
         SharedPrivate.assert_valid_opts!(TAG_CREATE_ALLOWED_OPTS, **options)
         Private.create_tag(@execution_context, name, target, options)
-        Git::Deprecation.silence { Git::Object::Tag.new(self, name) }
-      end
-
-      # @overload add_tag(name, options = {})
-      #
-      #   @param name [String] the name of the tag to create
-      #
-      #   @param options [Hash] options for creating the tag
-      #
-      #   @return [Git::Object::Tag] the newly created tag
-      #
-      # @overload add_tag(name, target, options = {})
-      #
-      #   @param name [String] the name of the tag to create
-      #
-      #   @param target [String] the object to tag (commit SHA, branch name, etc.)
-      #
-      #   @param options [Hash] options for creating the tag
-      #
-      #   @return [Git::Object::Tag] the newly created tag
-      #
-      # @raise [ArgumentError] if unsupported options are provided
-      #
-      # @raise [ArgumentError] if an annotated or signed tag is requested without
-      #   a message
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#tag_create} instead
-      #
-      #   The warning names {#tag_add}, the replacement this method shipped
-      #   with, and {#tag_add} is deprecated as well, so a creation call emits
-      #   two warnings: one for this method and one for {#tag_add}. The delete
-      #   form `add_tag(name, d: true)` emits a third, for the deprecated `:d`
-      #   and `:delete` options on {#tag_add}; use {#tag_delete} for that. Go
-      #   straight to {#tag_create} for creation.
-      #
-      def add_tag(name, *)
-        Git::Deprecation.warn(
-          'Git::Repository#add_tag is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#tag_add instead.'
-        )
-        tag_add(name, *)
+        tag_list(name).first ||
+          raise(Git::UnexpectedResultError, "tag was created but not found in the tag list: #{name}")
       end
 
       # Delete a tag
@@ -1120,54 +873,34 @@ module Git
         result.stdout
       end
 
-      # @param name [String] the name of the tag to delete
-      #
-      # @return [String] git's stdout from the delete
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#tag_delete} instead
-      #
-      def delete_tag(name)
-        Git::Deprecation.warn(
-          'Git::Repository#delete_tag is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#tag_delete instead.'
-        )
-        tag_delete(name)
-      end
-
       # Private helpers
       #
       # @api private
       #
-      module Private
+      module Private # rubocop:disable Metrics/ModuleLength
         module_function
 
-        # Splits the variadic `*args` of {ObjectOperations#tag_create} and
-        # {ObjectOperations#tag_add} into the target and the options hash
+        # Splits the variadic `*args` of {ObjectOperations#tag_create} into the
+        # target and the options hash
         #
-        # Both methods accept `(name, opts = {})` and `(name, target, opts = {})`,
+        # `tag_create` accepts `(name, opts = {})` and `(name, target, opts = {})`,
         # so a trailing `Hash` is the options and anything before it is the
         # target.
         #
         # @param args [Array] the arguments after the tag name
         #
-        # @param strict [Boolean] when `true`, raise instead of silently ignoring
-        #   a second positional argument before the options; `tag_create` is
-        #   strict, while the deprecated `tag_add` keeps its lenient behavior
-        #
         # @return [Array((String, nil), Hash)] the two-element tuple
         #   `[target, options]`; `target` is `nil` when only options were given
         #
-        # @raise [ArgumentError] if `strict` is `true` and more than one
-        #   positional argument precedes the options hash
+        # @raise [ArgumentError] if more than one positional argument precedes
+        #   the options hash
         #
         # @api private
         #
-        def tag_target_and_options(args, strict: false)
+        def tag_target_and_options(args)
           args = args.dup
           options = args.last.is_a?(Hash) ? args.pop : {}
-          if strict && args.size > 1
+          if args.size > 1
             raise ArgumentError,
                   "Expected at most one target before the options, got #{args.size}: #{args.inspect}"
           end
@@ -1258,39 +991,25 @@ module Git
           raise ArgumentError, 'Cannot create an annotated or signed tag without a message.'
         end
 
-        # Handle the deprecated :d/:delete option on tag_add
-        #
-        # Issues a deprecation warning and delegates to tag_delete. Raises
-        # ArgumentError if a target or incompatible options are also supplied.
-        #
-        # @param facade [ObjectOperations] the calling facade instance
+        # Read the SHA from a loose tag ref file without forking git
         #
-        # @param name [String] tag name
+        # Returns `nil` when the ref is not a loose file under `tags_dir` or when
+        # the file cannot be read, so the caller falls back to `git show-ref`.
         #
-        # @param target [String, nil] target argument (must be nil)
+        # @param tags_dir [String] absolute path of the `refs/tags` directory
         #
-        # @param opts [Hash] options hash (must contain only :d/:delete)
+        # @param head [String] absolute path of the candidate loose ref file
         #
-        # @option opts [Boolean] :d (true) request deletion in the deprecated
-        #   `tag_add` form
-        #
-        # @option opts [Boolean] :delete (true) alias for `:d`
-        #
-        # @return [String] stdout from tag_delete
+        # @return [String, nil] the SHA in the file, or `nil` to fall back to git
         #
         # @api private
         #
-        def tag_add_delete_deprecated(facade, name, target, opts)
-          Git::Deprecation.warn(
-            'Passing :d or :delete to tag_add is deprecated and will be removed in v6.0.0. ' \
-            'Use tag_delete instead.'
-          )
-          raise ArgumentError, 'Cannot pass a target when using the :d/:delete option.' if target
-
-          extra = opts.keys - %i[d delete]
-          raise ArgumentError, "Cannot combine :d/:delete with other options: #{extra.join(', ')}" unless extra.empty?
+        def loose_tag_sha(tags_dir, head)
+          return nil unless head.start_with?("#{tags_dir}#{File::SEPARATOR}") && File.file?(head)
 
-          facade.tag_delete(name)
+          File.read(head).chomp
+        rescue SystemCallError
+          nil
         end
 
         # Returns the direct SHA for a tag reference
@@ -1351,6 +1070,45 @@ module Git
           File.dirname(File.expand_path(file))
         end
 
+        # Write a git archive, staging it in a temporary file first
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @param treeish [String] tree-ish to archive
+        #
+        # @param file [String, nil] destination path, or `nil` to keep the
+        #   temporary file
+        #
+        # @param opts [Hash] caller-supplied options (read-only)
+        #
+        # @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
+        #   or `'tgz'`)
+        #
+        # @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
+        #   to the generated archive
+        #
+        # @option opts [String] :prefix (nil) prefix for entries in the archive
+        #
+        # @option opts [String] :path (nil) path within `treeish` to archive
+        #
+        # @option opts [String] :remote (nil) remote repository from which to
+        #   retrieve the archive
+        #
+        # @return [String] path to the written archive file
+        #
+        # @api private
+        #
+        def write_archive(execution_context, treeish, file, opts)
+          tmp = write_archive_tmp(execution_context, treeish, opts, dest_dir: staging_dir_for(file))
+          return tmp unless file
+
+          atomic_replace(tmp, file)
+          file
+        rescue StandardError
+          FileUtils.rm_f(tmp) if tmp
+          raise
+        end
+
         # Write a git archive to a fresh temporary file and return its path
         #
         # Always writes to a new temporary file so that on error the caller's
@@ -1533,17 +1291,42 @@ module Git
         #
         # @return [void]
         #
+        # @raise [Git::Error] if zlib fails during compression, with the
+        #   `Zlib::Error` as `cause`
+        #
         # @api private
         #
         def apply_gzip(file)
           gz_tmp = Tempfile.create('archive_gz', File.dirname(file)).tap(&:close).path
-          Zlib::GzipWriter.open(gz_tmp) { |gz| File.open(file, 'rb') { |f| IO.copy_stream(f, gz) } }
+          gzip_file(file, gz_tmp)
           FileUtils.rm_f(file)
           File.rename(gz_tmp, file)
         rescue StandardError
           FileUtils.rm_f(gz_tmp) if gz_tmp
           raise
         end
+
+        # Stream `src` through a {Zlib::GzipWriter} into `dest`
+        #
+        # A `Zlib::Error` is not a `SystemCallError`, so {Git::SystemCallGuard}
+        # does not convert it; this method does, per ADR-0008.
+        #
+        # @param src [String] path to the file to compress
+        #
+        # @param dest [String] path to write the gzip stream to
+        #
+        # @return [void]
+        #
+        # @raise [Git::Error] if zlib fails during compression, with the
+        #   `Zlib::Error` as `cause`
+        #
+        # @api private
+        #
+        def gzip_file(src, dest)
+          Zlib::GzipWriter.open(dest) { |gz| File.open(src, 'rb') { |f| IO.copy_stream(f, gz) } }
+        rescue Zlib::Error => e
+          raise Git::Error, "Failed to gzip the archive: #{e.message}"
+        end
       end
       private_constant :Private
     end