git 5.6.0 → 6.0.0

data/lib/git/repository/worktree_operations.rb

@@ -2,9 +2,7 @@
 
 require 'git/commands/worktree'
 require 'git/parsers/worktree'
-require 'git/worktree'
 require 'git/worktree_info'
-require 'git/worktrees'
 
 module Git
   class Repository
@@ -46,66 +44,56 @@ module Git
         Git::Parsers::Worktree.parse_list(result.stdout)
       end
 
-      # Returns all worktrees as an array of directory and SHA pairs
-      #
-      # Lists the main worktree and all linked worktrees. The main worktree of
-      # a bare repository has no checked-out commit and is omitted.
-      #
-      # @example List all worktrees
-      #   repo.worktrees_all
-      #   #=> [["/path/to/main", "4bef5ab..."], ["/tmp/worktree-1", "b8c6320..."]]
-      #
-      # @return [Array<Array(String, String)>] array of `[directory, sha]` pairs
-      #
-      #   `directory` is the worktree path reported by git (absolute or relative,
-      #   depending on repository configuration); `sha` is the full SHA of the
-      #   checked-out HEAD commit
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#worktree_list} instead
-      #
-      #   {#worktree_list} returns one {Git::WorktreeInfo} per worktree, with
-      #   `path` and `head` in place of the pair, and includes the main worktree
-      #   of a bare repository.
-      #
-      # @see #worktree_list
-      #
-      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
-      #
-      def worktrees_all
-        Git::Deprecation.warn(
-          'Git::Repository#worktrees_all is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#worktree_list instead.'
-        )
-        worktree_list.reject { |worktree| worktree.head.nil? }.map { |worktree| [worktree.path, worktree.head] }
-      end
-
       # Create a new linked worktree at the given directory
       #
+      # Returns the entry that {#worktree_list} reports for the new worktree.
+      # Its `path` is the directory as git records it: absolute, with symlinks
+      # resolved, so `/tmp/feature` on macOS comes back as
+      # `/private/tmp/feature`.
+      #
       # @example Create a worktree at a path (auto-creates a branch)
-      #   repo.worktree_add('/tmp/feature')
+      #   info = repo.worktree_add('/tmp/feature')
+      #   info.path    #=> "/private/tmp/feature"
+      #   info.branch  #=> "refs/heads/feature"
       #
       # @example Create a worktree and check out an existing commitish
-      #   repo.worktree_add('/tmp/hotfix', 'main')
+      #   repo.worktree_add('/tmp/hotfix', 'main').head
+      #   #=> "4bef5ab0c8e7c19c6be2c0f55ccd45eec1f3d32a"
       #
-      # @param dir [String] filesystem path for the new worktree
+      # @param dir [String] filesystem path for the new worktree, absolute or
+      #   relative to the current directory
       #
       # @param commitish [String, nil] branch, tag, or commit to check out
       #
-      #   When `nil`, git creates a new branch named after the final path component
+      #   When `nil`, git checks out the branch named after the final path
+      #   component, creating it when no such branch exists
       #
-      # @return [String] the output from the git worktree add command
+      # @return [Git::WorktreeInfo] the new worktree's entry from {#worktree_list}
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @raise [Git::UnexpectedResultError] if the worktree listing cannot be
+      #   parsed or does not contain an entry for the new worktree's directory
+      #   (for example, it was removed by another process before the lookup)
+      #
+      # @note When `commitish` is `nil` and git creates the branch, it does so
+      #   before it creates the worktree, so a failure after that point leaves
+      #   the new branch in place without a worktree. A branch that already
+      #   existed is left as it was.
+      #
       # @see https://git-scm.com/docs/git-worktree git-worktree documentation
       #
       def worktree_add(dir, commitish = nil)
         args = [dir]
         args << commitish unless commitish.nil?
 
-        Git::Commands::Worktree::Add.new(@execution_context).call(*args).stdout
+        Git::Commands::Worktree::Add.new(@execution_context).call(*args)
+
+        # git records the path as given with symlinks resolved, so compare by
+        # identity rather than by string: this covers symlinks, case-insensitive
+        # filesystems, and Unicode normalization on macOS
+        worktree_list.find { |worktree| File.identical?(worktree.path, dir) } ||
+          raise(Git::UnexpectedResultError, "worktree was created but not found in the worktree list: #{dir}")
       end
 
       # Remove a linked worktree
@@ -235,8 +223,6 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      # @raise [Git::VersionError] if the installed git is older than 2.29.0
-      #
       # @see https://git-scm.com/docs/git-worktree git-worktree documentation
       #
       def worktree_repair(*paths)
@@ -261,79 +247,6 @@ module Git
       def worktree_prune
         Git::Commands::Worktree::Prune.new(@execution_context).call.stdout
       end
-
-      # Return a {Git::Worktree} object for the given directory and optional commitish
-      #
-      # This is a factory method — it constructs the domain object but does not
-      # immediately execute any git commands.
-      #
-      # @example Get a worktree object for a new path
-      #   wt = repo.worktree('/tmp/feature')
-      #
-      # @example Get a worktree object for a specific branch or commit
-      #   wt = repo.worktree('/tmp/hotfix', 'main')
-      #
-      # @param dir [String] filesystem path for the worktree
-      #
-      # @param commitish [String, nil] branch, tag, or commit to associate with
-      #   the worktree; `nil` means no commitish is specified
-      #
-      # @return [Git::Worktree] a worktree domain object for the given path
-      #
-      # @deprecated Use {#worktree_add} and {#worktree_remove} instead
-      #
-      #   `repo.worktree(dir, commitish).add` becomes
-      #   `repo.worktree_add(dir, commitish)` and `repo.worktree(dir).remove`
-      #   becomes `repo.worktree_remove(dir)`. Read a worktree's checked-out
-      #   commit from {Git::WorktreeInfo#head} via {#worktree_list}.
-      #
-      # @see #worktree_add
-      #
-      # @see #worktree_remove
-      #
-      def worktree(dir, commitish = nil)
-        Git::Deprecation.warn(
-          'Git::Repository#worktree is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#worktree_add and Git::Repository#worktree_remove instead.'
-        )
-        Git::Worktree.new(self, dir, commitish)
-      end
-
-      # Return a {Git::Worktrees} collection of all worktrees (main and linked)
-      #
-      # The collection is populated eagerly when this method is called (git runs
-      # at construction time). It is enumerable and supports indexed access by
-      # worktree path.
-      #
-      # @example Iterate over all worktrees
-      #   repo.worktrees.each { |wt| puts wt.dir }
-      #
-      # @example Count worktrees
-      #   repo.worktrees.size
-      #
-      # @example Access a specific worktree by path
-      #   repo.worktrees['/tmp/feature']
-      #
-      # @return [Git::Worktrees] an enumerable collection of all worktrees
-      #
-      # @raise [Git::FailedError] if git exits with a non-zero exit status
-      #
-      # @deprecated Use {#worktree_list} instead
-      #
-      #   {#worktree_list} returns `Array<Git::WorktreeInfo>`. Look a worktree up
-      #   by path with `worktree_list.find { |w| w.path == path }` in place of
-      #   `worktrees[path]`, and call {#worktree_prune} in place of
-      #   `worktrees.prune`. Calling this method emits one deprecation warning.
-      #
-      # @see #worktree_list
-      #
-      def worktrees
-        Git::Deprecation.warn(
-          'Git::Repository#worktrees is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#worktree_list instead.'
-        )
-        Git::Worktrees.new(self)
-      end
     end
   end
 end

data/lib/git/repository.rb

@@ -15,11 +15,11 @@ require 'git/repository/maintenance'
 require 'git/repository/merging'
 require 'git/repository/object_operations'
 require 'git/repository/remote_operations'
-require 'git/repository/shared_private'
 require 'git/repository/staging'
 require 'git/repository/stashing'
 require 'git/repository/status_operations'
 require 'git/repository/worktree_operations'
+require 'git/system_call_guard'
 
 module Git
   # The main public interface for interacting with a Git repository
@@ -46,7 +46,7 @@ module Git
   #
   # @api public
   #
-  class Repository # rubocop:disable Metrics/ClassLength
+  class Repository
     include Git::Configuring
     include Git::Repository::Branching
     include Git::Repository::ContextHelpers
@@ -63,39 +63,6 @@ module Git
     include Git::Repository::StatusOperations
     include Git::Repository::WorktreeOperations
 
-    # Allowed keyword options for deprecated config write operations
-    #
-    # @return [Array<Symbol>] accepted option keys
-    #
-    CONFIG_SET_ALLOWED_OPTS = %i[file].freeze
-    private_constant :CONFIG_SET_ALLOWED_OPTS
-
-    # Allowed keyword options for deprecated config read operations
-    #
-    # @return [Array<Symbol>] accepted option keys
-    #
-    CONFIG_READ_ALLOWED_OPTS = %i[file].freeze
-    private_constant :CONFIG_READ_ALLOWED_OPTS
-
-    # Deprecation warning emitted by {#config}
-    #
-    # @return [String] the warning message shown to callers
-    #
-    CONFIG_DEPRECATION_WARNING =
-      'Git::Repository#config is deprecated and will be removed in v6.0.0. ' \
-      'Use config_get(name), config_set(name, value), or config_list instead.'
-    private_constant :CONFIG_DEPRECATION_WARNING
-
-    # Deprecation warning emitted by {#global_config}
-    #
-    # @return [String] the warning message shown to callers
-    #
-    GLOBAL_CONFIG_DEPRECATION_WARNING =
-      'Git::Repository#global_config is deprecated and will be removed in v6.0.0. ' \
-      'Use config_get(name, global: true), config_set(name, value, global: true), ' \
-      'or config_list(global: true) instead.'
-    private_constant :GLOBAL_CONFIG_DEPRECATION_WARNING
-
     # @return [Git::ExecutionContext::Repository] the execution context used to run
     #   git commands for this repository
     #
@@ -149,24 +116,6 @@ module Git
       index_file && Pathname.new(index_file)
     end
 
-    # Returns `self` after emitting a deprecation warning.
-    #
-    # Legacy callers that used `git.lib.some_method` can migrate to calling the
-    # facade method directly on the repository object. This shim will be removed
-    # in v6.0.0.
-    #
-    # @return [self]
-    #
-    # @api private
-    #
-    def lib
-      Git::Deprecation.warn(
-        'Git::Repository#lib is deprecated and will be removed in v6.0.0. ' \
-        'Use the repository object directly.'
-      )
-      self
-    end
-
     # @return [String, nil] the git directory path
     #
     # @api private
@@ -202,111 +151,6 @@ module Git
     # @api private
     def binary_path = execution_context.binary_path
 
-    # Reads or writes a git configuration entry
-    #
-    # Dispatches to one of three modes depending on the arguments supplied:
-    #
-    # * **List** — `config()` returns all visible config entries as a `Hash`.
-    # * **Get** — `config(name)` returns the value for a single key as a `String`.
-    # * **Set** — `config(name, value)` writes a value and returns the raw
-    #   command result.
-    #
-    # @example List all config entries
-    #   repo.config #=> { "user.name" => "Alice", "core.bare" => "false" }
-    #
-    # @example Read a config value
-    #   repo.config('user.name') #=> "Alice"
-    #
-    # @example Set a config value
-    #   repo.config('user.name', 'Alice')
-    #
-    # @param name [String, Hash, nil] the dotted config key, or an options hash
-    #   for list mode when `value` and `options` are omitted
-    #
-    # @param value [#to_s, Hash, nil] the value to set, or an options hash in the
-    #   legacy `config(name, options)` call shape
-    #
-    # @param options [Hash] options forwarded to git config
-    #
-    # @option options [String, nil] :file (nil) path to a custom config file
-    #
-    # @return [Hash{String => String}, String, Git::CommandLine::Result] all config
-    #   entries, a single value, or the command result for set mode
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def config(name = nil, value = nil, options = {})
-      Git::Deprecation.warn(CONFIG_DEPRECATION_WARNING)
-      name, value, options = deprecated_normalize_config_args(name, value, options)
-
-      if !name.nil? && !value.nil?
-        deprecated_config_set(name, value, **options)
-      elsif name
-        deprecated_config_get(name, **options)
-      else
-        deprecated_config_list(**options)
-      end
-    end
-
-    # Read or write a global git configuration entry
-    #
-    # Dispatches to one of three modes depending on the arguments supplied,
-    # targeting the git global config scope (`git config --global`):
-    #
-    # * **List** — `global_config()` returns all global config entries as a `Hash`.
-    # * **Get** — `global_config(name)` returns the value for a single key as a `String`.
-    # * **Set** — `global_config(name, value)` writes a value and returns the raw
-    #   command result.
-    #
-    # @overload global_config
-    #
-    #   @example List all global config entries
-    #     repo.global_config #=> { "user.name" => "Alice", "core.autocrlf" => "false" }
-    #
-    #   @return [Hash{String => String}] all global config entries, keyed by their
-    #     full dotted key names (e.g. `"user.name"`)
-    #
-    #   @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    # @overload global_config(name)
-    #
-    #   @example Read the global committer name
-    #     repo.global_config('user.name') #=> "Alice"
-    #
-    #   @param name [String] the dotted config key to look up (e.g. `"user.name"`)
-    #
-    #   @return [String] the value of the global config entry
-    #
-    #   @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    # @overload global_config(name, value)
-    #
-    #   @example Set the global committer name
-    #     repo.global_config('user.name', 'Alice')
-    #
-    #   @param name [String] the dotted config key to write (e.g. `"user.name"`)
-    #
-    #   @param value [#to_s] the value to assign; any object is accepted and
-    #     converted to a String via `#to_s` before being passed to git
-    #
-    #   @return [Git::CommandLine::Result] the raw result of
-    #     `git config --global <name> <value>`
-    #
-    #   @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def global_config(name = nil, value = nil)
-      Git::Deprecation.warn(GLOBAL_CONFIG_DEPRECATION_WARNING)
-      if !name.nil? && !value.nil?
-        deprecated_global_config_set(name, value)
-      elsif !name.nil?
-        deprecated_global_config_get(name)
-      else
-        deprecated_global_config_list
-      end
-    end
-
     # Returns the size of the repository directory in bytes
     #
     # Sums the sizes of every regular file under the repository (`.git`)
@@ -320,161 +164,38 @@ module Git
     #
     # @return [Integer] the total size in bytes of the repository directory
     #
+    # @raise [Git::Error] if the repository directory cannot be traversed, for
+    #   example when a subdirectory cannot be searched
+    #
     def repo_size
       repository = repo
       return 0 unless repository&.directory?
 
-      total = 0
-      Find.find(repository.to_s) do |path|
-        stat = File.lstat(path)
-        total += stat.size if stat.file?
-      rescue Errno::ENOENT
-        next
+      Git::SystemCallGuard.call('Failed to compute the repository size') do
+        repo_size_of_directory(repository.to_s)
       end
-      total
     end
 
     private
 
-    # Normalizes deprecated `config` call shapes into positional arguments
-    #
-    # @param name [String, Hash, nil] config key or an options hash
-    #
-    # @param value [#to_s, Hash, nil] config value or an options hash
-    #
-    # @param options [Hash] explicit options hash argument
-    #
-    # @option options [String, nil] :file (nil) path to a custom config file
-    #
-    # @return [Array((String, nil), (#to_s, nil), Hash)] normalized
-    #   `[name, value, options]`
-    #
-    # @raise [ArgumentError] if deprecated arguments mix an options hash with
-    #   unexpected additional positional arguments
-    #
-    def deprecated_normalize_config_args(name, value, options)
-      if name.is_a?(Hash)
-        raise ArgumentError, 'unexpected positional arguments after options hash' if !value.nil? || !options.empty?
-
-        [nil, nil, name]
-      elsif value.is_a?(Hash)
-        raise ArgumentError, 'unexpected third argument when second argument is options hash' unless options.empty?
-
-        [name, nil, value]
-      else
-        [name, value, options]
-      end
-    end
-
-    # Writes a config value using the deprecated `config(name, value, ...)` path
-    #
-    # @overload deprecated_config_set(name, value, **options)
-    #
-    #   @param name [String] the dotted config key to write
-    #
-    #   @param value [#to_s] the value to assign
-    #
-    #   @param options [Hash] command options
-    #
-    #   @option options [String, nil] :file (nil) path to a custom config file
-    #
-    #   @return [Git::CommandLine::Result] the command result
-    #
-    #   @raise [ArgumentError] if unsupported options are provided
-    #
-    #   @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def deprecated_config_set(name, value, **)
-      SharedPrivate.assert_valid_opts!(CONFIG_SET_ALLOWED_OPTS, **)
-      Git::Commands::ConfigOptionSyntax::Set.new(@execution_context).call(name, value, **)
-    end
-
-    # Reads a config value using the deprecated `config(name, ...)` path
-    #
-    # @param name [String] the dotted config key to read
-    #
-    # @param options [Hash] command options
-    #
-    # @option options [String, nil] :file (nil) path to a custom config file
-    #
-    # @return [String] the config value
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def deprecated_config_get(name, **options)
-      SharedPrivate.assert_valid_opts!(CONFIG_READ_ALLOWED_OPTS, **options)
-      opts = options[:file] ? { file: options[:file] } : {}
-      result = Git::Commands::ConfigOptionSyntax::Get.new(@execution_context).call(name, **opts)
-      raise Git::FailedError, result if result.status.exitstatus != 0
-
-      result.stdout
-    end
-
-    # Lists config entries using the deprecated `config(...)` path
-    #
-    # @param options [Hash] command options
-    #
-    # @option options [String, nil] :file (nil) path to a custom config file
-    #
-    # @return [Hash{String => String}] all visible config entries keyed by name
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def deprecated_config_list(**options)
-      SharedPrivate.assert_valid_opts!(CONFIG_READ_ALLOWED_OPTS, **options)
-      opts = options[:file] ? { file: options[:file] } : {}
-      lines = Git::Commands::ConfigOptionSyntax::List.new(@execution_context).call(**opts).stdout.split("\n")
-      lines.each_with_object({}) do |line, hsh|
-        key, value = line.split('=', 2)
-        hsh[key] = value || ''
-      end
-    end
-
-    # Reads a global config value using the deprecated `global_config(name)` path
+    # Sums the size of every regular file under `dir`
     #
-    # @param name [String] the dotted config key to read
+    # Symbolic links are not followed. Entries that disappear between the
+    # traversal and the `lstat` call are skipped.
     #
-    # @return [String] the config value
+    # @param dir [String] the directory to traverse
     #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def deprecated_global_config_get(name)
-      result = Git::Commands::ConfigOptionSyntax::Get.new(@execution_context).call(name, global: true)
-      raise Git::FailedError, result if result.status.exitstatus != 0
-
-      result.stdout
-    end
-
-    # Lists global config entries using the deprecated `global_config` path
+    # @return [Integer] the total size in bytes of the files under `dir`
     #
-    # @return [Hash{String => String}] all global config entries keyed by name
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def deprecated_global_config_list
-      lines = Git::Commands::ConfigOptionSyntax::List.new(@execution_context).call(global: true).stdout.split("\n")
-      lines.each_with_object({}) do |line, hsh|
-        key, value = line.split('=', 2)
-        hsh[key] = value || ''
+    def repo_size_of_directory(dir)
+      total = 0
+      Find.find(dir) do |path|
+        stat = File.lstat(path)
+        total += stat.size if stat.file?
+      rescue Errno::ENOENT
+        next
       end
-    end
-
-    # Writes a global config value using the deprecated `global_config` path
-    #
-    # @param name [String] the dotted config key to write
-    #
-    # @param value [#to_s] the value to assign
-    #
-    # @return [Git::CommandLine::Result] the command result
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    def deprecated_global_config_set(name, value)
-      Git::Commands::ConfigOptionSyntax::Set.new(@execution_context).call(name, value, global: true)
+      total
     end
 
     # All git config scopes are valid in a repository context

data/lib/git/system_call_guard.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'git/errors'
+
+module Git
+  # Convert `SystemCallError` raised by the gem's own filesystem calls to {Git::Error}
+  #
+  # The gem promises to raise only `ArgumentError` or a subclass of {Git::Error}.
+  # Filesystem calls such as `File.read`, `Dir.chdir`, or `Tempfile.create` can
+  # raise a bare `SystemCallError` (`Errno::ENOENT`, `Errno::EACCES`, and so on).
+  # Wrapping those calls in {.call} keeps the promise: the `SystemCallError` is
+  # re-raised as a {Git::Error} with the original error available as `cause`.
+  #
+  # Helpers that yield to caller-supplied blocks must not relabel errors raised
+  # by the caller's own code. {#unguarded} marks that region so a
+  # `SystemCallError` raised inside it propagates unchanged.
+  #
+  # @example Guard a single filesystem call
+  #   content = Git::SystemCallGuard.call('Failed to read the gitdir pointer file') do
+  #     File.read(path)
+  #   end
+  #
+  # @example Guard setup and cleanup but not the caller's block
+  #   def with_tempfile(&block)
+  #     Git::SystemCallGuard.call('Failed to create a temporary file') do |guard|
+  #       Tempfile.create do |file|
+  #         guard.unguarded { block.call(file) }
+  #       end
+  #     end
+  #   end
+  #
+  # @api private
+  #
+  class SystemCallGuard
+    # Run the block, converting any `SystemCallError` it raises to {Git::Error}
+    #
+    # @param message [String] prefix for the {Git::Error} message
+    #
+    # @return [Object] the value returned by the block
+    #
+    # @raise [Git::Error] if the block raises a `SystemCallError` outside an
+    #   unguarded region
+    #
+    # @yield [guard] the guarded region
+    #
+    # @yieldparam guard [Git::SystemCallGuard] use {#unguarded} to exempt a region
+    #
+    # @yieldreturn [Object] returned as the method's return value
+    #
+    def self.call(message, &)
+      new.call(message, &)
+    end
+
+    # Run the block, converting any `SystemCallError` it raises to {Git::Error}
+    #
+    # @param (see .call)
+    #
+    # @return (see .call)
+    #
+    # @raise (see .call)
+    #
+    # @yield (see .call)
+    #
+    # @yieldparam (see .call)
+    #
+    # @yieldreturn (see .call)
+    #
+    def call(message)
+      yield self
+    rescue SystemCallError => e
+      raise if e.equal?(@unguarded_error)
+
+      raise Git::Error, "#{message}: #{e.message}"
+    end
+
+    # Run the block with `SystemCallError` conversion suspended
+    #
+    # If the block raises a `SystemCallError`, the enclosing {#call} re-raises
+    # that same error unchanged. Any other `SystemCallError` reaching {#call},
+    # including one raised while unwinding from the block's error, is converted.
+    #
+    # @return [Object] the value returned by the block
+    #
+    # @yield the region exempt from conversion
+    #
+    # @yieldreturn [Object] returned as the method's return value
+    #
+    def unguarded
+      yield
+    rescue SystemCallError => e
+      @unguarded_error = e
+      raise
+    end
+  end
+end

data/lib/git/version.rb

@@ -4,7 +4,7 @@ module Git
   # The current gem version
   #
   # @return [String] the current gem version
-  VERSION = '5.6.0'
+  VERSION = '6.0.0'
 
   # Represents a git version with major, minor, and patch components
   #