git 5.7.0 → 6.0.0

data/lib/git/repository/branching.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
 require 'pathname'
-require 'git/branch'
 require 'git/branch_info'
-require 'git/branches'
 require 'git/commands/branch/create'
 require 'git/commands/branch/delete'
 require 'git/commands/branch/list'
@@ -175,6 +173,10 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note A refused checkout leaves HEAD, the index, and the working tree as
+      #   they were, and the branch `:new_branch` or `:orphan` names is not
+      #   created.
+      #
       def checkout(branch = nil, opts = {})
         if branch.is_a?(Hash) && opts.empty?
           opts = branch
@@ -197,18 +199,13 @@ module Git
       # checked out again. The hard reset discards changes to tracked files only;
       # untracked files created by the block are left in place.
       #
-      # Unlike `Git::Branch#in_branch`, this method does not create `branch`. The
-      # branch must be an existing local branch. Unlike {#checkout}, a commit SHA,
-      # tag, or remote-tracking branch is rejected before any checkout happens:
-      # those detach HEAD, and a commit made there would be left dangling once the
-      # original branch is restored. HEAD must
-      # be on a branch with at least one commit, or detached: an unborn branch (no
-      # commits yet) cannot be checked out again by name, so it is rejected before
-      # any checkout happens.
-      #
-      # **Note:** the restore checkout is not wrapped in `ensure`. If the block,
-      # the commit, or the reset raises an exception, the repository is left
-      # checked out on `branch` rather than restored to the original branch.
+      # This method does not create `branch`: it must be an existing local
+      # branch. Unlike {#checkout}, a commit SHA, tag, or remote-tracking branch
+      # is rejected before any checkout happens: those detach HEAD, and a commit
+      # made there would be left dangling once the original branch is restored.
+      # HEAD must be on a branch with at least one commit, or detached: an unborn
+      # branch (no commits yet) cannot be checked out again by name, so it is
+      # rejected before any checkout happens.
       #
       # @example Commit a new file on a feature branch
       #   repo.in_branch('feature', 'Add README') do
@@ -242,6 +239,11 @@ module Git
       # @yieldreturn [Object] a truthy value to commit all changes, a falsy value to
       #   hard-reset
       #
+      # @note If the block, the commit, the reset, or the restore checkout raises
+      #   an exception, the repository is left checked out on `branch` rather than
+      #   restored to the original branch. When the restore checkout is the step
+      #   that fails, the commit or reset has already run.
+      #
       def in_branch(branch, message = 'in branch work')
         SharedPrivate.assert_local_branch!(self, branch)
         restore_point = SharedPrivate.head_restore_point(self)
@@ -251,6 +253,7 @@ module Git
         else
           reset(nil, hard: true)
         end
+        # Runs only on success. See ADR-0009.
         checkout(restore_point)
       end
 
@@ -283,6 +286,10 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note git does not stop at the first path it cannot write, so a failure
+      #   leaves the files it did write in place, under `:prefix` when one is
+      #   given.
+      #
       def checkout_index(options = {})
         SharedPrivate.assert_valid_opts!(CHECKOUT_INDEX_ALLOWED_OPTS, **options)
 
@@ -344,71 +351,6 @@ module Git
         local_branch?(branch) || remote_branch?(branch)
       end
 
-      # Checks whether the named branch exists locally
-      #
-      # @example Check whether main exists locally
-      #   repo.is_local_branch?('main')  # => true
-      #
-      # @param branch [String] the local branch name to look up
-      #
-      # @return [Boolean] `true` if the branch exists locally, `false` otherwise
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated use {#local_branch?} instead
-      #
-      def is_local_branch?(branch) # rubocop:disable Naming/PredicatePrefix
-        Git::Deprecation.warn(
-          'Git::Repository#is_local_branch? is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#local_branch? instead.'
-        )
-        local_branch?(branch)
-      end
-
-      # Checks whether the named branch exists as a remote-tracking branch
-      #
-      # @example Check whether master exists on any remote
-      #   repo.is_remote_branch?('master')  # => true
-      #
-      # @param branch [String] the short branch name to look up across all remotes
-      #
-      # @return [Boolean] `true` if a remote-tracking branch with that short name
-      #   exists, `false` otherwise
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated use {#remote_branch?} instead
-      #
-      def is_remote_branch?(branch) # rubocop:disable Naming/PredicatePrefix
-        Git::Deprecation.warn(
-          'Git::Repository#is_remote_branch? is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#remote_branch? instead.'
-        )
-        remote_branch?(branch)
-      end
-
-      # Checks whether the named branch exists locally or as a remote-tracking branch
-      #
-      # @example Check whether main exists anywhere
-      #   repo.is_branch?('main')  # => true
-      #
-      # @param branch [String] the branch name to look up
-      #
-      # @return [Boolean] `true` if the branch exists locally or remotely,
-      #   `false` otherwise
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated use {#branch?} instead
-      #
-      def is_branch?(branch) # rubocop:disable Naming/PredicatePrefix
-        Git::Deprecation.warn(
-          'Git::Repository#is_branch? is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#branch? instead.'
-        )
-        branch?(branch)
-      end
-
       # Option keys accepted by {#branch_new}
       #
       BRANCH_NEW_ALLOWED_OPTS = %i[].freeze
@@ -624,30 +566,6 @@ module Git
         Git::Parsers::Branch.parse_list(result.stdout, remote_names:)
       end
 
-      # Returns all local and remote-tracking branches in the 4.x-compatible format
-      #
-      # Each entry is a 4-element array: `[refname, current, worktree, symref]`.
-      # The `refname` uses the short form (`main`, `remotes/origin/main`) to
-      # match the output of the legacy `Git::Lib#branches_all` method.
-      #
-      # @return [Array<Array>] array of `[refname, current, worktree, symref]` tuples
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#branch_list} instead, which returns richer
-      #   {Git::BranchInfo} objects.
-      #
-      def branches_all
-        Git::Deprecation.warn(
-          'Git::Repository#branches_all is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#branch_list instead.'
-        )
-        branch_list.map do |info|
-          refname = info.remote? ? "remotes/#{info.remote_name}/#{info.short_name}" : info.short_name
-          [refname, info.current, info.other_worktree?, info.symref]
-        end
-      end
-
       # Update a branch ref to point to a new commit
       #
       # Derives the full ref from the `branch` argument:
@@ -683,89 +601,6 @@ module Git
         Git::Commands::UpdateRef::Update.new(@execution_context).call(ref, commit)
       end
 
-      # Returns a {Git::Branch} object for the given branch name
-      #
-      # @example Get a branch object for 'main'
-      #   repo.branch('main')  #=> #<Git::Branch 'main'>
-      #
-      # @example Get a branch object for the current branch
-      #   repo.branch  #=> #<Git::Branch 'main'>
-      #
-      # @param branch_name [String] the branch name (defaults to the current branch)
-      #
-      # @return [Git::Branch] the branch object
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use `branch_list(name).first` and the name-based branch
-      #   operations instead
-      #
-      #   {#branch_list} returns immutable {Git::BranchInfo} value objects
-      #   rather than {Git::Branch}. It takes `git branch --list` patterns, so
-      #   pass the short name of a local branch or `"#{remote}/#{name}"` for a
-      #   remote-tracking branch; the `remotes/` and `refs/` prefixes this
-      #   method accepts match nothing. A `"#{remote}/#{name}"` pattern also
-      #   matches a local branch of that name, so take `find(&:remote?)` rather
-      #   than `first` for a remote-tracking branch. With no argument this
-      #   method wraps {#current_branch}, which is `'HEAD'` when HEAD is
-      #   detached; {#branch_list} has no entry for a detached or unborn HEAD,
-      #   so use {#current_branch_state} in those states. Call the
-      #   corresponding {Git::Repository} method (e.g. {#checkout},
-      #   {#branch_new}, {#branch_delete}) for operations on a branch.
-      #
-      # @see #branch_list
-      #
-      def branch(branch_name = current_branch)
-        Git::Deprecation.warn(
-          'Git::Repository#branch is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#branch_list(name).first for a local branch, ' \
-          'Git::Repository#branch_list("remote/name").find(&:remote?) for a remote-tracking branch, ' \
-          'and the name-based branch operations instead.'
-        )
-        Git::Branch.new(self, branch_name)
-      end
-
-      # Returns a {Git::Branches} collection of all branches in the repository
-      #
-      # @example List all branches
-      #   repo.branches
-      #   # => #<Git::Branches ...>
-      #
-      # @example Iterate over all branches
-      #   repo.branches.each { |b| puts b.name }
-      #
-      # @example Access local branches only
-      #   repo.branches.local
-      #
-      # @example Access remote-tracking branches only
-      #   repo.branches.remote
-      #
-      # @example Look up a branch by name
-      #   repo.branches['main']  # => #<Git::Branch 'main'>
-      #
-      # @return [Git::Branches] a collection wrapping all local and
-      #   remote-tracking branches in the repository
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#branch_list} instead
-      #
-      #   {#branch_list} returns `Array<Git::BranchInfo>` (immutable value
-      #   objects) rather than a {Git::Branches} collection. Filter it with
-      #   `select(&:remote?)` or `reject(&:remote?)` in place of
-      #   `branches.remote` and `branches.local`, and look a branch up by name
-      #   with `branch_list(name).first` in place of `branches[name]`.
-      #
-      # @see #branch_list
-      #
-      def branches
-        Git::Deprecation.warn(
-          'Git::Repository#branches is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#branch_list instead.'
-        )
-        Git::Branches.new(self)
-      end
-
       # Private helpers local to {Git::Repository::Branching}
       #
       # @api private
@@ -939,9 +774,6 @@ module Git
 
         # Builds the full git ref string from a branch name argument
         #
-        # Mirrors the routing logic of `Git::Branch#update_ref` for backward
-        # compatibility:
-        #
         # - `remotes/<remote>/<name>` or `refs/remotes/<remote>/<name>` →
         #   `refs/remotes/<remote>/<name>`
         # - Any other value → `refs/heads/<branch>`

data/lib/git/repository/committing.rb

@@ -73,7 +73,6 @@ module Git
       # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
       def commit(message, opts = {})
-        opts = normalize_commit_options(opts)
         SharedPrivate.assert_valid_opts!(COMMIT_ALLOWED_OPTS, **opts)
 
         call_opts = { no_edit: true }
@@ -217,30 +216,6 @@ module Git
       def write_and_commit_tree(opts = {})
         commit_tree(write_tree, opts)
       end
-
-      private
-
-      # Normalizes deprecated commit options into their supported form
-      #
-      # @param opts [Hash] caller-provided commit options
-      #
-      # @option opts [Boolean, nil] :add_all (nil) deprecated alias for `:all`
-      #
-      # @return [Hash] options with deprecated aliases translated
-      #
-      # @api private
-      #
-      def normalize_commit_options(opts)
-        opts = opts.dup
-        return opts unless opts.key?(:add_all)
-
-        Git::Deprecation.warn(
-          'The :add_all option for #commit is deprecated and will be removed in v6.0.0. ' \
-          'Use :all instead.'
-        )
-        opts[:all] = opts.delete(:add_all)
-        opts
-      end
     end
   end
 end