git 1.19.1 → 5.5.0

data/lib/git/url.rb

@@ -8,9 +8,10 @@ module Git
   # Any URL that can be passed to `git clone` can be parsed by this class.
   #
   # @see https://git-scm.com/docs/git-clone#_git_urls GIT URLs
-  # @see https://github.com/sporkmonger/addressable Addresable::URI
   #
-  # @api public
+  # @see https://github.com/sporkmonger/addressable Addressable::URI
+  #
+  # @api private
   #
   class URL
     # Regexp used to match a Git URL with an alternative SSH syntax
@@ -23,14 +24,14 @@ module Git
       :(?!/)                 # : serparator is required, but must not be followed by /
       (?<path>.*?)           # path is required
       $
-    }x.freeze
+    }x
 
     # Parse a Git URL and return an Addressable::URI object
     #
     # The URI returned can be converted back to a string with 'to_s'. This is
     # guaranteed to return the same URL string that was parsed.
     #
-    # @example
+    # @example Parsing clone target from HTTPS and local paths
     #   uri = Git::URL.parse('https://github.com/ruby-git/ruby-git.git')
     #     #=> #<Addressable::URI:0x44c URI:https://github.com/ruby-git/ruby-git.git>
     #   uri.scheme #=> "https"
@@ -54,11 +55,15 @@ module Git
 
     # The directory `git clone` would use for the repository directory for the given URL
     #
-    # @example
+    # @example Deriving the clone directory name
     #   Git::URL.clone_to('https://github.com/ruby-git/ruby-git.git') #=> 'ruby-git'
     #
     # @param url [String] the Git URL containing the repository directory
     #
+    # @param bare [Boolean] whether the repository should be cloned as bare
+    #
+    # @param mirror [Boolean] whether the repository should be cloned as a mirror
+    #
     # @return [String] the name of the repository directory
     #
     def self.clone_to(url, bare: false, mirror: false)
@@ -80,7 +85,7 @@ module Git
   # This class is necessary to ensure that #to_s returns the same string
   # that was passed to the initializer.
   #
-  # @api public
+  # @api private
   #
   class GitAltURI < Addressable::URI
     # Create a new GitAltURI object
@@ -90,7 +95,9 @@ module Git
     #   uri.to_s #=> 'james@github.com/james/ruby-git'
     #
     # @param user [String, nil] the user from the URL or nil
+    #
     # @param host [String] the host from the URL
+    #
     # @param path [String] the path from the URL
     #
     def initialize(user:, host:, path:)
@@ -118,9 +125,9 @@ module Git
     #
     def to_s
       if user
-        "#{user}@#{host}:#{path[1..-1]}"
+        "#{user}@#{host}:#{path[1..]}"
       else
-        "#{host}:#{path[1..-1]}"
+        "#{host}:#{path[1..]}"
       end
     end
   end

data/lib/git/version.rb

@@ -1,5 +1,116 @@
+# frozen_string_literal: true
+
 module Git
   # The current gem version
-  # @return [String] the current gem version.
-  VERSION='1.19.1'
+  #
+  # @return [String] the current gem version
+  VERSION = '5.5.0'
+
+  # Represents a git version with major, minor, and patch components
+  #
+  # Git versions follow a strict major.minor.patch format. This class provides
+  # parsing from git command output (which may include platform suffixes) and
+  # comparison operations for version gating.
+  #
+  # @!attribute [r] major
+  #   The major version number
+  #
+  #   @return [Integer]
+  #
+  # @!attribute [r] minor
+  #   The minor version number
+  #
+  #   @return [Integer]
+  #
+  # @!attribute [r] patch
+  #   The patch version number
+  #
+  #   @return [Integer]
+  #
+  # @example Creating a version directly
+  #   version = Git::Version.new(2, 42, 1)
+  #   version.to_s  #=> "2.42.1"
+  #
+  # @example Parsing from git version output
+  #   Git::Version.parse('git version 2.42.1')  #=> Git::Version.new(2, 42, 1)
+  #   Git::Version.parse('2.39.2 (Apple Git-143)')  #=> Git::Version.new(2, 39, 2)
+  #
+  # @example Parsing versions with platform suffixes
+  #   Git::Version.parse('2.42.0.windows.1')  #=> Git::Version.new(2, 42, 0)
+  #
+  # @example Comparing versions
+  #   Git::Version.new(2, 42, 1) > Git::Version.new(2, 28, 0)  #=> true
+  #
+  # @api public
+  #
+  Version = Data.define(:major, :minor, :patch) do
+    include Comparable
+
+    # Parse a version string into a Version object
+    #
+    # Handles git's version output format, stripping platform suffixes
+    # (like `.windows.1` or `.vfs.0`) and padding two-segment versions
+    # to three segments.
+    #
+    # @example Parse various version string formats
+    #   Git::Version.parse('2.42.1')  #=> Git::Version.new(2, 42, 1)
+    #   Git::Version.parse('git version 2.42.1')  #=> Git::Version.new(2, 42, 1)
+    #   Git::Version.parse('2.42.0.windows.1')  #=> Git::Version.new(2, 42, 0)
+    #
+    # @param string [String] version string to parse
+    #
+    # @return [Git::Version] the parsed version
+    #
+    # @raise [Git::UnexpectedResultError] if the string cannot be parsed as a version
+    #
+    def self.parse(string)
+      version_match = string&.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
+      raise Git::UnexpectedResultError, "Invalid version: #{string.inspect}" unless version_match
+
+      major = version_match[1].to_i
+      minor = version_match[2].to_i
+      patch = (version_match[3] || '0').to_i
+
+      new(major, minor, patch)
+    end
+
+    # Compare this version to another
+    #
+    # @param other [Git::Version] the version to compare to
+    #
+    # @return [Integer] -1, 0, or 1
+    #
+    def <=>(other)
+      [major, minor, patch] <=> [other.major, other.minor, other.patch]
+    end
+
+    # Return the version as a dotted string
+    #
+    # @return [String] the version in "major.minor.patch" format
+    #
+    def to_s
+      "#{major}.#{minor}.#{patch}"
+    end
+
+    # Return a readable representation
+    #
+    # @return [String] inspect string
+    #
+    def inspect
+      "#<Git::Version #{self}>"
+    end
+
+    # 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.
+    #
+    # @example Get version as integer components
+    #   Git.git_version.to_a  #=> [2, 42, 0]
+    #
+    # @return [Array<Integer>] [major, minor, patch]
+    def to_a
+      deconstruct
+    end
+  end
 end

data/lib/git/version_constraint.rb

@@ -0,0 +1,85 @@
+# 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
+    # Initialize a new VersionConstraint
+    #
+    # @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,38 +1,180 @@
-require 'git/path'
+# frozen_string_literal: true
 
 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}.
+  #
+  # @example Add and remove a linked worktree
+  #   worktree = repo.worktree('/path/to/new-worktree')
+  #   worktree.add
+  #   worktree.remove
+  #
+  # @deprecated Use {Git::Repository::WorktreeOperations#worktree_list} and the
+  #   path-based worktree operations on {Git::Repository} instead
+  #
+  #   {Git::Repository::WorktreeOperations#worktree_list} returns immutable
+  #   {Git::WorktreeInfo} value objects. Operations that lived on this class are
+  #   called on the repository with the worktree path instead (for example
+  #   {Git::Repository::WorktreeOperations#worktree_add} and
+  #   {Git::Repository::WorktreeOperations#worktree_remove}). {#gcommit},
+  #   {#add}, and {#remove} each emit a deprecation warning; the `dir`, `full`,
+  #   `to_s`, and `to_a` readers do not.
+  #
+  # @api public
+  #
+  class Worktree
+    # 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
 
-  class Worktree < Path
-
-    attr_accessor :full, :dir, :gcommit
+    # 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::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 if !gcommit.nil?
+      @full += " #{gcommit}" unless gcommit.nil?
       @base = base
       @dir = dir
       @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
+    #
+    # @deprecated Use {Git::WorktreeInfo#head} from
+    #   {Git::Repository::WorktreeOperations#worktree_list} instead
+    #
+    #   `head` is always the commit SHA as a `String` (or `nil` for a bare main
+    #   worktree). Call `repo.gcommit(info.head)` for the commit object.
+    #
+    # @see Git::WorktreeInfo#head
+    #
     def gcommit
-      @gcommit ||= @base.gcommit(@full)
+      Git::Deprecation.warn(
+        'Git::Worktree#gcommit is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::WorktreeInfo#head from Git::Repository#worktree_list instead.'
+      )
+      @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
+    #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_add} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_add
+    #
     def add
-      @base.lib.worktree_add(@dir, @gcommit)
+      Git::Deprecation.warn(
+        'Git::Worktree#add is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_add instead.'
+      )
+      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
+    #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_remove} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_remove
+    #
     def remove
-      @base.lib.worktree_remove(@dir)
+      Git::Deprecation.warn(
+        'Git::Worktree#remove is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_remove instead.'
+      )
+      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
+
+    # @return [Git::Repository] the repository used for worktree operations
+    #
+    # @api private
+    #
+    def worktree_repository
+      @base
+    end
   end
 end

data/lib/git/worktree_info.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object for one entry of `git worktree list`
+  #
+  # Each entry carries what `git worktree list --porcelain` reports for a
+  # worktree: its path, the checked-out HEAD and branch, and whether it is bare,
+  # detached, locked, or prunable, with the reason git gives for the last two.
+  #
+  # @example A locked linked worktree with a branch checked out
+  #   info = Git::WorktreeInfo.new(
+  #     path: '/tmp/wt/linked',
+  #     head: 'f3e2c1ffb860086504eeb27b77a1d0028b68fd8f',
+  #     branch: 'refs/heads/linked',
+  #     bare: false,
+  #     detached: false,
+  #     locked: true,
+  #     lock_reason: 'on purpose',
+  #     prunable: false,
+  #     prune_reason: nil
+  #   )
+  #
+  #   info.path         # => '/tmp/wt/linked'
+  #   info.head         # => 'f3e2c1ffb860086504eeb27b77a1d0028b68fd8f'
+  #   info.branch       # => 'refs/heads/linked'
+  #   info.locked?      # => true
+  #   info.lock_reason  # => 'on purpose'
+  #   info.detached?    # => false
+  #   info.to_s         # => '/tmp/wt/linked'
+  #
+  # @example Pass an entry back to a worktree operation
+  #   info = repo.worktree_list.find { |w| w.branch == 'refs/heads/linked' }
+  #   repo.worktree_remove(info)
+  #
+  # @see Git::Repository::WorktreeOperations#worktree_list for the repository
+  #   method that returns these
+  #
+  # @api public
+  #
+  # @!attribute [r] path
+  #   @return [String] the worktree directory as git reports it
+  #
+  # @!attribute [r] head
+  #   @return [String, nil] the full object ID of the checked-out HEAD commit
+  #     (the all-zero object ID when the branch has no commits yet), or nil for a
+  #     bare main worktree
+  #
+  # @!attribute [r] branch
+  #   @return [String, nil] the full refname of the checked-out branch (e.g.,
+  #     'refs/heads/main'), or nil when the worktree is bare or detached
+  #
+  # @!attribute [r] bare
+  #   @return [Boolean] true if this is the main worktree of a bare repository
+  #
+  # @!attribute [r] detached
+  #   @return [Boolean] true if HEAD is detached in this worktree
+  #
+  # @!attribute [r] locked
+  #   @return [Boolean] true if the worktree is locked
+  #
+  # @!attribute [r] lock_reason
+  #   @return [String, nil] the reason given when the worktree was locked, or nil
+  #     when it is not locked or was locked without a reason
+  #
+  # @!attribute [r] prunable
+  #   @return [Boolean] true if `git worktree prune` would remove this entry
+  #
+  # @!attribute [r] prune_reason
+  #   @return [String, nil] git's explanation of why the entry is prunable, or
+  #     nil when it is not prunable
+  #
+  WorktreeInfo = Data.define(
+    :path,
+    :head,
+    :branch,
+    :bare,
+    :detached,
+    :locked,
+    :lock_reason,
+    :prunable,
+    :prune_reason
+  ) do
+    # Whether this is the main worktree of a bare repository
+    #
+    # @example
+    #   info.bare? # => false
+    #
+    # @return [Boolean] true if the worktree is bare
+    def bare? = bare
+
+    # Whether HEAD is detached in this worktree
+    #
+    # @example
+    #   info.detached? # => false
+    #
+    # @return [Boolean] true if HEAD is detached
+    def detached? = detached
+
+    # Whether the worktree is locked
+    #
+    # @example
+    #   info.locked? # => true
+    #
+    # @return [Boolean] true if the worktree is locked
+    def locked? = locked
+
+    # Whether `git worktree prune` would remove this entry
+    #
+    # @example
+    #   info.prunable? # => false
+    #
+    # @return [Boolean] true if the entry is prunable
+    def prunable? = prunable
+
+    # Returns the worktree path
+    #
+    # Lets an entry be passed directly to the worktree operations that take a
+    # path, such as {Git::Repository::WorktreeOperations#worktree_remove}.
+    #
+    # @example Convert to string
+    #   info.to_s # => '/tmp/wt/linked'
+    #
+    # @return [String] the worktree path
+    def to_s
+      path
+    end
+  end
+end