git 5.0.0.beta.1 → 5.0.0.beta.3

data/lib/git/repository.rb

@@ -3,17 +3,21 @@
 require 'find'
 require 'pathname'
 
+require 'git/configuring'
+require 'git/deprecation'
 require 'git/execution_context/repository'
 require 'git/repository/branching'
+require 'git/repository/context_helpers'
 require 'git/repository/committing'
-require 'git/repository/configuring'
 require 'git/repository/diffing'
+require 'git/repository/factories'
 require 'git/repository/inspecting'
 require 'git/repository/logging'
+require 'git/repository/maintenance'
 require 'git/repository/merging'
 require 'git/repository/object_operations'
-require 'git/repository/path_resolver'
 require 'git/repository/remote_operations'
+require 'git/repository/shared_private'
 require 'git/repository/staging'
 require 'git/repository/stashing'
 require 'git/repository/status_operations'
@@ -44,13 +48,17 @@ module Git
   #
   # @api public
   #
-  class Repository
+  class Repository # rubocop:disable Metrics/ClassLength
+    extend Git::Repository::Factories
+
+    include Git::Configuring
     include Git::Repository::Branching
+    include Git::Repository::ContextHelpers
     include Git::Repository::Committing
-    include Git::Repository::Configuring
     include Git::Repository::Diffing
     include Git::Repository::Inspecting
     include Git::Repository::Logging
+    include Git::Repository::Maintenance
     include Git::Repository::Merging
     include Git::Repository::ObjectOperations
     include Git::Repository::RemoteOperations
@@ -59,133 +67,22 @@ module Git
     include Git::Repository::StatusOperations
     include Git::Repository::WorktreeOperations
 
-    # Open a working copy at an existing path
-    #
-    # The new repository factories are additive scaffolding introduced by the
-    # architectural redesign. The top-level {Git.open} entry point still returns a
-    # {Git::Base} object; this method exists so future work can route construction
-    # through {Git::Repository} without changing the public entry points.
-    #
-    # Note: this method opens working copies only. To open a bare repository, use
-    # {Git::Repository.bare}.
-    #
-    # @example Open the working copy in the current directory
-    #   repository = Git::Repository.open('.')
-    #
-    # @param working_dir [String] the path to the root of the working copy
-    #
-    #   May be any path inside the working tree when `:repository` is not given.
-    #
-    # @param options [Hash] options that control how the repository is located
-    #
-    # @option options [String] :repository a non-standard path to the `.git`
-    #   directory
-    #
-    #   When given, `working_dir` is used as-is (the working tree root is not
-    #   auto-detected).
-    #
-    # @option options [String] :index a non-standard path to the index file
-    #
-    # @option options [Logger] :log a logger forwarded to the command layer
-    #
-    # @option options [String, nil, :use_global_config] :git_ssh path to a custom SSH executable;
-    #   pass `:use_global_config` (the default) to use `Git::Base.config.git_ssh`
-    #
-    # @option options [String, :use_global_config] :binary_path path to the git binary;
-    #   pass `:use_global_config` (the default) to use `Git::Base.config.binary_path`
-    #
-    # @return [Git::Repository] a repository bound to the resolved paths
-    #
-    # @raise [ArgumentError] if `working_dir` is not a directory or is not inside
-    #   a git working tree
-    #
-    def self.open(working_dir, options = {})
-      raise ArgumentError, "'#{working_dir}' is not a directory" unless Dir.exist?(working_dir)
-
-      working_dir = resolve_open_working_dir(working_dir, options) unless options[:repository]
+    CONFIG_SET_ALLOWED_OPTS = %i[file].freeze
+    private_constant :CONFIG_SET_ALLOWED_OPTS
 
-      paths = PathResolver.resolve_paths(
-        working_directory: working_dir,
-        repository: options[:repository],
-        index: options[:index]
-      )
-
-      from_paths(options, paths)
-    end
+    CONFIG_READ_ALLOWED_OPTS = %i[file].freeze
+    private_constant :CONFIG_READ_ALLOWED_OPTS
 
-    # Open an existing bare repository at `git_dir`
-    #
-    # The new repository factories are additive scaffolding introduced by the
-    # architectural redesign. The top-level {Git.bare} entry point still returns a
-    # {Git::Base} object; this method exists so future work can route construction
-    # through {Git::Repository} without changing the public entry points.
-    #
-    # @example Open a bare repository
-    #   repository = Git::Repository.bare('/path/to/repo.git')
-    #
-    # @param git_dir [String] the path to the bare repository directory
-    #
-    # @param options [Hash] options forwarded to the constructed repository
-    #
-    # @option options [Logger] :log a logger forwarded to the command layer
-    #
-    # @option options [String, nil, :use_global_config] :git_ssh path to a custom SSH executable;
-    #   pass `:use_global_config` (the default) to use `Git::Base.config.git_ssh`
-    #
-    # @option options [String, :use_global_config] :binary_path path to the git binary;
-    #   pass `:use_global_config` (the default) to use `Git::Base.config.binary_path`
-    #
-    # @return [Git::Repository] a repository bound to the bare repository directory
-    #
-    def self.bare(git_dir, options = {})
-      paths = PathResolver.resolve_paths(repository: git_dir, bare: true)
-
-      from_paths(options, paths)
-    end
-
-    # Resolve the worktree root to use as the working directory for `.open`
-    #
-    # Delegates to {PathResolver.root_of_worktree}, forwarding `:binary_path`
-    # and `:git_ssh` from `options`.
-    #
-    # @param working_dir [String] a path inside the working tree
-    #
-    # @param options [Hash] the caller-supplied options hash from `.open`
-    #
-    # @return [String] the absolute path to the root of the working tree
-    #
-    # @raise [ArgumentError] if `working_dir` is not inside a git working tree
-    #
-    # @api private
-    #
-    def self.resolve_open_working_dir(working_dir, options)
-      PathResolver.root_of_worktree(
-        working_dir,
-        binary_path: options.fetch(:binary_path, :use_global_config),
-        git_ssh: options.fetch(:git_ssh, :use_global_config)
-      )
-    end
-    private_class_method :resolve_open_working_dir
+    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
 
-    # Build a repository from caller options and resolved paths
-    #
-    # @param options [Hash] the caller-supplied options (`:git_ssh`,
-    #   `:binary_path`, `:log`)
-    #
-    # @param paths [Hash{Symbol => (String, nil)}] the resolved
-    #   `:working_directory`, `:repository`, and `:index` paths
-    #
-    # @return [Git::Repository] the constructed repository
-    #
-    # @api private
-    #
-    def self.from_paths(options, paths)
-      execution_context = Git::ExecutionContext::Repository.from_hash(
-        options.merge(paths), logger: options[:log]
-      )
-      new(execution_context: execution_context)
-    end
-    private_class_method :from_paths
+    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
@@ -239,6 +136,202 @@ 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
+    def git_dir = execution_context.git_dir
+
+    # @return [String, nil] the working directory path
+    #
+    # @api private
+    def git_work_dir = execution_context.git_work_dir
+
+    # @return [String, nil] the index file path
+    #
+    # @api private
+    def git_index_file = execution_context.git_index_file
+
+    # @return [Git::Version] the installed git version
+    #
+    # @api private
+    def git_version(timeout: nil) = execution_context.git_version(timeout: timeout)
+
+    # @return [String, nil] the SSH wrapper path
+    #
+    # @api private
+    def git_ssh = execution_context.git_ssh
+
+    # @return [String, :use_global_config] the path to the git binary
+    #
+    # @api private
+    def binary_path = execution_context.binary_path
+
+    # Read or write 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.
+    #
+    # @overload config(options = {})
+    #
+    #   @example List all config entries
+    #     repo.config #=> { "user.name" => "Alice", "core.bare" => "false" }
+    #
+    #   @example List all entries from a custom config file
+    #     repo.config(file: '/path/to/.gitconfig')
+    #     #=> { "user.name" => "Alice", "core.bare" => "false" }
+    #
+    #   @param options [Hash] options for the list operation
+    #
+    #   @option options [String, nil] :file (nil) path to a custom config file
+    #     to read from instead of the default resolution chain
+    #
+    #   @return [Hash{String => String}] all visible config entries, keyed by
+    #     their full dotted key names (e.g. `"user.name"`)
+    #
+    #   @raise [ArgumentError] if unsupported options are provided
+    #
+    # @overload config(name, options = {})
+    #
+    #   @example Read the committer name from config
+    #     repo.config('user.name') #=> "Alice"
+    #
+    #   @example Read a value from a custom config file
+    #     repo.config('user.name', file: '/path/to/.gitconfig') #=> "Alice"
+    #
+    #   @param name [String] the dotted config key to look up (e.g.
+    #     `"user.name"`)
+    #
+    #   @param options [Hash] options for the get operation
+    #
+    #   @option options [String, nil] :file (nil) path to a custom config file
+    #     to read from instead of the default resolution chain
+    #
+    #   @return [String] the value of the config entry
+    #
+    #   @raise [ArgumentError] if unsupported options are provided
+    #
+    # @overload config(name, value, options = {})
+    #
+    #   @example Set the committer name in local config
+    #     repo.config('user.name', 'Alice')
+    #
+    #   @example Write a value to a custom config file
+    #     repo.config('user.name', 'Alice', file: '/path/to/custom/config')
+    #
+    #   @param name [String] the dotted config key to write (e.g.
+    #     `"user.name"`)
+    #
+    #   @param value [#to_s] the value to assign; must not be `nil` (a `nil`
+    #     value is treated as "no value" and routes to the get overload).
+    #     Must not be a `Hash` (a Hash is treated as the `options` argument;
+    #     call `value.to_s` explicitly before passing if a stringified Hash
+    #     is genuinely needed). Any other non-nil object is converted to a
+    #     String via `#to_s` before being passed to git
+    #
+    #   @param options [Hash] options for the set operation
+    #
+    #   @option options [String, nil] :file (nil) path to a custom config file
+    #     to write to instead of the repository's default `.git/config`
+    #
+    #   @return [Git::CommandLineResult] the raw result of
+    #     `git config <name> <value>`
+    #
+    #   @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::CommandLineResult] 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`)
@@ -265,5 +358,72 @@ module Git
       end
       total
     end
+
+    private
+
+    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
+
+    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
+
+    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
+
+    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
+
+    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
+
+    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 || ''
+      end
+    end
+
+    def deprecated_global_config_set(name, value)
+      Git::Commands::ConfigOptionSyntax::Set.new(@execution_context).call(name, value, global: true)
+    end
+
+    # All git config scopes are valid in a repository context
+    #
+    # @return [void]
+    #
+    def assert_valid_scope!(**)
+      nil
+    end
   end
 end

data/lib/git/stash.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'git/base'
-
 module Git
   # Represents a single stash entry in a Git repository
   #
@@ -18,7 +16,7 @@ module Git
     # When `existing` is `false` (the default), immediately calls {#save} to push
     # the current working-directory state onto the stash stack.
     #
-    # @param base [Git::Repository, Git::Base] the git repository
+    # @param base [Git::Repository] the git repository
     #
     # @param message [String] the stash message
     #
@@ -93,15 +91,10 @@ module Git
 
     private
 
-    # Returns the facade interface for stash operations
-    #
-    # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
-    # The `is_a?` guard will be removed when {Git::Base} is deleted in Phase 4.
-    #
     # @return [Git::Repository]
     #
     def stash_repository
-      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+      @base
     end
   end
 end

data/lib/git/stashes.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'git/base'
-
 module Git
   # Collection of stash entries for a Git repository
   #
@@ -21,7 +19,7 @@ module Git
     #
     # Loads all existing stash entries from the repository at construction time.
     #
-    # @param base [Git::Repository, Git::Base] the git repository
+    # @param base [Git::Repository] the git repository
     #
     # @return [void]
     #
@@ -161,13 +159,10 @@ module Git
 
     # Returns the facade interface for stash operations
     #
-    # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
-    # The `is_a?` guard will be removed when {Git::Base} is deleted in Phase 4.
-    #
     # @return [Git::Repository]
     #
     def stash_repository
-      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+      @base
     end
   end
 end

data/lib/git/status.rb

@@ -14,7 +14,7 @@ module Git
 
     # Create a new Status for the given repository
     #
-    # @param base [Git::Base, Git::Repository] the git object backing this status
+    # @param base [Git::Repository] the git object backing this status
     #
     def initialize(base)
       @base = base
@@ -172,17 +172,15 @@ module Git
 
     # Return `true` when git is configured to ignore filename case
     #
-    # Reads `core.ignoreCase` from the repository config. Returns `false` if
-    # the config value is absent or if reading it raises {Git::FailedError}.
+    # Reads `core.ignoreCase` with {Git::Repository#config_get}. Returns `false`
+    # when the config value is absent.
     #
     # @return [Boolean] `true` when `core.ignoreCase` is `"true"`
     #
     def ignore_case?
-      return @_ignore_case if defined?(@_ignore_case)
+      return @ignore_case if defined?(@ignore_case)
 
-      @_ignore_case = (@base.config('core.ignoreCase') == 'true')
-    rescue Git::FailedError
-      @_ignore_case = false
+      @ignore_case = (@base.config_get('core.ignoreCase')&.value == 'true')
     end
   end
 end
@@ -239,7 +237,7 @@ module Git
 
       # Initialize a new StatusFile with the given git object and data hash
       #
-      # @param base [Git::Base, Git::Repository] the git object
+      # @param base [Git::Repository] the git object
       #
       # @param hash [Hash] raw status data for this file
       #
@@ -281,18 +279,10 @@ module Git
     class StatusFileFactory
       # Create a new factory backed by the given git object
       #
-      # When `base` is a {Git::Repository} (which exposes `#diff_index`
-      # directly), it is used as the data provider. When `base` is a
-      # {Git::Base} (the legacy path), `base.lib` is used instead.
-      #
-      # @param base [Git::Base, Git::Repository] the git object used as the
-      #   status data provider
+      # @param base [Git::Repository] the git object used as the status data provider
       #
       def initialize(base)
         @base = base
-        # When base is Git::Repository (which exposes #diff_index directly),
-        # use it as the data provider. Otherwise use base.lib (legacy path).
-        @provider = base.respond_to?(:diff_index) ? base : base.lib
       end
 
       # Gather all status data and build a hash of file paths to StatusFile objects
@@ -314,7 +304,7 @@ module Git
       # @return [Hash{String => Hash}] raw per-file status data keyed by path
       #
       def fetch_all_files_data
-        files = @provider.ls_files # Start with files tracked in the index.
+        files = @base.ls_files # Start with files tracked in the index.
         merge_untracked_files(files)
         merge_modified_files(files)
         merge_head_diffs(files)
@@ -328,7 +318,7 @@ module Git
       # @return [void]
       #
       def merge_untracked_files(files)
-        @provider.untracked_files.each do |file|
+        @base.untracked_files.each do |file|
           files[file] = { path: file, untracked: true }
         end
       end
@@ -341,7 +331,7 @@ module Git
       #
       def merge_modified_files(files)
         # Merge changes between the index and the working directory.
-        @provider.diff_files.each do |path, data|
+        @base.diff_files.each do |path, data|
           (files[path] ||= {}).merge!(data)
         end
       end
@@ -353,12 +343,11 @@ module Git
       # @return [void]
       #
       def merge_head_diffs(files)
-        # Git::Repository exposes #no_commits?; Git::Lib exposes #empty?.
-        is_empty = @provider.respond_to?(:no_commits?) ? @provider.no_commits? : @provider.empty?
+        is_empty = @base.no_commits?
         return if is_empty
 
         # Merge changes between HEAD and the index.
-        @provider.diff_index('HEAD').each do |path, data|
+        @base.diff_index('HEAD').each do |path, data|
           (files[path] ||= {}).merge!(data)
         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.0.0.beta.1'
+  VERSION = '5.0.0.beta.3'
 
   # Represents a git version with major, minor, and patch components
   #
@@ -100,7 +100,7 @@ module Git
     # Return the version as an array of integers
     #
     # Useful when legacy code expects the array shape returned by the
-    # deprecated {Git::Lib#current_command_version} method.
+    # deprecated `Git::Lib#current_command_version` method.
     #
     # @return [Array<Integer>] [major, minor, patch]
     #

data/lib/git/worktree.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'git/base'
-
 module Git
   # A worktree in a Git repository
   #
@@ -9,11 +7,6 @@ module Git
   # {Git::Repository::WorktreeOperations#worktree} or populated by
   # {Git::Worktrees}.
   #
-  # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy form)
-  # as the `base` argument. The `is_a?(Git::Base)` guard routes git operations
-  # through the facade repository and will be removed when {Git::Base} is
-  # deleted in Phase 4.
-  #
   # @example Add and remove a linked worktree
   #   worktree = repo.worktree('/path/to/new-worktree')
   #   worktree.add
@@ -37,7 +30,7 @@ module Git
 
     # Creates a new Worktree object
     #
-    # @param base [Git::Base, Git::Repository] the repository that owns this
+    # @param base [Git::Repository] the repository that owns this
     #   worktree
     #
     # @param dir [String] filesystem path of the worktree
@@ -137,18 +130,12 @@ module Git
 
     private
 
-    # Resolves the {Git::Repository} for worktree operations
-    #
-    # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
-    # The `is_a?(Git::Base)` guard will be removed when {Git::Base} is deleted
-    # in Phase 4.
-    #
     # @return [Git::Repository] the repository used for worktree operations
     #
     # @api private
     #
     def worktree_repository
-      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+      @base
     end
   end
 end