git 5.2.0 → 5.4.0

data/lib/git/repository/object_operations.rb

@@ -721,8 +721,28 @@ module Git
       # @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::Object::Tag.new(self, 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
@@ -753,6 +773,47 @@ module Git
         Git::Object.new(self, objectish)
       end
 
+      # Returns the tags in the repository as structured objects
+      #
+      # @example List all tags
+      #   repo.tag_list
+      #   # => [#<data Git::TagInfo name="v1.0.0", oid=nil, target_oid="abc123...", ...>,
+      #   #     #<data Git::TagInfo name="v2.0.0", oid="def456...", target_oid="789abc...", ...>]
+      #
+      # @example Look up a single tag by name
+      #   repo.tag_list('v1.0.0').first
+      #   # => #<data Git::TagInfo name="v1.0.0", ...>
+      #
+      # @example Look up a tag that does not exist
+      #   repo.tag_list('nonexistent').first #=> nil
+      #
+      # @example Filter using glob patterns
+      #   repo.tag_list('v1.*', 'v2.*')
+      #
+      # @example List only annotated tags
+      #   repo.tag_list.select(&:annotated?)
+      #
+      # @param patterns [Array<String>] optional shell wildcard patterns passed
+      #   directly to `git tag --list`; when empty (the default) all tags are
+      #   returned
+      #
+      # @return [Array<Git::TagInfo>] parsed tag information for every tag
+      #   matching the patterns, in the order `git tag --list` reports them
+      #
+      #   Returns an empty array when the repository has no tags or no tag
+      #   matches the given patterns.
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see https://git-scm.com/docs/git-tag git-tag
+      #
+      def tag_list(*patterns)
+        result = Git::Commands::Tag::List.new(@execution_context).call(
+          *patterns, format: Git::Parsers::Tag::FORMAT_STRING
+        )
+        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,
@@ -769,30 +830,50 @@ module Git
       #
       # @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
-        result = Git::Commands::Tag::List.new(@execution_context).call(format: Git::Parsers::Tag::FORMAT_STRING)
-        Git::Parsers::Tag.parse_list(result.stdout).map { |info| tag(info.name) }
+        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_add}
-      TAG_ADD_ALLOWED_OPTS = %i[
+      # Option keys accepted by {#tag_create} and {#tag_add}
+      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
       ].freeze
-      private_constant :TAG_ADD_ALLOWED_OPTS
+      private_constant :TAG_CREATE_ALLOWED_OPTS
 
-      # Create a new tag
+      # Create a new tag and return its metadata
       #
-      # @overload tag_add(name, options = {})
+      # @overload tag_create(name, options = {})
       #
       #   @example Create a lightweight tag on HEAD
-      #     repo.tag_add('v1.0.0')
+      #     repo.tag_create('v1.0.0')
+      #     # => #<data Git::TagInfo name="v1.0.0", oid=nil, target_oid="abc123...", ...>
       #
       #   @example Create an annotated tag on HEAD
-      #     repo.tag_add('v1.0.0', annotate: true, message: 'Release 1.0.0')
+      #     repo.tag_create('v1.0.0', annotate: true, message: 'Release 1.0.0')
+      #     # => #<data Git::TagInfo name="v1.0.0", oid="def456...", message="Release 1.0.0", ...>
       #
       #   @example Replace an existing tag on HEAD
-      #     repo.tag_add('v1.0.0', force: true)
+      #     repo.tag_create('v1.0.0', force: true)
       #
       #   @param name [String] the name of the tag to create
       #
@@ -847,6 +928,65 @@ module Git
       #   @option options [Boolean, nil] :create_reflog (nil) create a reflog for
       #     the tag
       #
+      #   @return [Git::TagInfo] the newly created tag
+      #
+      # @overload tag_create(name, target, options = {})
+      #
+      #   @example Create a lightweight tag on a specific commit
+      #     repo.tag_create('v1.0.0', 'abc123')
+      #
+      #   @example Create an annotated tag on a specific commit
+      #     repo.tag_create('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 the
+      #     first overload)
+      #
+      #   @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
+      #
+      # @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
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @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 = {})
@@ -861,8 +1001,8 @@ module Git
       #
       #   @param target [String] the object to tag (commit SHA, branch name, etc.)
       #
-      #   @param options [Hash] options for creating the tag (same keys as the
-      #     first overload)
+      #   @param options [Hash] options for creating the tag (same keys as
+      #     {#tag_create})
       #
       #   @return [Git::Object::Tag] the newly created tag
       #
@@ -893,17 +1033,31 @@ module Git
       #
       # @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)
-        options = args.last.is_a?(Hash) ? args.pop : {}
-        target = args.first
+        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_ADD_ALLOWED_OPTS, **options)
-        Private.validate_tag_options!(options)
-        Git::Commands::Tag::Create.new(@execution_context).call(name, target, **options)
-        tag(name)
+        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 = {})
@@ -931,7 +1085,14 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      # @deprecated Use {#tag_add} instead
+      # @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(
@@ -982,6 +1143,82 @@ module Git
       module Private
         module_function
 
+        # Splits the variadic `*args` of {ObjectOperations#tag_create} and
+        # {ObjectOperations#tag_add} into the target and the options hash
+        #
+        # Both methods accept `(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
+        #
+        # @api private
+        #
+        def tag_target_and_options(args, strict: false)
+          args = args.dup
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          if strict && args.size > 1
+            raise ArgumentError,
+                  "Expected at most one target before the options, got #{args.size}: #{args.inspect}"
+          end
+
+          [args.first, options]
+        end
+
+        # Validates the tag-creation options and runs `git tag`
+        #
+        # @param execution_context [Git::ExecutionContext::Repository] the
+        #   execution context for git commands
+        #
+        # @param name [String] the name of the tag to create
+        #
+        # @param target [String, nil] the object to tag, or `nil` for HEAD
+        #
+        # @param options [Hash] the tag-creation options, already checked
+        #   against the allowed keys (see {ObjectOperations#tag_create} for the
+        #   full list)
+        #
+        # @option options [Boolean, nil] :annotate (nil) make an annotated tag;
+        #   requires a message (alias: `:a`)
+        #
+        # @option options [Boolean, nil] :sign (nil) make a signed tag; requires
+        #   a message (alias: `:s`)
+        #
+        # @option options [String] :local_user (nil) sign with the given key;
+        #   requires a message (alias: `:u`)
+        #
+        # @option options [String] :message (nil) the tag message (alias: `:m`)
+        #
+        # @option options [String] :file (nil) a file to read the tag message
+        #   from (alias: `:F`)
+        #
+        # @option options [Boolean, nil] :force (nil) replace an existing tag
+        #   (alias: `:f`)
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] when an annotated or signed tag is requested
+        #   without a message
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        # @api private
+        #
+        def create_tag(execution_context, name, target, options)
+          validate_tag_options!(options)
+          Git::Commands::Tag::Create.new(execution_context).call(name, target, **options)
+        end
+
         # Validate that a message is present when an annotated or signed tag is
         # requested
         #

data/lib/git/repository/remote_operations.rb

@@ -525,7 +525,37 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
+      # @deprecated Use `remote_list.find { |r| r.name == name }` for the fields
+      #   {Git::RemoteInfo} models, or filter {Git::Configuring#config_list} on
+      #   the `remote.<name>.` key prefix to keep every entry
+      #
+      #   {#remote_list} returns a {Git::RemoteInfo} per remote. Its `url` and
+      #   `fetch` members hold every configured value as `Array<String>`,
+      #   whereas this method returns a flat hash in which a repeated `url` or
+      #   `fetch` key overwrites the earlier value.
+      #
+      #   {Git::RemoteInfo} models only the remote variables git defines and
+      #   drops any other `remote.<name>.*` entry, whereas this method returns
+      #   every entry. Callers that read custom keys should filter
+      #   {Git::Configuring#config_list} instead, which returns the same hash
+      #   (shown here for the `origin` remote):
+      #
+      #     prefix = 'remote.origin.'
+      #     repo.config_list
+      #         .select { |entry| entry.key.start_with?(prefix) }
+      #         .to_h { |entry| [entry.key.delete_prefix(prefix), entry.value] }
+      #
+      # @see #remote_list
+      #
+      # @see Git::Configuring#config_list
+      #
       def config_remote(name)
+        Git::Deprecation.warn(
+          'Git::Repository#config_remote is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_list.find { |r| r.name == name } for the fields ' \
+          'Git::RemoteInfo models, or filter Git::Repository#config_list on the ' \
+          '"remote.<name>." key prefix to keep every entry.'
+        )
         prefix = "remote.#{name}."
         Private.config_list(@execution_context).each_with_object({}) do |(key, value), hsh|
           hsh[key.delete_prefix(prefix)] = value if key.start_with?(prefix)
@@ -574,7 +604,19 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use `remote_list.find { |r| r.name == name }` instead
+      #
+      #   {#remote_list} returns immutable {Git::RemoteInfo} value objects
+      #   rather than {Git::Remote}. Call the corresponding {Git::Repository}
+      #   method (e.g. {#fetch}, {#remote_remove}) for operations on a remote.
+      #
+      # @see #remote_list
+      #
       def remote(name = 'origin')
+        Git::Deprecation.warn(
+          'Git::Repository#remote is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_list.find { |r| r.name == name } instead.'
+        )
         Git::Remote.new(self, name)
       end
 
@@ -589,7 +631,22 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use {#remote_list} instead
+      #
+      #   {#remote_list} returns `Array<Git::RemoteInfo>` (immutable value
+      #   objects) rather than `Array<Git::Remote>`. Call the corresponding
+      #   {Git::Repository} method (e.g. {#fetch}, {#remote_remove}) for
+      #   operations on a remote. Each {Git::Remote} this method constructs
+      #   emits its own deprecation warning, so a call produces one warning
+      #   for this method plus one per remote returned.
+      #
+      # @see #remote_list
+      #
       def remotes
+        Git::Deprecation.warn(
+          'Git::Repository#remotes is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_list instead.'
+        )
         result = Git::Commands::Remote::List.new(@execution_context).call
         result.stdout.split("\n").map { |name| Git::Remote.new(self, name) }
       end

data/lib/git/repository/shared_private.rb

@@ -46,6 +46,73 @@ module Git
 
         raise ArgumentError, "Unknown options: #{unknown.join(', ')}"
       end
+
+      # Raise unless `branch` names an existing local branch
+      #
+      # Used by facade methods that check out a branch, do work on it, and switch
+      # back. {Git::Repository#checkout} also accepts commit SHAs, tags, and
+      # remote-tracking branches, all of which detach HEAD; work committed there
+      # would be left dangling once the original branch is restored, and git has
+      # no way to report that.
+      #
+      # @example With an existing local branch
+      #   SharedPrivate.assert_local_branch!(repo, 'feature') #=> nil
+      #
+      # @example With a tag
+      #   SharedPrivate.assert_local_branch!(repo, 'v1.0.0')
+      #   #=> raises ArgumentError: 'v1.0.0' is not an existing local branch
+      #
+      # @param repository [Git::Repository] the repository to check
+      #
+      # @param branch [String] the branch name to verify
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] when `branch` is not an existing local branch
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def assert_local_branch!(repository, branch)
+        return if repository.local_branch?(branch)
+
+        raise ArgumentError, "'#{branch}' is not an existing local branch"
+      end
+
+      # Returns a revision that restores the current HEAD after switching branches
+      #
+      # Used by facade methods that temporarily check out another branch and
+      # then switch back. On a branch, the branch name is enough. When HEAD is
+      # detached, {Git::Repository#current_branch} reports `'HEAD'`, which after
+      # a checkout resolves to the new branch rather than the original commit,
+      # so the commit SHA is captured instead. An unborn branch (one with no
+      # commits yet) has no ref to check out by name, so it is rejected here,
+      # before the caller switches away from it.
+      #
+      # @example On a branch
+      #   SharedPrivate.head_restore_point(repo) #=> "main"
+      #
+      # @example With a detached HEAD
+      #   SharedPrivate.head_restore_point(repo) #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
+      #
+      # @param repository [Git::Repository] the repository whose HEAD to record
+      #
+      # @return [String] the current branch name, or the full HEAD commit SHA
+      #   when HEAD is detached
+      #
+      # @raise [Git::Error] when HEAD is on an unborn branch
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def head_restore_point(repository)
+        head = repository.current_branch_state
+        case head.state
+        when :detached then repository.rev_parse('HEAD').strip
+        when :unborn
+          raise Git::Error, "HEAD is on the unborn branch '#{head.name}', which cannot be restored " \
+                            'after switching branches; make a commit on it first'
+        else head.name
+        end
+      end
     end
 
     private_constant :SharedPrivate