git 5.7.1 → 6.0.0

data/lib/git/repository/remote_operations.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'git/commands/config_option_syntax'
 require 'git/commands/fetch'
 require 'git/commands/ls_remote'
 require 'git/commands/pull'
@@ -8,7 +7,6 @@ require 'git/commands/push'
 require 'git/commands/remote'
 require 'git/parsers/ls_remote'
 require 'git/parsers/remote'
-require 'git/remote'
 
 require 'git/repository/shared_private'
 
@@ -20,7 +18,7 @@ module Git
     #
     # @api private
     #
-    module RemoteOperations # rubocop:disable Metrics/ModuleLength
+    module RemoteOperations
       # Key normalizations for {#fetch} options
       #
       # Maps dash-style option keys (which the 4.x `Git::Lib#fetch` accepted)
@@ -192,6 +190,12 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
+      # @note The fetch completes before the merge starts, so a failure after the
+      #   fetch leaves `FETCH_HEAD` and any updated remote-tracking branches in
+      #   place. On a conflict, the merge is left in progress as described at
+      #   {#merge}, or the rebase when the repository is configured to pull with
+      #   rebase.
+      #
       def pull(remote = nil, branch = nil, opts = {})
         raise ArgumentError, 'You must specify a remote if a branch is specified' if remote.nil? && !branch.nil?
 
@@ -346,41 +350,6 @@ module Git
         nil
       end
 
-      # @param name [String] the name for the new remote
-      #
-      # @param url [String, Git::Repository] the URL of the remote repository
-      #
-      #   A {Git::Repository} instance is accepted for local references and converted
-      #   to `url.repo.to_s`.
-      #
-      # @param opts [Hash] options for adding the remote
-      #
-      # @option opts [Boolean, nil] :fetch (nil) fetch from the remote immediately
-      #   after adding it (`-f`)
-      #
-      #   The deprecated alias `:with_fetch` is accepted and normalized
-      #   automatically.
-      #
-      # @option opts [String, nil] :track (nil) track only the given branch during
-      #   fetch (`-t`)
-      #
-      # @return [Git::Remote] the newly added remote
-      #
-      # @raise [ArgumentError] when unsupported option keys are provided
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#remote_add} instead
-      #
-      def add_remote(name, url, opts = {})
-        Git::Deprecation.warn(
-          'Git::Repository#add_remote is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#remote_add instead.'
-        )
-        remote_add(name, url, opts)
-        Git::Remote.new(self, name)
-      end
-
       # Removes a remote from this repository
       #
       # Deletes the remote named `name` along with its associated configuration,
@@ -399,22 +368,6 @@ module Git
         Git::Commands::Remote::Remove.new(@execution_context).call(name)
       end
 
-      # @param name [String] the name of the remote to remove
-      #
-      # @return [Git::CommandLine::Result] the result of calling `git remote remove`
-      #
-      # @raise [Git::FailedError] when git exits with a non-zero status
-      #
-      # @deprecated Use {#remote_remove} instead
-      #
-      def remove_remote(name)
-        Git::Deprecation.warn(
-          'Git::Repository#remove_remote is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#remote_remove instead.'
-        )
-        remote_remove(name)
-      end
-
       # Sets the URL for an existing remote
       #
       # Replaces the fetch URL configured for the remote named `name`.
@@ -444,28 +397,6 @@ module Git
         nil
       end
 
-      # @param name [String] the name of the remote to update
-      #
-      # @param url [String, Git::Repository] the new URL for the remote
-      #
-      #   A {Git::Repository} instance is accepted for local references and converted
-      #   to `url.repo.to_s`.
-      #
-      # @return [Git::Remote] the updated remote
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#remote_set_url} instead
-      #
-      def set_remote_url(name, url)
-        Git::Deprecation.warn(
-          'Git::Repository#set_remote_url is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#remote_set_url instead.'
-        )
-        remote_set_url(name, url)
-        Git::Remote.new(self, name)
-      end
-
       # Configures which branches are fetched for a remote
       #
       # Uses `git remote set-branches` to set or append fetch refspecs. When the
@@ -503,65 +434,6 @@ module Git
         nil
       end
 
-      # Return the git configuration entries for a named remote
-      #
-      # Reads `git config --list` and returns all entries whose keys begin with
-      # `remote.<name>.`, with the `remote.<name>.` prefix stripped. This
-      # typically yields at least `"url"` and `"fetch"` for a configured remote.
-      #
-      # @example Retrieve the config for the 'origin' remote
-      #   repo.config_remote('origin')
-      #   #=> {
-      #   #     'url'   => 'https://github.com/user/repo.git',
-      #   #     'fetch' => '+refs/heads/*:refs/remotes/origin/*'
-      #   #   }
-      #
-      # @param name [String] the name of the remote (e.g. `"origin"`)
-      #
-      # @return [Hash{String => String}] configuration entries for the remote,
-      #   keyed without the `remote.<name>.` prefix
-      #
-      #   Returns an empty hash when no entries are found.
-      #
-      # @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)
-        end
-      end
-
       # List all configured remotes as {Git::RemoteInfo} objects
       #
       # Reads the repository configuration via {Git::Configuring#config_list} and
@@ -590,67 +462,6 @@ module Git
         Git::Parsers::Remote.parse_list(config_list)
       end
 
-      # Returns a {Git::Remote} object for the named remote
-      #
-      # @example Get the default 'origin' remote
-      #   repo.remote  #=> #<Git::Remote 'origin'>
-      #
-      # @example Get a named remote
-      #   repo.remote('upstream')  #=> #<Git::Remote 'upstream'>
-      #
-      # @param name [String] the remote name (defaults to `'origin'`)
-      #
-      # @return [Git::Remote] the remote object
-      #
-      # @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
-
-      # Returns all configured remotes as {Git::Remote} objects
-      #
-      # @example List all remotes
-      #   repo.remotes  #=> [#<Git::Remote 'origin'>, #<Git::Remote 'upstream'>]
-      #
-      # @return [Array<Git::Remote>] one {Git::Remote} for each configured remote
-      #
-      #   Returns an empty array when no remotes are configured.
-      #
-      # @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
-
       # Returns the names of all configured remotes
       #
       # Lists remote names by running `git remote`. This is a lightweight
@@ -954,29 +765,6 @@ module Git
           normalized[:fetch] = normalized.delete(:with_fetch) if normalized.key?(:with_fetch)
           normalized
         end
-
-        # Retrieve all config entries as a flat hash
-        #
-        # Runs `git config --list` and parses each `key=value` line into a hash.
-        # When no value is present for a key, the value defaults to an empty string.
-        #
-        # @param execution_context [Git::ExecutionContext::Repository] the
-        #   execution context for the repository
-        #
-        # @return [Hash{String => String}] all visible config entries, keyed by
-        #   their full dotted key names
-        #
-        #   For example, `"remote.origin.url"` is a valid key.
-        #
-        # @api private
-        #
-        def config_list(execution_context)
-          lines = Git::Commands::ConfigOptionSyntax::List.new(execution_context).call.stdout.split("\n")
-          lines.each_with_object({}) do |line, hsh|
-            key, value = line.split('=', 2)
-            hsh[key] = value || ''
-          end
-        end
       end
       private_constant :Private
     end

data/lib/git/repository/staging.rb

@@ -92,38 +92,6 @@ module Git
         Git::Commands::Reset.new(@execution_context).call(commitish, **opts).stdout
       end
 
-      # Reset the current HEAD to a specified state with `--hard`
-      #
-      # @example Hard reset to HEAD
-      #   repo.reset_hard
-      #
-      # @example Hard reset to a specific commit
-      #   repo.reset_hard('HEAD~1')
-      #
-      # @param commitish [String, nil] the commit or tree-ish to reset to;
-      #   defaults to HEAD when `nil`
-      #
-      # @param opts [Hash] options passed through to {#reset}
-      #
-      # @option opts [Boolean, nil] :hard (nil) ignored; this method always forces
-      #   `hard: true`
-      #
-      # @return [String] git's stdout from the reset
-      #
-      # @raise [ArgumentError] when unsupported options are provided
-      #
-      # @raise [Git::FailedError] when git exits with a non-zero exit status
-      #
-      # @deprecated Use {#reset} with `hard: true` instead
-      #
-      def reset_hard(commitish = nil, opts = {})
-        Git::Deprecation.warn(
-          'Git::Repository#reset_hard is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#reset(commitish, hard: true) instead.'
-        )
-        reset(commitish, **opts, hard: true)
-      end
-
       # Apply a patch file to the working tree
       #
       # Reads the unified diff in `file` and applies it to the working tree via
@@ -164,6 +132,11 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
+      # @note If a patch fails to apply, the `git am` session is left in progress
+      #   until the caller continues, skips, or aborts it. The patches applied
+      #   before it are already committed on the current branch; aborting the
+      #   session removes them again.
+      #
       def apply_mail(file)
         return unless File.exist?(file)
 
@@ -325,10 +298,6 @@ module Git
       end
 
       # Option keys accepted by {#clean}
-      #
-      # The deprecated `:ff` and `:force_force` keys are handled by
-      # {Git::Repository::Staging::Private.migrate_clean_legacy_options} before this
-      # whitelist is enforced, so they are intentionally absent here.
       CLEAN_ALLOWED_OPTS = %i[d force f dry_run n quiet q exclude e x X pathspec].freeze
       private_constant :CLEAN_ALLOWED_OPTS
 
@@ -377,13 +346,11 @@ module Git
       #
       # @return [String] git's stdout from the clean
       #
-      # @raise [ArgumentError] when unsupported options are provided, or when a
-      #   deprecated `:ff`/`:force_force` value is not `true`, `false`, or `nil`
+      # @raise [ArgumentError] when unsupported options are provided
       #
       # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
       def clean(opts = {})
-        opts = Private.migrate_clean_legacy_options(opts)
         SharedPrivate.assert_valid_opts!(CLEAN_ALLOWED_OPTS, **opts)
         Git::Commands::Clean.new(@execution_context).call(**opts).stdout
       end
@@ -417,151 +384,6 @@ module Git
       module Private
         module_function
 
-        # Translate deprecated `git clean` option keys into their modern form
-        #
-        # Maps the legacy `:ff` and `:force_force` boolean options onto the
-        # `:force` option, emitting a deprecation warning for each.
-        #
-        # @param opts [Hash] the caller-provided clean options
-        #
-        # @option opts [Boolean, nil] :ff (nil) deprecated alias for requesting a
-        #   double-force clean
-        #
-        # @option opts [Boolean, nil] :force_force (nil) deprecated alias for
-        #   requesting a double-force clean
-        #
-        # @option opts [Boolean, Integer, nil] :force (nil) existing force value
-        #   merged with deprecated options when present
-        #
-        # @return [Hash] a new options hash with deprecated keys translated
-        #
-        # @raise [ArgumentError] when a deprecated value is not `true`, `false`, or `nil`
-        #
-        def migrate_clean_legacy_options(opts)
-          opts = deprecate_clean_option(
-            :ff,
-            ':ff option is deprecated and will be removed in v6.0.0. Use force: 2 instead.',
-            opts
-          )
-
-          deprecate_clean_option(
-            :force_force,
-            ':force_force option is deprecated and will be removed in v6.0.0. Use force: 2 instead.',
-            opts
-          )
-        end
-
-        # Translate a single deprecated clean option key onto `:force`
-        #
-        # @param key [Symbol] the deprecated option key (`:ff` or `:force_force`)
-        #
-        # @param message [String] the deprecation message to emit
-        #
-        # @param opts [Hash] the clean options
-        #
-        # @option opts [Boolean, nil] :ff (nil) deprecated alias for requesting a
-        #   double-force clean
-        #
-        # @option opts [Boolean, nil] :force_force (nil) deprecated alias for
-        #   requesting a double-force clean
-        #
-        # @option opts [Boolean, Integer, nil] :force (nil) existing force value
-        #   updated when the deprecated key is true
-        #
-        # @return [Hash] a new options hash with the deprecated key removed
-        #
-        # @raise [ArgumentError] when the deprecated value is not `true`, `false`,
-        #   or `nil`
-        #
-        def deprecate_clean_option(key, message, opts)
-          return opts unless opts.key?(key)
-
-          opts = opts.dup
-          deprecated_value = opts.delete(key)
-          validate_deprecated_clean_option_value!(key, deprecated_value)
-
-          Git::Deprecation.warn(message)
-          return opts unless deprecated_value
-
-          opts[:force] = merge_clean_force_option(opts[:force], force_specified: force_option_specified?(opts))
-          opts
-        end
-
-        # Whether the caller explicitly set a non-nil `:force` value
-        #
-        # @param opts [Hash] the clean options
-        #
-        # @option opts [Boolean, Integer, nil] :force (nil) the clean force value
-        #   to inspect
-        #
-        # @return [Boolean] true if `:force` was set to a non-nil value, false
-        #   otherwise
-        #
-        def force_option_specified?(opts)
-          opts.key?(:force) && !opts[:force].nil?
-        end
-
-        # Validate the value passed to a deprecated clean option
-        #
-        # @param key [Symbol] the deprecated option key
-        #
-        # @param value [Object] the value provided for the deprecated key
-        #
-        # @return [void]
-        #
-        # @raise [ArgumentError] when `value` is not `true`, `false`, or `nil`
-        #
-        def validate_deprecated_clean_option_value!(key, value)
-          return if value.nil? || value == true || value == false
-
-          raise ArgumentError, "#{key} option only accepts true, false, or nil"
-        end
-
-        # Merge a deprecated force request into the existing `:force` value
-        #
-        # @param existing_force [Boolean, Integer, nil] the caller's `:force` value
-        #
-        # @param force_specified [Boolean] whether the caller explicitly set `:force`
-        #
-        # @return [Integer] the resolved `:force` value
-        #
-        def merge_clean_force_option(existing_force, force_specified: false)
-          return 2 unless force_specified
-
-          normalized_force = normalize_clean_force_option(existing_force)
-
-          case normalized_force
-          when Integer then merge_integer_clean_force_option(normalized_force)
-          when false then 2
-          else normalized_force
-          end
-        end
-
-        # Merge an integer `:force` value with the deprecated force request
-        #
-        # @param normalized_force [Integer] the caller's normalized `:force` value
-        #
-        # @return [Integer] the resolved `:force` value
-        #
-        def merge_integer_clean_force_option(normalized_force)
-          return normalized_force if normalized_force < 1
-
-          [normalized_force, 2].max
-        end
-
-        # Normalize a `:force` value, coercing `true` to the integer `1`
-        #
-        # @param value [Boolean, Integer, nil] the `:force` value
-        #
-        # @return [Integer, Boolean, nil] the normalized value
-        #
-        def normalize_clean_force_option(value)
-          case value
-          when true then 1
-          else value
-          end
-        end
-
         # Unescape a git-quoted path
         #
         # Git wraps paths containing non-ASCII or special characters in