git 1.19.1 → 5.5.0

data/lib/git/path_resolver.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'git/commands/rev_parse'
+require 'git/errors'
+require 'git/execution_context'
+require 'git/execution_context/global'
+
+module Git
+  # Resolves and normalizes the filesystem paths that locate a Git repository
+  #
+  # `PathResolver` is the single home for the path-resolution logic used by the
+  # `Git::Repository` factory class methods ({Git::Repository.open} and
+  # {Git::Repository.bare}). It computes the absolute working-directory,
+  # repository (`.git`), and index paths from the caller-supplied values,
+  # following the same rules Git itself uses (including gitdir-pointer files for
+  # submodules and linked worktrees).
+  #
+  # @api private
+  #
+  module PathResolver
+    module_function
+
+    # Resolve and normalize the paths that locate a Git repository
+    #
+    # Returns a new hash containing the resolved absolute paths for:
+    #   * `:working_directory` — the working tree root (`nil` for bare repos)
+    #   * `:repository` — the `.git` directory
+    #   * `:index` — the index file
+    #
+    # This method does not mutate any inputs.
+    #
+    # @example Resolve paths for a working tree
+    #   Git::PathResolver.resolve_paths(working_directory: '/repo')
+    #   #=> { working_directory: '/repo', repository: '/repo/.git', index: '/repo/.git/index' }
+    #
+    # @param working_directory [String, nil] the working directory path
+    #
+    # @param repository [String, nil] the repository (`.git`) directory path
+    #
+    # @param index [String, nil] the index file path
+    #
+    # @param bare [Boolean] whether this is a bare repository
+    #
+    # @return [Hash{Symbol => (String, nil)}] a hash with `:working_directory`,
+    #   `:repository`, and `:index` keys
+    #
+    def resolve_paths(working_directory: nil, repository: nil, index: nil, bare: false)
+      working_dir = resolve_working_directory(working_directory, bare: bare)
+      # For bare repos, use working_directory as the default repository location
+      repo_path = resolve_repository(repository, working_dir, bare: bare, bare_default: working_directory)
+      index_path = resolve_index(index, repo_path)
+
+      {
+        working_directory: working_dir,
+        repository: repo_path,
+        index: index_path
+      }
+    end
+
+    # Find the root of the working tree that contains `working_dir`
+    #
+    # Runs `git rev-parse --show-toplevel` from `working_dir` to locate the
+    # top-level directory of the working tree.
+    #
+    # @example Find the worktree root from a subdirectory
+    #   Git::PathResolver.root_of_worktree('/repo/subdir') #=> '/repo'
+    #
+    # @param working_dir [String] a path inside the working tree
+    #
+    # @param binary_path [String, :use_global_config] path to the git binary
+    #
+    #   Controls which git binary is invoked during root detection. Defaults to
+    #   `:use_global_config`, which resolves to `Git.config.binary_path`.
+    #
+    # @param git_ssh [String, nil, :use_global_config] the SSH wrapper path
+    #
+    #   Forwarded as `GIT_SSH`. Defaults to `:use_global_config`.
+    #
+    # @return [String] the absolute path to the root of the working tree
+    #
+    # @raise [ArgumentError] if `working_dir` does not exist, is not a
+    #   directory, or is not inside a git working tree
+    #
+    #   Also raised if the git binary cannot be found.
+    #
+    def root_of_worktree(working_dir, binary_path: :use_global_config, git_ssh: :use_global_config)
+      raise ArgumentError, "'#{working_dir}' does not exist or is not a directory" unless Dir.exist?(working_dir)
+
+      execute_rev_parse_toplevel(working_dir, binary_path: binary_path, git_ssh: git_ssh)
+    end
+
+    # Run `git rev-parse --show-toplevel` from `working_dir` and return stdout
+    #
+    # @param working_dir [String] a path inside the working tree
+    #
+    # @param binary_path [String, :use_global_config] path to the git binary
+    #
+    # @param git_ssh [String, nil, :use_global_config] the SSH wrapper path
+    #
+    # @return [String] the top-level directory reported by git
+    #
+    # @raise [ArgumentError] if the git binary is not found or `working_dir` is
+    #   not inside a git working tree
+    #
+    # @api private
+    #
+    def execute_rev_parse_toplevel(working_dir, binary_path: :use_global_config, git_ssh: :use_global_config)
+      execution_context = Git::ExecutionContext::Global.new(binary_path: binary_path, git_ssh: git_ssh)
+      Git::Commands::RevParse.new(execution_context).call(
+        show_toplevel: true, chdir: File.expand_path(working_dir)
+      ).stdout
+    rescue Errno::ENOENT
+      raise ArgumentError, 'Failed to find the root of the worktree: git binary not found'
+    rescue Git::FailedError
+      raise ArgumentError, "'#{working_dir}' is not in a git working tree"
+    end
+    private_class_method :execute_rev_parse_toplevel
+
+    # Resolve the working directory path
+    #
+    # @param path [String, nil] the working directory path or `nil`
+    #
+    # @param bare [Boolean] whether this is a bare repository
+    #
+    # @return [String, nil] the absolute path, or `nil` for bare repos
+    #
+    # @api private
+    #
+    def resolve_working_directory(path, bare:)
+      return nil if bare
+
+      File.expand_path(path || Dir.pwd)
+    end
+    private_class_method :resolve_working_directory
+
+    # Resolve the repository (`.git`) directory path
+    #
+    # Handles the gitdir-pointer file case for submodules and linked worktrees.
+    #
+    # @param path [String, nil] the repository path or `nil`
+    #
+    # @param working_dir [String, nil] the working directory used for relative
+    #   path resolution
+    #
+    # @param bare [Boolean] whether this is a bare repository
+    #
+    # @param bare_default [String, nil] for bare repos, used as the default when
+    #   `path` is `nil`
+    #
+    # @return [String] the absolute path to the repository
+    #
+    # @api private
+    #
+    def resolve_repository(path, working_dir, bare:, bare_default: nil)
+      initial_path = if bare
+                       File.expand_path(path || bare_default || Dir.pwd)
+                     else
+                       File.expand_path(path || '.git', working_dir)
+                     end
+
+      resolve_gitdir_pointer(initial_path)
+    end
+    private_class_method :resolve_repository
+
+    # Resolve gitdir-pointer files used by submodules and linked worktrees
+    #
+    # If `path` points to a file containing `"gitdir: <path>"`, returns the
+    # resolved target path. Otherwise returns `path` unchanged.
+    #
+    # @param path [String] the path to check
+    #
+    # @return [String] the resolved absolute path
+    #
+    # Relative pointer targets are resolved from the directory containing the
+    # pointer file itself, matching git's pointer-file semantics.
+    #
+    # @api private
+    #
+    def resolve_gitdir_pointer(path)
+      return path unless File.file?(path)
+
+      gitdir_content = File.read(path).strip
+      return path unless gitdir_content.start_with?('gitdir: ')
+
+      gitdir_path = gitdir_content.sub(/\Agitdir: /, '')
+      File.expand_path(gitdir_path, File.dirname(path))
+    end
+    private_class_method :resolve_gitdir_pointer
+
+    # Resolve the index file path
+    #
+    # @param path [String, nil] the index path or `nil`
+    #
+    # @param repository [String] the repository directory used for relative
+    #   path resolution
+    #
+    # @return [String] the absolute path to the index file
+    #
+    # @api private
+    #
+    def resolve_index(path, repository)
+      File.expand_path(path || 'index', repository)
+    end
+    private_class_method :resolve_index
+  end
+end

data/lib/git/remote.rb

@@ -1,38 +1,191 @@
+# frozen_string_literal: true
+
+require 'git/branch'
+require 'git/branch_info'
+
 module Git
-  class Remote < Path
+  # A remote in a Git repository
+  #
+  # Remote objects provide access to remote metadata and operations like fetch,
+  # merge, and remove. This class and `Git::Repository#remote`, which returns
+  # it, are both deprecated: read remote configuration through
+  # {Git::Repository::RemoteOperations#remote_list} and call the
+  # repository-level operations with the remote name instead.
+  #
+  # @example Reading a remote and fetching from it without Git::Remote
+  #   git = Git.open('.')
+  #   origin = git.remote_list.find { |r| r.name == 'origin' }  #=> Git::RemoteInfo
+  #   origin.url.first
+  #   git.fetch(origin.name)
+  #
+  # @deprecated Use {Git::Repository::RemoteOperations#remote_list} and the
+  #   repository-level remote operations instead
+  #
+  #   {Git::Repository::RemoteOperations#remote_list} returns immutable
+  #   {Git::RemoteInfo} value objects. Operations that lived on this class are
+  #   called on the repository with the remote name instead (for example
+  #   {Git::Repository::RemoteOperations#fetch} and
+  #   {Git::Repository::RemoteOperations#remote_remove}). Constructing a
+  #   `Git::Remote` emits a deprecation warning.
+  #
+  # @api public
+  #
+  class Remote
+    # The name of this remote (e.g. `'origin'`)
+    #
+    # @return [String] the remote name
+    #
+    attr_accessor :name
+
+    # The URL of this remote
+    #
+    # @return [String, nil] the remote URL
+    #
+    attr_accessor :url
 
-    attr_accessor :name, :url, :fetch_opts
+    # The fetch refspec for this remote
+    #
+    # @return [String, nil] the fetch options string
+    #
+    attr_accessor :fetch_opts
 
+    # Initialize a new Remote object
+    #
+    # @param base [Git::Repository] the git repository
+    #
+    # @param name [String] the remote name (e.g. `'origin'`)
+    #
+    # @note Do not construct directly. `Git::Repository#remote` is deprecated as
+    #   well; use {Git::Repository::RemoteOperations#remote_list} and the
+    #   repository-level remote operations instead.
+    #
+    # @api private
+    #
     def initialize(base, name)
+      Git::Deprecation.warn(
+        'Git::Remote is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#remote_list and the repository-level remote operations instead.'
+      )
       @base = base
-      config = @base.lib.config_remote(name)
+      # config_remote is deprecated too; silence it so one Git::Remote.new emits one warning
+      config = Git::Deprecation.silence { remote_repository.config_remote(name) }
       @name = name
       @url = config['url']
       @fetch_opts = config['fetch']
     end
 
-    def fetch(opts={})
-      @base.fetch(@name, opts)
+    # Fetches from this remote
+    #
+    # @example Fetch from origin
+    #   git.remote('origin').fetch
+    #
+    # @param opts [Hash] options for the fetch command
+    #
+    # @option opts [Boolean, nil] :tags (nil) fetch all tags from the remote
+    #   (`--tags`)
+    #
+    # @option opts [Boolean, nil] :prune (nil) remove remote-tracking references
+    #   that no longer exist on the remote (`--prune`)
+    #
+    # @option opts [Boolean, nil] :prune_tags (nil) remove local tags that no
+    #   longer exist on the remote (`--prune-tags`)
+    #
+    # @option opts [Boolean, nil] :force (nil) override the fast-forward check
+    #   when using explicit refspecs (`--force`)
+    #
+    # @option opts [Boolean, nil] :update_head_ok (nil) allow `git fetch` to
+    #   update the branch pointed to by `HEAD` (`--update-head-ok`)
+    #
+    # @option opts [Boolean, nil] :unshallow (nil) convert a shallow clone into a
+    #   full repository (`--unshallow`)
+    #
+    # @option opts [String, Integer, nil] :depth (nil) limit history to N commits
+    #   from each branch tip (`--depth=N`)
+    #
+    # @option opts [String, Array<String>, nil] :ref (nil) one or more refspecs to
+    #   fetch as positional arguments after the remote name
+    #
+    # @return [String] git's stdout from the fetch
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def fetch(opts = {})
+      remote_repository.fetch(@name, opts)
     end
 
-    # merge this remote locally
-    def merge(branch = @base.current_branch)
+    # Merges this remote into the given (or current) local branch
+    #
+    # @example Merge origin/main into the current branch
+    #   git.remote('origin').merge('main')
+    #
+    # @param branch [String] the local branch to merge into (defaults to current branch)
+    #
+    # @return [String] git's stdout from the merge
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def merge(branch = nil)
+      branch ||= remote_repository.current_branch
       remote_tracking_branch = "#{@name}/#{branch}"
-      @base.merge(remote_tracking_branch)
+      remote_repository.merge(remote_tracking_branch)
     end
 
-    def branch(branch = @base.current_branch)
-      remote_tracking_branch = "#{@name}/#{branch}"
-      Git::Branch.new(@base, remote_tracking_branch)
+    # Returns a {Git::Branch} object for the given branch on this remote
+    #
+    # @example Get the remote-tracking branch object
+    #   git.remote('origin').branch('main')  #=> #<Git::Branch 'origin/main'>
+    #
+    # @param branch [String] the branch name on this remote (defaults to current branch)
+    #
+    # @return [Git::Branch] a branch object representing `<remote>/<branch>`
+    #
+    # @deprecated Use
+    #   `Git::Repository#branch_list("#{name}/#{branch || current_branch}").first`
+    #   instead
+    #
+    #   With no argument this method falls back to the current branch, so the
+    #   replacement has to supply `Git::Repository#current_branch` itself. The
+    #   replacement returns a {Git::BranchInfo} value object rather than a
+    #   {Git::Branch}, and returns `nil` when the remote-tracking branch does
+    #   not exist.
+    #
+    def branch(branch = nil)
+      branch ||= remote_repository.current_branch
+      Git::Branch.new(@base, "#{@name}/#{branch}")
     end
 
+    # Removes this remote from the repository
+    #
+    # @example Remove the upstream remote
+    #   git.remote('upstream').remove
+    #
+    # @return [Git::CommandLine::Result] the result of `git remote remove`
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def remove
-      @base.lib.remote_remove(@name)
+      remote_repository.remote_remove(@name)
     end
 
+    # Returns the name of this remote as a string
+    #
+    # @example Get the remote name as a string
+    #   git.remote('origin').to_s  #=> 'origin'
+    #
+    # @return [String] the remote name
+    #
     def to_s
       @name
     end
 
+    private
+
+    # @return [Git::Repository]
+    #
+    # @api private
+    #
+    def remote_repository
+      @base
+    end
   end
 end

data/lib/git/remote_info.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Git
+  # Value object representing a configured git remote
+  #
+  # Each instance holds the parsed configuration for a single remote as read
+  # from the repository's git config. Multi-value fields (`:url`, `:push_url`,
+  # `:fetch`, `:push`) are always `Array<String>` (never `nil`; may be empty).
+  # Those arrays are frozen copies of the values given, so the set of URLs and
+  # refspecs cannot change after construction; use `with` to derive a modified
+  # copy. The immutability is shallow, as with any `Data` member: the strings
+  # inside those arrays and the scalar members are the objects the caller
+  # passed in, not copies. All other fields are nilable except `:name`.
+  #
+  # @example Minimal remote (fetch-only, one URL)
+  #   info = Git::RemoteInfo.new(
+  #     name: 'origin',
+  #     url: ['https://github.com/ruby-git/ruby-git.git'],
+  #     push_url: [],
+  #     fetch: ['+refs/heads/*:refs/remotes/origin/*'],
+  #     push: []
+  #   )
+  #   info.name   # => "origin"
+  #   info.url    # => ["https://github.com/ruby-git/ruby-git.git"]
+  #   info.prune  # => nil
+  #
+  # @api public
+  #
+  # @!attribute [r] name
+  #   @return [String] the name of the remote (e.g. `'origin'`)
+  #
+  # @!attribute [r] url
+  #   @return [Array<String>] the fetch URL(s) for this remote (`remote.<name>.url`)
+  #
+  # @!attribute [r] push_url
+  #   @return [Array<String>] the push URL(s) for this remote (`remote.<name>.pushurl`)
+  #
+  # @!attribute [r] fetch
+  #   @return [Array<String>] the fetch refspec(s) for this remote (`remote.<name>.fetch`)
+  #
+  # @!attribute [r] push
+  #   @return [Array<String>] the push refspec(s) for this remote (`remote.<name>.push`)
+  #
+  # @!attribute [r] mirror
+  #   @return [Boolean, nil] `true`/`false` per `remote.<name>.mirror`, or `nil` when not set
+  #
+  # @!attribute [r] skip_default_update
+  #   @return [Boolean, nil] `true`/`false` per `remote.<name>.skipDefaultUpdate`, or `nil` when not set
+  #
+  # @!attribute [r] tag_opt
+  #   @return [String, nil] the tag-fetching option (`remote.<name>.tagOpt`), or `nil` when not set
+  #
+  # @!attribute [r] prune
+  #   @return [Boolean, nil] `true`/`false` per `remote.<name>.prune`; `nil` inherits `fetch.prune`
+  #
+  # @!attribute [r] prune_tags
+  #   @return [Boolean, nil] `true`/`false` per `remote.<name>.pruneTags`; `nil` inherits `fetch.pruneTags`
+  #
+  # @!attribute [r] receivepack
+  #   @return [String, nil] the `git-receive-pack` path on the remote (`remote.<name>.receivepack`)
+  #
+  # @!attribute [r] uploadpack
+  #   @return [String, nil] the `git-upload-pack` path on the remote (`remote.<name>.uploadpack`)
+  #
+  # @!attribute [r] promisor
+  #   @return [Boolean, nil] `true`/`false` per `remote.<name>.promisor`, or `nil` when not set
+  #
+  # @!attribute [r] partial_clone_filter
+  #   @return [String, nil] the partial-clone object filter (`remote.<name>.partialclonefilter`)
+  #
+  # @!attribute [r] vcs
+  #   @return [String, nil] the VCS type for git-remote helpers (`remote.<name>.vcs`)
+  #
+  RemoteInfo = Data.define(
+    :name,
+    :url,
+    :push_url,
+    :fetch,
+    :push,
+    :mirror,
+    :skip_default_update,
+    :tag_opt,
+    :prune,
+    :prune_tags,
+    :receivepack,
+    :uploadpack,
+    :promisor,
+    :partial_clone_filter,
+    :vcs
+  ) do
+    # Create a new RemoteInfo
+    #
+    # @param name [String] the name of the remote (required)
+    #
+    # @param url [Array<String>] fetch URLs (default `[]`); stored as a frozen copy
+    #
+    # @param push_url [Array<String>] push URLs (default `[]`); stored as a frozen copy
+    #
+    # @param fetch [Array<String>] fetch refspecs (default `[]`); stored as a frozen copy
+    #
+    # @param push [Array<String>] push refspecs (default `[]`); stored as a frozen copy
+    #
+    # @param mirror [Boolean, nil] mirror flag (default `nil`)
+    #
+    # @param skip_default_update [Boolean, nil] skip-default-update flag (default `nil`)
+    #
+    # @param tag_opt [String, nil] tag-fetching option (default `nil`)
+    #
+    # @param prune [Boolean, nil] prune flag (default `nil`)
+    #
+    # @param prune_tags [Boolean, nil] prune-tags flag (default `nil`)
+    #
+    # @param receivepack [String, nil] receive-pack path (default `nil`)
+    #
+    # @param uploadpack [String, nil] upload-pack path (default `nil`)
+    #
+    # @param promisor [Boolean, nil] promisor flag (default `nil`)
+    #
+    # @param partial_clone_filter [String, nil] partial-clone filter (default `nil`)
+    #
+    # @param vcs [String, nil] VCS type (default `nil`)
+    #
+    # @return [Git::RemoteInfo]
+    #
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      name:,
+      url: [],
+      push_url: [],
+      fetch: [],
+      push: [],
+      mirror: nil,
+      skip_default_update: nil,
+      tag_opt: nil,
+      prune: nil,
+      prune_tags: nil,
+      receivepack: nil,
+      uploadpack: nil,
+      promisor: nil,
+      partial_clone_filter: nil,
+      vcs: nil
+    )
+      super(
+        name:, url: Array(url).dup.freeze, push_url: Array(push_url).dup.freeze,
+        fetch: Array(fetch).dup.freeze, push: Array(push).dup.freeze, mirror:,
+        skip_default_update:, tag_opt:, prune:, prune_tags:, receivepack:, uploadpack:,
+        promisor:, partial_clone_filter:, vcs:
+      )
+    end
+
+    # Return a copy of this RemoteInfo with the given fields replaced
+    #
+    # Routes through {#initialize} so the multi-value fields of the copy are
+    # frozen copies, the same as on construction. `Data#with` bypasses
+    # `initialize` on Ruby 3.2, which would leave those arrays mutable.
+    #
+    # @example Replace the fetch URL
+    #   info.with(url: ['https://example.com/other.git']).url
+    #   # => ["https://example.com/other.git"]
+    #
+    # @param fields [Hash{Symbol => Object}] the fields to replace, keyed by
+    #   member name
+    #
+    # @option fields [String] :name the name of the remote
+    #
+    # @option fields [Array<String>] :url fetch URLs
+    #
+    # @option fields [Array<String>] :push_url push URLs
+    #
+    # @option fields [Array<String>] :fetch fetch refspecs
+    #
+    # @option fields [Array<String>] :push push refspecs
+    #
+    # @option fields [Boolean, nil] :mirror mirror flag
+    #
+    # @option fields [Boolean, nil] :skip_default_update skip-default-update flag
+    #
+    # @option fields [String, nil] :tag_opt tag-fetching option
+    #
+    # @option fields [Boolean, nil] :prune prune flag
+    #
+    # @option fields [Boolean, nil] :prune_tags prune-tags flag
+    #
+    # @option fields [String, nil] :receivepack receive-pack path
+    #
+    # @option fields [String, nil] :uploadpack upload-pack path
+    #
+    # @option fields [Boolean, nil] :promisor promisor flag
+    #
+    # @option fields [String, nil] :partial_clone_filter partial-clone filter
+    #
+    # @option fields [String, nil] :vcs VCS type
+    #
+    # @return [Git::RemoteInfo] a new instance; `self` when no fields are given
+    #
+    # @raise [ArgumentError] if a key is not a member of this Data class
+    #
+    def with(**fields)
+      return self if fields.empty?
+
+      self.class.new(**to_h, **fields)
+    end
+  end
+end