git 4.4.5 → 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