git 5.2.0 → 5.3.0

data/lib/git/branch.rb

@@ -17,6 +17,17 @@ module Git
   # @example Listing branches
   #   git.branches.each { |b| puts b.name }
   #
+  # @deprecated Use {Git::Repository::Branching#branch_list} and the
+  #   name-based branch operations on {Git::Repository} instead
+  #
+  #   {Git::Repository::Branching#branch_list} returns immutable
+  #   {Git::BranchInfo} value objects. Operations that lived on this class are
+  #   called on the repository with the branch name instead (for example
+  #   {Git::Repository::Branching#checkout} and
+  #   {Git::Repository::Branching#branch_delete}). Every operation on a
+  #   `Git::Branch` emits a deprecation warning; the `full`, `name`, `remote`,
+  #   `to_s`, and `to_a` readers do not.
+  #
   # @api public
   #
   class Branch
@@ -94,13 +105,31 @@ module Git
     #
     # @return [Git::Object] the commit at the tip of this branch
     #
+    # @deprecated Use {Git::Repository::ObjectOperations#gcommit} with the branch name instead
+    #
+    #   Pass the branch name for a local branch, or `"remotes/#{remote}/#{name}"`
+    #   (the value of {#full}) for a remote-tracking branch; the shorter
+    #   `"#{remote}/#{name}"` can resolve a local branch of that name.
+    #
+    # @see Git::Repository::ObjectOperations#gcommit
+    #
     def gcommit
+      Git::Deprecation.warn(
+        'Git::Branch#gcommit is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#gcommit(name) or, for a remote-tracking branch, ' \
+        'Git::Repository#gcommit("remotes/remote/name") instead.'
+      )
       @gcommit ||= branch_repository.gcommit(@full)
       @gcommit
     end
 
     # Returns the stash list for this repository
     #
+    # This method ignores the branch receiver and returns every stash in the
+    # repository, so `git.branch('feature').stashes` and
+    # `git.branch('main').stashes` return the same entries. It is deprecated and
+    # will be removed in v6.0.0.
+    #
     # The result is memoized after the first call.
     #
     # @example Iterate over stash entries
@@ -108,7 +137,16 @@ module Git
     #
     # @return [Git::Stashes] the stash list
     #
+    # @deprecated Use {Git::Repository#stashes_all} instead
+    #
+    # @see Git::Repository#stashes_all
+    #
     def stashes
+      Git::Deprecation.warn(
+        'Git::Branch#stashes is deprecated and will be removed in v6.0.0. ' \
+        'It ignores the branch and returns all repository stashes. ' \
+        'Use Git::Repository#stashes_all instead.'
+      )
       @stashes ||= Git::Stashes.new(branch_repository)
     end
 
@@ -131,7 +169,30 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::Branching#checkout} with the branch name instead
+    #
+    #   {Git::Repository::Branching#checkout} does not create a missing local
+    #   branch, apart from the guess git makes on its own: with no `:no_guess`
+    #   option, git creates a tracking branch when exactly one remote has a
+    #   branch of that name. To reproduce the create-or-checkout behavior of
+    #   this method, call {Git::Repository::Branching#branch_new} when
+    #   {Git::Repository::Branching#local_branch?} is false, then
+    #   {Git::Repository::Branching#checkout}. Pass `"remotes/#{remote}/#{name}"`
+    #   (the value of {#full}) for a remote-tracking branch; the shorter
+    #   `"#{remote}/#{name}"` can resolve a local branch of that name.
+    #
+    # @see Git::Repository::Branching#checkout
+    #
+    # @see Git::Repository::Branching#branch_new
+    #
     def checkout
+      Git::Deprecation.warn(
+        'Git::Branch#checkout is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#checkout(name) or, for a remote-tracking branch, ' \
+        'Git::Repository#checkout("remotes/remote/name") instead. Git::Repository#checkout does not ' \
+        'create a missing local branch (beyond the guess git makes from a unique remote-tracking ' \
+        'branch); call Git::Repository#branch_new first unless Git::Repository#local_branch? is true.'
+      )
       check_if_create
       branch_repository.checkout(@full)
     end
@@ -172,7 +233,20 @@ module Git
     #
     # @raise [Git::FailedError] if `git archive` fails
     #
+    # @deprecated Use {Git::Repository::ObjectOperations#archive} with the branch name instead
+    #
+    #   Pass the branch name for a local branch, or `"remotes/#{remote}/#{name}"`
+    #   (the value of {#full}) for a remote-tracking branch; the shorter
+    #   `"#{remote}/#{name}"` can resolve a local branch of that name.
+    #
+    # @see Git::Repository::ObjectOperations#archive
+    #
     def archive(file, opts = {})
+      Git::Deprecation.warn(
+        'Git::Branch#archive is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#archive(name, file, opts) or, for a remote-tracking branch, ' \
+        'Git::Repository#archive("remotes/remote/name", file, opts) instead.'
+      )
       branch_repository.archive(@full, file, opts)
     end
 
@@ -203,14 +277,27 @@ module Git
     #
     # @yieldreturn [Object] return a truthy value to commit all changes, a falsy value to hard-reset
     #
+    # @deprecated Use {Git::Repository::Branching#in_branch} with the branch name instead
+    #
+    #   {Git::Repository::Branching#in_branch} does not create the branch and
+    #   restores a detached HEAD to its original commit.
+    #   It takes an existing local branch, so a remote-tracking `Git::Branch` has
+    #   no direct replacement: this method checked out the remote-tracking ref,
+    #   detaching HEAD. Create a local branch from that ref with
+    #   {Git::Repository::Branching#branch_new} first.
+    #
+    # @see Git::Repository::Branching#in_branch
+    #
     def in_branch(message = 'in branch work')
+      Git::Deprecation.warn(
+        'Git::Branch#in_branch is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#in_branch(name, message) instead. It takes an existing local ' \
+        'branch; for a remote-tracking branch, create a local branch from it first.'
+      )
       old_current = branch_repository.current_branch
-      checkout
-      if yield
-        branch_repository.commit_all(message)
-      else
-        branch_repository.reset(nil, hard: true)
-      end
+      # checkout is deprecated too; silence it so one in_branch call emits one warning
+      Git::Deprecation.silence { checkout }
+      yield ? branch_repository.commit_all(message) : branch_repository.reset(nil, hard: true)
       branch_repository.checkout(old_current)
     end
 
@@ -224,7 +311,18 @@ module Git
     #
     # @return [nil]
     #
+    # @deprecated Use {Git::Repository::Branching#branch_new} instead
+    #
+    #   {Git::Repository::Branching#branch_new} raises {Git::FailedError} when
+    #   the branch already exists rather than ignoring the error.
+    #
+    # @see Git::Repository::Branching#branch_new
+    #
     def create
+      Git::Deprecation.warn(
+        'Git::Branch#create is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#branch_new instead.'
+      )
       check_if_create
     end
 
@@ -240,7 +338,19 @@ module Git
     #
     # @raise [Git::Error] if the branch cannot be deleted
     #
+    # @deprecated Use {Git::Repository::Branching#branch_delete} instead
+    #
+    #   Pass the branch name for a local branch, or `"#{remote}/#{name}"` with
+    #   `remotes: true` for a remote-tracking branch.
+    #
+    # @see Git::Repository::Branching#branch_delete
+    #
     def delete
+      Git::Deprecation.warn(
+        'Git::Branch#delete is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#branch_delete(name) or, for a remote-tracking branch, ' \
+        'Git::Repository#branch_delete("remote/name", remotes: true) instead.'
+      )
       if @remote
         branch_repository.branch_delete("#{@remote.name}/#{@name}", remotes: true)
       else
@@ -263,7 +373,16 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Compare {Git::Repository::Branching#current_branch} with the
+    #   branch name instead
+    #
+    # @see Git::Repository::Branching#current_branch
+    #
     def current # rubocop:disable Naming/PredicateMethod
+      Git::Deprecation.warn(
+        'Git::Branch#current is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#current_branch == name instead.'
+      )
       branch_repository.current_branch == @name
     end
 
@@ -283,7 +402,19 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::Branching#branch_contains} with the
+    #   commit and branch name instead
+    #
+    #   {Git::Repository::Branching#branch_contains} returns the matching
+    #   branch names as a String; test it with `empty?`.
+    #
+    # @see Git::Repository::Branching#branch_contains
+    #
     def contains?(commit)
+      Git::Deprecation.warn(
+        'Git::Branch#contains? is deprecated and will be removed in v6.0.0. ' \
+        'Use !Git::Repository#branch_contains(commit, name).empty? instead.'
+      )
       !branch_repository.branch_contains(commit, name).empty?
     end
 
@@ -318,16 +449,27 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::Merging#merge_into} in place of
+    #   `merge(branch)` and {Git::Repository::Merging#merge} with the branch
+    #   name in place of `merge()`
+    #
+    #   {Git::Repository::Merging#merge_into} returns the merge's stdout, does
+    #   not hard-reset after the merge, and restores a detached HEAD to its
+    #   original commit.
+    #   It takes an existing local branch, so a remote-tracking `Git::Branch` has
+    #   no direct replacement: `merge(branch)` checked out the remote-tracking ref,
+    #   detaching HEAD. Create a local branch from that ref with
+    #   {Git::Repository::Branching#branch_new} first.
+    #
+    # @see Git::Repository::Merging#merge_into
+    #
+    # @see Git::Repository::Merging#merge
+    #
     def merge(branch = nil, message = nil)
       if branch
-        in_branch do
-          branch_repository.merge(branch, message)
-          false
-        end
-        # merge a branch into this one
+        merge_into_this_branch(branch, message)
       else
-        # merge this branch into the current one
-        branch_repository.merge(@name)
+        merge_into_current_branch
       end
     end
 
@@ -351,7 +493,19 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::Branching#update_ref} instead
+    #
+    #   Pass the branch name for a local branch, or
+    #   `"remotes/#{remote}/#{name}"` for a remote-tracking branch.
+    #
+    # @see Git::Repository::Branching#update_ref
+    #
     def update_ref(commit)
+      Git::Deprecation.warn(
+        'Git::Branch#update_ref is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#update_ref(name, commit) or, for a remote-tracking branch, ' \
+        'Git::Repository#update_ref("remotes/remote/name", commit) instead.'
+      )
       if @remote
         branch_repository.update_ref("remotes/#{@remote.name}/#{@name}", commit)
       else
@@ -429,7 +583,9 @@ module Git
     #
     def initialize_from_branch_info(branch_info)
       @name = branch_info.short_name
-      @remote = branch_info.remote_name ? Git::Remote.new(@base, branch_info.remote_name) : nil
+      remote_name = branch_info.remote_name
+      # Git::Remote is deprecated too; silence it so one Git::Branch call emits one warning
+      @remote = remote_name ? Git::Deprecation.silence { Git::Remote.new(@base, remote_name) } : nil
       @full = @remote ? "remotes/#{@remote.name}/#{@name}" : @name
     end
 
@@ -468,11 +624,50 @@ module Git
     def parse_name(name)
       # Expect this will always match
       match = name.match(BRANCH_NAME_REGEXP)
-      remote = match[:remote_name] ? Git::Remote.new(@base, match[:remote_name]) : nil
+      remote_name = match[:remote_name]
+      # Git::Remote is deprecated too; silence it so one Git::Branch call emits one warning
+      remote = remote_name ? Git::Deprecation.silence { Git::Remote.new(@base, remote_name) } : nil
       branch_name = match[:branch_name]
       [remote, branch_name]
     end
 
+    # Merges the given branch into this branch, then restores the original branch
+    #
+    # @param branch [String] the name of the branch to merge into this one
+    #
+    # @param message [String, nil] commit message for the merge commit
+    #
+    # @return [String] git's stdout from the final checkout back to the original branch
+    #
+    # @api private
+    #
+    def merge_into_this_branch(branch, message)
+      Git::Deprecation.warn(
+        'Git::Branch#merge(branch) is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#merge_into(name, branch, message) instead. It takes an existing ' \
+        'local branch; for a remote-tracking branch, create a local branch from it first.'
+      )
+      # in_branch is deprecated too; silence it so one merge call emits one warning.
+      # The falsy block value makes in_branch hard-reset instead of committing.
+      Git::Deprecation.silence do
+        in_branch { branch_repository.merge(branch, message) && false }
+      end
+    end
+
+    # Merges this branch into the currently checked-out branch
+    #
+    # @return [String] git's stdout from the merge command
+    #
+    # @api private
+    #
+    def merge_into_current_branch
+      Git::Deprecation.warn(
+        'Git::Branch#merge with no arguments is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#merge(name) instead.'
+      )
+      branch_repository.merge(@name)
+    end
+
     # Creates the branch if it does not already exist, ignoring errors
     #
     # @return [nil]

data/lib/git/branch_info.rb

@@ -70,7 +70,7 @@ module Git
   #   info.remote_name  #=> 'origin'
   #   info.short_name   #=> 'main'
   #
-  # @see Git::Branch for the full-featured branch object with operations
+  # @see Git::Repository::Branching#branch_list for the repository method that returns these
   #
   # @see Git::Commands::Branch::List for the command that produces these
   #

data/lib/git/branches.rb

@@ -10,6 +10,14 @@ module Git
   #   branches = repo.branches
   #   branches.each { |b| puts b.name }
   #
+  # @deprecated Use {Git::Repository::Branching#branch_list} instead
+  #
+  #   {Git::Repository::Branching#branch_list} returns `Array<Git::BranchInfo>`
+  #   (immutable value objects). Filter it with `select(&:remote?)` or
+  #   `reject(&:remote?)` in place of {#remote} and {#local}, and look a
+  #   branch up by name with `branch_list(name).first` in place of {#[]}.
+  #   Constructing a `Git::Branches` emits a deprecation warning.
+  #
   # @api public
   #
   class Branches
@@ -24,18 +32,21 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::Branching#branch_list} instead
+    #
+    # @see Git::Repository::Branching#branch_list
+    #
     def initialize(base)
+      Git::Deprecation.warn(
+        'Git::Branches is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#branch_list instead.'
+      )
       @branches = {}
       @lookup = {}
 
       @base = base
 
-      branch_repository.branch_list.each do |branch_info|
-        branch = Git::Branch.new(base, branch_info)
-
-        @branches[branch_info.refname] = branch
-        index_branch_lookup(branch, refname: branch_info.refname)
-      end
+      load_branches
     end
 
     # Returns all local (non-remote-tracking) branches
@@ -127,13 +138,30 @@ module Git
     def to_s
       out = +''
       @branches.each_value do |b|
-        out << (b.current ? '* ' : '  ') << b.to_s << "\n"
+        # Git::Branch#current is deprecated too; silence it so one to_s call emits one warning
+        current = Git::Deprecation.silence { b.current }
+        out << (current ? '* ' : '  ') << b.to_s << "\n"
       end
       out
     end
 
     private
 
+    # Builds a Git::Branch for every branch in the repository and indexes it
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def load_branches
+      branch_repository.branch_list.each do |branch_info|
+        branch = Git::Branch.new(@base, branch_info)
+
+        @branches[branch_info.refname] = branch
+        index_branch_lookup(branch, refname: branch_info.refname)
+      end
+    end
+
     # @return [Git::Repository] the repository used to enumerate branches
     #
     # @api private

data/lib/git/commands/cat_file/raw.rb

@@ -50,8 +50,10 @@ module Git
           flag_option :s
 
           # Allow -t and -s to query broken or corrupt objects of unknown type.
-          # Git 2.28-2.49 rejects this flag in other modes; git 2.50+ accepts and
-          # ignores it everywhere (the unknown-type feature was removed; see issue 1709).
+          # Deprecated and removed in v6.0.0 (see issue 1709); passing it emits a
+          # deprecation warning. Git 2.28-2.49 honors it with -t and -s and rejects
+          # it in other modes; git 2.50+ accepts and ignores it everywhere (the
+          # unknown-type feature was removed).
           # See https://git-scm.com/docs/git-cat-file/2.49.0#Documentation/git-cat-file.txt---allow-unknown-type
           flag_option :allow_unknown_type
 
@@ -91,6 +93,13 @@ module Git
         #
         #   @param options [Hash] command options
         #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
+        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
+        #     on git 2.50 and later
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning.
+        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -113,8 +122,11 @@ module Git
         #   @param options [Hash] command options
         #
         #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
-        #     unknown type on git 2.28-2.49; git 2.50 removed the unknown-type feature
-        #     and accepts this flag as a no-op
+        #     unknown type on git 2.28-2.49
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning. Git 2.50 removed the unknown-type feature and accepts this
+        #     flag as a no-op.
         #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
@@ -138,8 +150,11 @@ module Git
         #   @param options [Hash] command options
         #
         #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
-        #     unknown type on git 2.28-2.49; git 2.50 removed the unknown-type feature
-        #     and accepts this flag as a no-op
+        #     unknown type on git 2.28-2.49
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning. Git 2.50 removed the unknown-type feature and accepts this
+        #     flag as a no-op.
         #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
@@ -162,6 +177,13 @@ module Git
         #
         #   @param options [Hash] command options
         #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
+        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
+        #     on git 2.50 and later
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning.
+        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -183,6 +205,13 @@ module Git
         #
         #   @param options [Hash] command options
         #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
+        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
+        #     on git 2.50 and later
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning.
+        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -199,6 +228,7 @@ module Git
         #   @option options [Numeric, nil] :timeout (nil) abort the command after this many seconds
         #
         def call(*, **)
+          warn_allow_unknown_type_deprecated(**)
           bound = args_definition.bind(*, **)
           validate_version!(bound.execution_options)
           result = execute_command(bound)
@@ -211,6 +241,30 @@ module Git
 
           result
         end
+
+        private
+
+        # Emit the deprecation warning when the `allow_unknown_type` keyword is passed
+        #
+        # Keys on the keyword being present, whatever its value: `false` and `nil`
+        # suppress the flag but still name a deprecated option.
+        #
+        # @param options [Hash] the keyword arguments passed to {#call}
+        #
+        # @option options [Boolean, nil] :allow_unknown_type the deprecated option;
+        #   any value, including `false` and `nil`, triggers the warning
+        #
+        # @return [void]
+        #
+        def warn_allow_unknown_type_deprecated(**options)
+          return unless options.key?(:allow_unknown_type)
+
+          Git::Deprecation.warn(
+            'The allow_unknown_type option of Git::Commands::CatFile::Raw is deprecated ' \
+            'and will be removed in v6.0.0. Git 2.50 removed the unknown-type feature ' \
+            'and accepts --allow-unknown-type as a no-op.'
+          )
+        end
       end
     end
   end

data/lib/git/object.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'git/author'
+require 'git/author_info'
 require 'git/diff'
 require 'git/errors'
 require 'git/log'
@@ -438,7 +438,10 @@ module Git
         @parents
       end
 
-      # git author
+      # Returns the commit author identity
+      #
+      # @return [Git::AuthorInfo] the author name, email, and author date
+      #
       def author
         check_commit
         @author
@@ -452,7 +455,10 @@ module Git
         author.date
       end
 
-      # git author
+      # Returns the commit committer identity
+      #
+      # @return [Git::AuthorInfo] the committer name, email, and commit date
+      #
       def committer
         check_commit
         @committer
@@ -499,8 +505,8 @@ module Git
       #
       def from_data(data)
         @sha ||= data['sha']
-        @committer = Git::Author.new(data['committer'])
-        @author = Git::Author.new(data['author'])
+        @committer = Git::AuthorInfo.parse(data['committer'])
+        @author = Git::AuthorInfo.parse(data['author'])
         @tree = Git::Object::Tree.new(@base, data['tree'])
         @parents = data['parent'].map { |sha| Git::Object::Commit.new(@base, sha) }
         @message = data['message'].chomp
@@ -593,7 +599,7 @@ module Git
 
       # Returns the tagger identity
       #
-      # @return [Git::Author, nil] the tagger for an annotated tag, or `nil`
+      # @return [Git::AuthorInfo, nil] the tagger for an annotated tag, or `nil`
       #   for a lightweight tag
       #
       def tagger
@@ -613,7 +619,7 @@ module Git
         if annotated?
           tdata = object_repository.cat_file_tag(@name)
           @message = tdata['message'].chomp
-          @tagger = Git::Author.new(tdata['tagger'])
+          @tagger = Git::AuthorInfo.parse(tdata['tagger'])
         else
           @message = @tagger = nil
         end