git 4.4.0 → 5.0.0.beta.1

data/lib/git/version_constraint.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents a git version constraint with minimum and upper bound versions
+  #
+  # Used by {Git::Commands::Base.requires_git_version} to declare version requirements
+  # and by {Git::VersionError} to report constraint violations.
+  #
+  # @example Minimum version only
+  #   constraint = Git::VersionConstraint.new(min: Git::Version.parse('2.30.0'))
+  #   constraint.too_old?(Git::Version.parse('2.28.0'))  #=> true
+  #   constraint.too_new?(Git::Version.parse('2.28.0'))  #=> false
+  #
+  # @example Upper bound only
+  #   constraint = Git::VersionConstraint.new(before: Git::Version.parse('2.50.0'))
+  #   constraint.too_old?(Git::Version.parse('2.51.0'))  #=> false
+  #   constraint.too_new?(Git::Version.parse('2.51.0'))  #=> true
+  #
+  # @example Both bounds
+  #   constraint = Git::VersionConstraint.new(
+  #     min: Git::Version.parse('2.30.0'),
+  #     before: Git::Version.parse('2.50.0')
+  #   )
+  #   constraint.satisfied_by?(Git::Version.parse('2.40.0'))  #=> true
+  #
+  # @api public
+  #
+  VersionConstraint = Data.define(:min, :before) do
+    # @param min [Git::Version, nil] minimum version (inclusive)
+    # @param before [Git::Version, nil] upper bound version (exclusive)
+    def initialize(min: nil, before: nil)
+      super
+    end
+
+    # Check if the given version is too old (below the minimum)
+    #
+    # @param version [Git::Version] the version to check
+    #
+    # @return [Boolean] true if version is below the minimum, false otherwise
+    #
+    def too_old?(version)
+      return false unless min
+
+      version < min
+    end
+
+    # Check if the given version is too new (at or past the upper bound)
+    #
+    # @param version [Git::Version] the version to check
+    #
+    # @return [Boolean] true if version is at or past the upper bound, false otherwise
+    #
+    def too_new?(version)
+      return false unless before
+
+      version >= before
+    end
+
+    # Check if the given version satisfies this constraint
+    #
+    # @param version [Git::Version] the version to check
+    #
+    # @return [Boolean] true if the version satisfies the constraint
+    #
+    def satisfied_by?(version)
+      !too_old?(version) && !too_new?(version)
+    end
+
+    # Return a human-readable representation of this constraint
+    #
+    # @return [String] the constraint in git version range form
+    #
+    def to_s
+      return ">= #{min}, < #{before}" if min && before
+      return ">= #{min}" if min
+      return "< #{before}" if before
+
+      'any version'
+    end
+  end
+end

data/lib/git/worktree.rb

@@ -1,12 +1,52 @@
 # frozen_string_literal: true
 
-require 'git/path'
+require 'git/base'
 
 module Git
   # A worktree in a Git repository
+  #
+  # Represents a single linked or main worktree. Constructed by
+  # {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
+  #   worktree.remove
+  #
+  # @api public
+  #
   class Worktree
-    attr_accessor :full, :dir
+    # Full worktree descriptor including the optional commitish
+    #
+    # @return [String] the filesystem path, space-separated with the commitish
+    #   when one was given at construction time
+    #
+    attr_accessor :full
 
+    # Filesystem path of this worktree
+    #
+    # @return [String] the filesystem path of the worktree directory
+    #
+    attr_accessor :dir
+
+    # Creates a new Worktree object
+    #
+    # @param base [Git::Base, Git::Repository] the repository that owns this
+    #   worktree
+    #
+    # @param dir [String] filesystem path of the worktree
+    #
+    # @param gcommit [String, nil] commitish associated with the worktree;
+    #   when non-nil it is appended to {#full}
+    #
+    # @return [void]
+    #
     def initialize(base, dir, gcommit = nil)
       @full = dir
       @full += " #{gcommit}" unless gcommit.nil?
@@ -15,25 +55,100 @@ module Git
       @gcommit = gcommit
     end
 
+    # Returns the commit (or commitish string) associated with this worktree
+    #
+    # When a commitish string was supplied at construction time (e.g. by
+    # {Git::Worktrees} which passes the raw SHA from `git worktree list`), that
+    # string is returned as-is. Otherwise the value is lazily resolved on first
+    # call via `worktree_repository.gcommit(@full)` and the result is memoized.
+    #
+    # @example When resolved lazily (no commitish at construction)
+    #   worktree = repo.worktree('/path/to/wt')
+    #   worktree.gcommit  # => #<Git::Object::Commit ...>
+    #
+    # @example When the commitish was given at construction
+    #   worktree = repo.worktrees['/path/to/wt']
+    #   worktree.gcommit  # => "4bef5ab8c9..."   (raw SHA string)
+    #
+    # @return [Git::Object::Commit, String] a commit object when lazily
+    #   resolved, or the raw commitish string when pre-set at construction
+    #
+    # @raise [Git::FailedError] if git must resolve the commit and exits with a
+    #   non-zero exit status
+    #
     def gcommit
-      @gcommit ||= @base.gcommit(@full)
+      @gcommit ||= worktree_repository.gcommit(@full)
       @gcommit
     end
 
+    # Creates this worktree on disk
+    #
+    # Runs `git worktree add` for {#dir}, optionally at the commitish passed
+    # at construction time.
+    #
+    # @example Add a worktree
+    #   worktree = repo.worktree('/path/to/new-worktree')
+    #   worktree.add
+    #
+    # @return [String] stdout from the git command
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def add
-      @base.lib.worktree_add(@dir, @gcommit)
+      worktree_repository.worktree_add(@dir, @gcommit)
     end
 
+    # Removes this worktree from disk
+    #
+    # Runs `git worktree remove` for {#dir}.
+    #
+    # @example Remove a worktree
+    #   worktree.remove
+    #
+    # @return [String] stdout from the git command (typically empty)
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def remove
-      @base.lib.worktree_remove(@dir)
+      worktree_repository.worktree_remove(@dir)
     end
 
+    # Returns an array containing the full worktree descriptor
+    #
+    # @example Get the descriptor array
+    #   worktree.to_a  # => ["/path/to/worktree"]
+    #
+    # @return [Array<String>] array containing the full worktree descriptor
+    #
     def to_a
       [@full]
     end
 
+    # Returns the full worktree descriptor as a string
+    #
+    # @example Get the descriptor string
+    #   worktree.to_s  # => "/path/to/worktree"
+    #
+    # @return [String] the full worktree descriptor (path and optional commitish)
+    #
     def to_s
       @full
     end
+
+    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
+    end
   end
 end

data/lib/git/worktrees.rb

@@ -1,47 +1,147 @@
 # frozen_string_literal: true
 
+require 'git/base'
+
 module Git
-  # object that holds all the available worktrees
+  # Collection of all Git worktrees in a repository
+  #
+  # Wraps every linked and main worktree and provides enumeration and
+  # path-based lookup.
+  #
+  # 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 Enumerate all worktrees
+  #   worktrees = repo.worktrees
+  #   worktrees.each { |wt| puts wt.dir }
+  #
+  # @api public
+  #
   class Worktrees
     include Enumerable
 
+    # Creates a new Worktrees collection populated from the given repository
+    #
+    # @param base [Git::Base, Git::Repository] the repository to enumerate
+    #   worktrees from
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def initialize(base)
       @worktrees = {}
 
       @base = base
 
-      # Array contains [dir, git_hash]
-      @base.lib.worktrees_all.each do |w|
+      worktree_repository.worktrees_all.each do |w|
         @worktrees[w[0]] = Git::Worktree.new(@base, w[0], w[1])
       end
     end
 
-    # array like methods
-
+    # Returns the number of worktrees in the collection
+    #
+    # @example Count all worktrees
+    #   repo.worktrees.size  # => 2
+    #
+    # @return [Integer] the total number of worktrees
+    #
     def size
       @worktrees.size
     end
 
+    # Iterates over every worktree in the collection
+    #
+    # @overload each
+    #
+    #   @example Get an enumerator over all worktrees
+    #     enum = repo.worktrees.each
+    #
+    #   @return [Enumerator<Git::Worktree>] an enumerator over all worktrees
+    #
+    # @overload each(&block)
+    #
+    #   @example Print every worktree path
+    #     repo.worktrees.each { |wt| puts wt.dir }
+    #
+    #   @return [Array<Git::Worktree>] the full list of worktrees
+    #
+    #   @yield [worktree] passes each worktree to the block
+    #
+    #   @yieldparam worktree [Git::Worktree] a worktree in the repository
+    #
+    #   @yieldreturn [void]
+    #
     def each(&)
       @worktrees.values.each(&)
     end
 
+    # Returns the worktree with the given path
+    #
+    # Supports lookup by the filesystem path of the worktree directory or by
+    # the full worktree descriptor (path and optional commitish).
+    #
+    # @example Look up a worktree by path
+    #   repo.worktrees['/path/to/linked-worktree']
+    #
+    # @param worktree_name [#to_s] the path (or full descriptor) of the
+    #   worktree to retrieve
+    #
+    # @return [Git::Worktree, nil] the matching worktree, or `nil` if not found
+    #
     def [](worktree_name)
       @worktrees.values.each_with_object(@worktrees) do |worktree, worktrees|
         worktrees[worktree.full] ||= worktree
       end[worktree_name.to_s]
     end
 
+    # Returns a string listing all worktrees, one per line
+    #
+    # @example Display all worktrees
+    #   puts repo.worktrees.to_s
+    #
+    # @return [String] a newline-separated listing of worktree descriptors
+    #
     def to_s
-      out = ''
+      out = +''
       @worktrees.each_value do |b|
         out << b.to_s << "\n"
       end
       out
     end
 
+    # Removes stale administrative files for worktrees that no longer exist
+    #
+    # Runs `git worktree prune` to clean up any lingering worktree metadata
+    # for linked worktrees whose directories have been deleted.
+    #
+    # @example Prune stale worktree metadata
+    #   repo.worktrees.prune
+    #
+    # @return [String] stdout from the git command (typically empty)
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def prune
-      @base.lib.worktree_prune
+      worktree_repository.worktree_prune
+    end
+
+    private
+
+    # Resolves the {Git::Repository} for this collection of worktrees
+    #
+    # 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 to enumerate worktrees
+    #
+    # @api private
+    #
+    def worktree_repository
+      @base.is_a?(Git::Base) ? @base.facade_repository : @base
     end
   end
 end

data/lib/git.rb

@@ -1,57 +1,63 @@
 # frozen_string_literal: true
 
+require 'active_support'
 require 'active_support/deprecation'
 
-# Define Git::Deprecation before requiring the rest of the library to ensure that
-# any deprecation warnings emitted during the loading of the library are properly
-# configured according to the GIT_DEPRECATION_BEHAVIOR environment variable.
-#
+require 'git/version'
+
 module Git
-  # The deprecation instance used to emit deprecation warnings for the Git gem
-  #
-  # @api public
   Deprecation = ActiveSupport::Deprecation.new('5.0.0', 'Git')
 
-  if (behavior = ENV.fetch('GIT_DEPRECATION_BEHAVIOR', nil))
-    behavior = behavior.strip
-    allowed_behaviors = ActiveSupport::Deprecation::DEFAULT_BEHAVIORS.keys.map(&:to_s)
-
-    unless allowed_behaviors.include?(behavior)
-      raise ArgumentError,
-            "Invalid GIT_DEPRECATION_BEHAVIOR=#{behavior.inspect}; " \
-            "expected one of: #{allowed_behaviors.join(', ')}"
-    end
-
-    Deprecation.behavior = behavior.to_sym
-  end
+  # Minimum git version required by this gem
+  #
+  # Commands and features may require newer versions, but this is the absolute
+  # minimum supported version for the gem as a whole.
+  #
+  # @return [Git::Version]
+  #
+  # @api public
+  #
+  MINIMUM_GIT_VERSION = Version.parse('2.28.0')
 end
 
 require 'git/author'
-require 'git/base'
 require 'git/branch'
+require 'git/branch_info'
 require 'git/branches'
 require 'git/command_line_result'
 require 'git/command_line'
+require 'git/commands/init'
 require 'git/config'
 require 'git/diff'
+require 'git/diff_file_numstat_info'
+require 'git/diff_file_patch_info'
+require 'git/diff_file_raw_info'
+require 'git/diff_info'
+require 'git/parsers/diff'
+require 'git/diff_result'
+require 'git/dirstat_info'
 require 'git/encoding_utils'
 require 'git/errors'
 require 'git/escaped_path'
+require 'git/execution_context'
+require 'git/file_ref'
 require 'git/fsck_object'
 require 'git/fsck_result'
-require 'git/index'
+require 'git/version_constraint'
 require 'git/lib'
 require 'git/log'
 require 'git/object'
-require 'git/path'
 require 'git/remote'
 require 'git/repository'
+require 'git/base'
 require 'git/status'
 require 'git/stash'
+require 'git/stash_info'
 require 'git/stashes'
+require 'git/tag_delete_failure'
+require 'git/tag_delete_result'
+require 'git/tag_info'
 require 'git/url'
-require 'git/version'
-require 'git/working_directory'
 require 'git/worktree'
 require 'git/worktrees'
 
@@ -62,29 +68,13 @@ require 'git/worktrees'
 #
 # @author Scott Chacon (mailto:schacon@gmail.com)
 #
-module Git # rubocop:disable Style/OneClassPerFile
-  # Internal alias for Git::Lib, used by the gem itself after the public constant
-  # is deprecated. Code outside the gem should not reference this constant.
-  # @api private
-  LibImpl = remove_const(:Lib)
-
-  # @api private
-  def self.const_missing(name)
-    return super unless name == :Lib
-
-    Git::Deprecation.warn(
-      'Git::Lib is deprecated and will be removed in version 5.x. ' \
-      'Use the #lib accessor on the object returned by Git.init, Git.open, or Git.clone instead.'
-    )
-    const_set(:Lib, LibImpl)
-  end
-
+module Git
   # g.config('user.name', 'Scott Chacon') # sets value
   # g.config('user.email', 'email@email.com')  # sets value
   # g.config('user.name')  # returns 'Scott Chacon'
   # g.config # returns whole config hash
   def config(name = nil, value = nil)
-    lib = LibImpl.new
+    lib = Git::Lib.new
     if name && value
       # set value
       lib.config_set(name, value)
@@ -158,9 +148,9 @@ module Git # rubocop:disable Style/OneClassPerFile
   #
   # @param directory [Pathname, nil] The directory to clone into
   #
-  #   If `directory` is a relative directory it is relative to the `path` option if
-  #   given. If `path` is not given, `directory` is relative to the current working
-  #   directory.
+  #   If `directory` is a relative path it is relative to the `:chdir` option if
+  #   given. If `:chdir` is not given, `directory` is relative to the current
+  #   working directory.
   #
   #   If `nil`, `directory` will be set to the basename of the last component of
   #   the path from the `repository_url`. For example, for the URL:
@@ -211,9 +201,14 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @option options [String] :origin Use the value instead `origin` to track
   #   the upstream repository.
   #
-  # @option options [Pathname] :path The directory to clone into.  May be used
-  #   as an alternative to the `directory` parameter.  If specified, the
-  #   `path` option is used instead of the `directory` parameter.
+  # @option options [Pathname] :chdir Run `git clone` from within this directory.
+  #
+  #   The `directory` parameter (or the repository basename when `directory` is nil)
+  #   is resolved relative to `:chdir`, just as if you had `cd`'d into it before
+  #   running `git clone`. The returned path is the join of `:chdir` and the
+  #   cloned directory path.
+  #
+  # @option options [Pathname] :path Deprecated — use `:chdir` instead.
   #
   # @option options [Boolean] :recursive After the clone is created, initialize
   #   all submodules within, using their default settings.
@@ -226,8 +221,10 @@ module Git # rubocop:disable Style/OneClassPerFile
   #
   # @example Clone into a different directory `my-ruby-git`
   #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', 'my-ruby-git')
-  #   # or:
-  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', path: 'my-ruby-git')
+  #
+  # @example Clone into a specific parent directory
+  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', chdir: '/path/to/projects')
+  #   # clones into /path/to/projects/ruby-git
   #
   # @example Create a bare repository in the directory `ruby-git.git`
   #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', bare: true)
@@ -255,8 +252,6 @@ module Git # rubocop:disable Style/OneClassPerFile
   #   of the cloned local working copy or cloned repository.
   #
   def self.clone(repository_url, directory = nil, options = {})
-    clone_to_options = options.slice(:bare, :mirror)
-    directory ||= Git::URL.clone_to(repository_url, **clone_to_options)
     Base.clone(repository_url, directory, options)
   end
 
@@ -322,7 +317,7 @@ module Git # rubocop:disable Style/OneClassPerFile
   # g.config('user.name')  # returns 'Scott Chacon'
   # g.config # returns whole config hash
   def self.global_config(name = nil, value = nil)
-    lib = LibImpl.new(nil, nil)
+    lib = Git::Lib.new(nil, nil)
     if name && value
       # set value
       lib.global_config_set(name, value)
@@ -364,6 +359,8 @@ module Git # rubocop:disable Style/OneClassPerFile
   #   and converted to an absolute path using
   #   [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
   #
+  # @option options [Pathname] :separate_git_dir Alias for `:repository`.
+  #
   # @option options [String, nil] :git_ssh An optional custom SSH command
   #
   #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
@@ -392,7 +389,30 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @see https://git-scm.com/docs/git-init git init
   #
   def self.init(directory = '.', options = {})
-    Base.init(directory, options)
+    require_relative 'git/commands/init'
+
+    options = options.dup
+    options[:repository] ||= options.delete(:separate_git_dir)
+    init_opts = options.slice(:bare, :initial_branch)
+    init_opts[:separate_git_dir] = options[:repository] if options.key?(:repository)
+    Git::Commands::Init.new(Git::Lib.new(nil, options[:log])).call(directory, **init_opts)
+
+    open_initialized_repository(directory, options)
+  end
+
+  # Open the repository after initialization
+  #
+  # @param directory [String] the directory containing the repository
+  # @param options [Hash] the options hash
+  # @return [Git::Base] the opened repository
+  # @api private
+  #
+  private_class_method def self.open_initialized_repository(directory, options)
+    if options[:bare]
+      Git.bare(options[:repository] || directory, options.slice(:log, :git_ssh).compact)
+    else
+      Git.open(directory, options.slice(:log, :git_ssh, :index, :repository).compact)
+    end
   end
 
   # returns a Hash containing information about the references
@@ -404,7 +424,7 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @param [String|NilClass] location the target repository location or nil for '.'
   # @return [{String=>Hash}] the available references of the target repo.
   def self.ls_remote(location = nil, options = {})
-    LibImpl.new.ls_remote(location, options)
+    Git::Lib.new.ls_remote(location, options)
   end
 
   # Open a an existing Git working directory
@@ -461,6 +481,37 @@ module Git # rubocop:disable Style/OneClassPerFile
     Base.open(working_dir, options)
   end
 
+  # Return the version of a git binary as a {Git::Version}
+  #
+  # @param binary_path [String, nil] path to the git binary; defaults to
+  #   `Git::Base.config.binary_path`
+  #
+  # @return [Git::Version] the parsed git version
+  #
+  # @raise [Git::UnexpectedResultError] if the version output cannot be parsed
+  #
+  # @raise [Git::FailedError] if the git binary exits with a non-zero status
+  #
+  # @raise [Git::Error] if the binary is not found or fails to launch
+  #
+  # @example Default binary
+  #   Git.git_version #=> #<Git::Version 2.42.0>
+  #
+  # @example Explicit binary path
+  #   Git.git_version('/opt/homebrew/bin/git') #=> #<Git::Version 2.42.0>
+  #
+  def self.git_version(binary_path = nil)
+    path = binary_path || Git::Base.config.binary_path
+    Git::Lib.cached_git_version(path) { run_git_version(path) }
+  end
+
+  # @api private
+  def self.run_git_version(path)
+    output = Git::Commands::Version.new(Git::ExecutionContext::Global.new(binary_path: path)).call.stdout
+    Git::Version.parse(output)
+  end
+  private_class_method :run_git_version
+
   # Return the version of the git binary
   #
   # @example
@@ -468,7 +519,17 @@ module Git # rubocop:disable Style/OneClassPerFile
   #
   # @return [Array<Integer>] the version of the git binary
   #
+  # @deprecated Use {Git.git_version} instead, which returns a {Git::Version} (not an Array).
+  #   For the legacy array shape, call: `Git.git_version.to_a`.
+  #   The optional binary_path argument is preserved: `Git.git_version(binary_path)`.
+  #
   def self.binary_version(binary_path = Git::Base.config.binary_path)
-    Base.binary_version(binary_path)
+    Git::Deprecation.warn(
+      'Git.binary_version is deprecated and will be removed in 6.0. ' \
+      'Use Git.git_version instead, which returns a Git::Version ' \
+      '(not an Array). For the legacy array shape, call: Git.git_version.to_a. ' \
+      'The optional binary_path argument is preserved: Git.git_version(binary_path).'
+    )
+    git_version(binary_path).to_a
   end
 end