git 4.3.2 → 5.0.0.beta.2

data/lib/git/branch_info.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Git
+  # Regular expression for parsing branch refnames
+  #
+  # Captures:
+  #   - remote_name: the remote name (e.g., 'origin') for remote branches, nil for local
+  #   - branch_name: the branch name without the remote prefix
+  #
+  # @note This regex is similar to Git::Branch::BRANCH_NAME_REGEXP but uses \A/\z anchors
+  #   instead of ^/$ for stricter matching. As part of the architectural redesign,
+  #   Git::Branch will eventually be refactored to use BranchInfo internally, at which
+  #   point this will become the single source of truth for branch name parsing.
+  #
+  # @note This regex assumes remote names do not contain '/'. If a remote name
+  #   contains '/', parsing will be incorrect. For example, 'remotes/team/upstream/main'
+  #   would parse as remote_name='team' instead of 'team/upstream'. This is an inherent
+  #   ambiguity in git refnames that can only be resolved with knowledge of configured
+  #   remotes. See: https://github.com/ruby-git/ruby-git/issues/919
+  #
+  # @example
+  #   'main' => { remote_name: nil, branch_name: 'main' }
+  #   'remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
+  #   'feature/foo' => { remote_name: nil, branch_name: 'feature/foo' }
+  #   'remotes/origin/feature/bar' => { remote_name: 'origin', branch_name: 'feature/bar' }
+  #
+  # @api private
+  BRANCH_REFNAME_REGEXP = %r{
+    \A                              # start of string
+    (?:(?:refs/)?remotes/(?<remote_name>[^/]+)/)? # optional 'refs?/remotes/<remote_name>/'
+    (?<branch_name>.+)                   # branch name (everything else)
+    \z                              # end of string
+  }x
+
+  # Value object representing branch metadata from git branch output
+  #
+  # This is a lightweight, immutable data structure returned by branch listing
+  # commands. It contains only the data parsed from git output without any
+  # repository context or operations.
+  #
+  # @example Creating from git branch output
+  #   info = Git::BranchInfo.new(
+  #     refname: 'main',
+  #     target_oid: 'abc123def456789012345678901234567890abcd',
+  #     current: true,
+  #     worktree: false,
+  #     symref: nil,
+  #     upstream: nil
+  #   )
+  #   info.current?     #=> true
+  #   info.remote?      #=> false
+  #   info.short_name   #=> 'main'
+  #
+  # @example Remote branch
+  #   info = Git::BranchInfo.new(
+  #     refname: 'remotes/origin/main',
+  #     target_oid: 'abc123def456789012345678901234567890abcd',
+  #     current: false,
+  #     worktree: false,
+  #     symref: nil,
+  #     upstream: nil
+  #   )
+  #   info.remote?      #=> true
+  #   info.remote_name  #=> 'origin'
+  #   info.short_name   #=> 'main'
+  #
+  # @example Local branch with upstream tracking
+  #   upstream_info = Git::BranchInfo.new(
+  #     refname: 'remotes/origin/main',
+  #     target_oid: 'abc123def456789012345678901234567890abcd',
+  #     current: false,
+  #     worktree: false,
+  #     symref: nil,
+  #     upstream: nil
+  #   )
+  #   info = Git::BranchInfo.new(
+  #     refname: 'main',
+  #     target_oid: 'abc123def456789012345678901234567890abcd',
+  #     current: true,
+  #     worktree: false,
+  #     symref: nil,
+  #     upstream: upstream_info
+  #   )
+  #   info.upstream.remote_name  #=> 'origin'
+  #
+  # @see Git::Branch for the full-featured branch object with operations
+  #
+  # @see Git::Commands::Branch::List for the command that produces these
+  #
+  # @api public
+  #
+  # @!attribute [r] refname
+  #
+  #   The full reference name of the branch
+  #
+  #   @return [String] the branch refname (e.g., 'main', 'remotes/origin/main')
+  #
+  # @!attribute [r] target_oid
+  #
+  #   The commit object ID (SHA) that this branch points to
+  #
+  #   @return [String, nil] the full 40-character object ID, or nil if unavailable
+  #
+  # @!attribute [r] current
+  #
+  #   Whether this branch is currently checked out in the current worktree
+  #
+  #   @return [Boolean] true if this is the current branch
+  #
+  # @!attribute [r] worktree
+  #
+  #   Whether this branch is checked out in another linked worktree
+  #
+  #   @return [Boolean] true if checked out in a different worktree
+  #
+  # @!attribute [r] symref
+  #
+  #   The target reference if this is a symbolic reference
+  #
+  #   @return [String, nil] the target ref (e.g., 'refs/heads/main'), or nil if not a symref
+  #
+  # @!attribute [r] upstream
+  #
+  #   The configured upstream/tracking branch
+  #
+  #   @return [Git::BranchInfo, nil] the upstream branch info, or nil if no upstream is configured
+  #
+  #   @note Remote-tracking branches (e.g., 'origin/main') have upstream: nil
+  #
+  #   @note When upstream exists but the remote-tracking branch hasn't been fetched,
+  #     the upstream's target_oid may be nil
+  #
+  BranchInfo = Data.define(:refname, :target_oid, :current, :worktree, :symref, :upstream) do
+    # @return [Boolean] always false for BranchInfo (see DetachedHeadInfo for detached state)
+    def detached? = false
+
+    # @return [Boolean] true if this is an unborn branch (no commits yet)
+    def unborn? = target_oid.nil?
+
+    # @return [Boolean] true if this is the currently checked out branch
+    def current? = current
+
+    # @return [Boolean] true if this branch is checked out in another worktree
+    def worktree? = worktree
+
+    # @return [Boolean] true if this is a symbolic reference
+    def symref? = !symref.nil?
+
+    # @return [Boolean] true if this is a remote-tracking branch
+    def remote? = !remote_name.nil?
+
+    # @return [String, nil] the name of the remote (e.g., 'origin'), or nil for local branches
+    def remote_name
+      parse_refname[:remote_name]
+    end
+
+    # @return [String] the branch name without remote prefix (e.g., 'main' or 'feature/foo')
+    def short_name
+      parse_refname[:branch_name]
+    end
+
+    # @return [String] string representation (the full refname)
+    def to_s = refname
+
+    private
+
+    # Parse the refname and return match data
+    #
+    # The regex is guaranteed to match any non-empty string due to the `.+` pattern,
+    # so we don't need nil checking. If refname is empty/nil, this would fail at
+    # object creation time since refname is a required attribute.
+    #
+    # @return [MatchData] the match result
+    def parse_refname
+      refname.match(Git::BRANCH_REFNAME_REGEXP)
+    end
+  end
+end

data/lib/git/branches.rb

@@ -1,68 +1,166 @@
 # frozen_string_literal: true
 
 module Git
-  # object that holds all the available branches
+  # Collection of all Git branches in a repository
+  #
+  # Wraps both local and remote-tracking branches and provides filtering,
+  # enumeration, and name-based lookup.
+  #
+  # @example Enumerate all branches
+  #   branches = repo.branches
+  #   branches.each { |b| puts b.name }
+  #
+  # @api public
+  #
   class Branches
     include Enumerable
 
+    # Creates a new Branches collection populated from the given repository
+    #
+    # @param base [Git::Repository] the repository to enumerate
+    #   branches from
+    #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def initialize(base)
       @branches = {}
+      @lookup = {}
 
       @base = base
 
-      @base.lib.branches_all.each do |b|
-        @branches[b[0]] = Git::Branch.new(@base, b[0])
+      branch_repository.branches_all.each do |branch_info|
+        branch = Git::Branch.new(base, branch_info)
+
+        @branches[branch_info.refname] = branch
+        index_branch_lookup(branch, refname: branch_info.refname)
       end
     end
 
+    # Returns all local (non-remote-tracking) branches
+    #
+    # @example List local branch names
+    #   repo.branches.local.map(&:name)
+    #
+    # @return [Array<Git::Branch>] the local branches
+    #
     def local
       reject(&:remote)
     end
 
+    # Returns all remote-tracking branches
+    #
+    # @example List remote branch names
+    #   repo.branches.remote.map(&:name)
+    #
+    # @return [Array<Git::Branch>] the remote-tracking branches
+    #
     def remote
       self.select(&:remote)
     end
 
-    # array like methods
-
+    # Returns the number of branches in the collection
+    #
+    # @example Count all branches
+    #   repo.branches.size  # => 3
+    #
+    # @return [Integer] the total number of branches
+    #
     def size
       @branches.size
     end
 
+    # Iterates over every branch in the collection
+    #
+    # @overload each
+    #
+    #   @example Get an enumerator over all branches
+    #     enum = repo.branches.each
+    #
+    #   @return [Enumerator<Git::Branch>] an enumerator over all branches
+    #
+    # @overload each(&block)
+    #
+    #   @example Print every branch name
+    #     repo.branches.each { |b| puts b.name }
+    #
+    #   @return [Array<Git::Branch>] the full list of branches
+    #
+    #   @yield [branch] passes each branch to the block
+    #
+    #   @yieldparam branch [Git::Branch] a branch in the repository
+    #
+    #   @yieldreturn [void]
+    #
     def each(&)
       @branches.values.each(&)
     end
 
-    # Returns the target branch
+    # Returns the branch with the given name
+    #
+    # Supports short names (`'main'`), remote-qualified names
+    # (`'working/master'`), and full refspec names
+    # (`'remotes/working/master'`).
     #
-    # Example:
-    #   Given (git branch -a):
-    #    master
-    #    remotes/working/master
+    # @example Look up a branch by short name
+    #   repo.branches['main']
     #
-    #   g.branches['master'].full #=> 'master'
-    #   g.branches['working/master'].full => 'remotes/working/master'
-    #   g.branches['remotes/working/master'].full => 'remotes/working/master'
+    # @example Look up a remote-tracking branch
+    #   repo.branches['working/master']
+    #
+    # @param branch_name [#to_s] the name of the branch to retrieve
+    #
+    # @return [Git::Branch, nil] the matching branch, or `nil` if not found
     #
-    # @param [#to_s] branch_name the target branch name.
-    # @return [Git::Branch] the target branch.
     def [](branch_name)
-      @branches.values.each_with_object(@branches) do |branch, branches|
-        branches[branch.full] ||= branch
-
-        # This is how Git (version 1.7.9.5) works.
-        # Lets you ignore the 'remotes' if its at the beginning of the branch full
-        # name (even if is not a real remote branch).
-        branches[branch.full.sub('remotes/', '')] ||= branch if branch.full =~ %r{^remotes/.+}
-      end[branch_name.to_s]
+      @lookup[branch_name.to_s]
     end
 
+    # Returns a string listing all branches, prefixed with `*` for the current branch
+    #
+    # @example Display all branches
+    #   puts repo.branches.to_s
+    #
+    # @return [String] a formatted branch listing
+    #
     def to_s
-      out = ''
+      out = +''
       @branches.each_value do |b|
         out << (b.current ? '* ' : '  ') << b.to_s << "\n"
       end
       out
     end
+
+    private
+
+    # @return [Git::Repository] the repository used to enumerate branches
+    #
+    # @api private
+    #
+    def branch_repository
+      @base
+    end
+
+    # Indexes all supported lookup keys for a branch without mutating
+    # the canonical `@branches` collection used by enumeration
+    #
+    # @param branch [Git::Branch] the branch to index
+    #
+    # @param refname [String] the full refname key to use for primary lookup
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def index_branch_lookup(branch, refname:)
+      @lookup[refname] ||= branch
+      @lookup[branch.full] ||= branch
+
+      return unless branch.full.start_with?('remotes/')
+
+      # Mirror git compatibility: allow omitting a leading "remotes/".
+      @lookup[branch.full.delete_prefix('remotes/')] ||= branch
+    end
   end
 end

data/lib/git/command_line/base.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require 'git/command_line'
+require 'git/errors'
+
+module Git
+  module CommandLine
+    # Abstract base class for git command-line execution strategies
+    #
+    # Concrete subclasses must implement {#run} to execute a git command and
+    # return a {Git::CommandLine::Result}. Two implementations are provided:
+    #
+    # * {Git::CommandLine::Capturing} — buffers stdout and stderr in memory
+    # * {Git::CommandLine::Streaming} — streams stdout to a caller-supplied IO
+    #
+    # @example Instantiate a concrete subclass
+    #   env = { 'GIT_DIR' => '/path/to/git/dir' }
+    #   binary_path = '/usr/bin/git'
+    #   global_opts = %w[--git-dir /path/to/git/dir]
+    #   logger = Logger.new($stdout)
+    #   cli = Git::CommandLine::Capturing.new(env, binary_path, global_opts, logger)
+    #   cli.run('version') #=> #<Git::CommandLine::Result ...>
+    #
+    # @abstract Subclass and implement {#run}
+    #
+    # @api public
+    #
+    class Base
+      # Create a Base (or subclass) object
+      #
+      # @param env [Hash{String => String, nil}] environment variables to set or
+      #   unset. String values set the variable; `nil` values unset it.
+      #
+      # @param binary_path [String] the path to the git binary
+      #
+      # @param global_opts [Array<String>] global options to pass to git
+      #
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(env, binary_path, global_opts, logger)
+        @env = env
+        @binary_path = binary_path
+        @global_opts = global_opts
+        @logger = logger
+      end
+
+      # Execute a git command and return the result
+      #
+      # Concrete subclasses must override this method.
+      #
+      # @raise [NotImplementedError] always — must be implemented by subclasses
+      #
+      def run(*)
+        raise NotImplementedError, "#{self.class}#run is not implemented"
+      end
+
+      # @attribute [r] env
+      #
+      # Variables to set (or unset) in the git command's environment
+      #
+      # @example
+      #   env = { 'GIT_DIR' => '/path/to/git/dir' }
+      #   cli = Git::CommandLine::Capturing.new(env, '/usr/bin/git', [], Logger.new(nil))
+      #   cli.env #=> { 'GIT_DIR' => '/path/to/git/dir' }
+      #
+      # @return [Hash{String => String, nil}]
+      #
+      # @see https://ruby-doc.org/3.2.1/Process.html#method-c-spawn Process.spawn
+      #   for details on how to set environment variables using the `env` parameter
+      #
+      attr_reader :env
+
+      # @attribute [r] binary_path
+      #
+      # The path to the command line binary to run
+      #
+      # @example
+      #   cli = Git::CommandLine::Capturing.new({}, '/usr/bin/git', [], Logger.new(nil))
+      #   cli.binary_path #=> '/usr/bin/git'
+      #
+      # @return [String]
+      #
+      attr_reader :binary_path
+
+      # @attribute [r] global_opts
+      #
+      # The global options to pass to git
+      #
+      # These are options that are passed to git before the command name and
+      # arguments. For example, in `git --git-dir /path/to/git/dir version`, the
+      # global options are %w[--git-dir /path/to/git/dir].
+      #
+      # @example
+      #   global_opts = %w[--git-dir /path/to/git/dir]
+      #   cli = Git::CommandLine::Capturing.new({}, '/usr/bin/git', global_opts, Logger.new(nil))
+      #   cli.global_opts #=> %w[--git-dir /path/to/git/dir]
+      #
+      # @return [Array<String>]
+      #
+      attr_reader :global_opts
+
+      # @attribute [r] logger
+      #
+      # The logger to use for logging git commands and results
+      #
+      # @example
+      #   logger = Logger.new(nil)
+      #   cli = Git::CommandLine::Capturing.new({}, '/usr/bin/git', [], logger)
+      #   cli.logger == logger #=> true
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      private
+
+      # Merge caller-supplied options into `defaults` and raise if any unknown keys are present
+      #
+      # @param defaults [Hash] the allowed keys and their default values (e.g. RUN_OPTION_DEFAULTS)
+      #
+      # @param options_hash [Hash] caller-supplied options
+      #
+      # @return [Hash] defaults with any supplied values overridden
+      #
+      # @raise [ArgumentError] if options_hash contains keys not present in defaults
+      #
+      # @api private
+      #
+      def merge_and_validate_options(defaults, options_hash)
+        merged = defaults.merge(options_hash)
+        extra = merged.keys - defaults.keys
+        raise ArgumentError, "Unknown options: #{extra.join(', ')}" if extra.any?
+
+        merged
+      end
+
+      # Merge the instance-level env with any per-call overrides in options_hash[:env]
+      #
+      # @param options_hash [Hash] options that may include an :env override
+      #
+      # @return [Hash{String => String, nil}]
+      #
+      # @api private
+      #
+      def merged_env(options_hash)
+        env.merge(options_hash[:env] || {})
+      end
+
+      # Yield to a block that calls ProcessExecuter and translate any ProcessExecuter
+      # errors to their ruby-git equivalents
+      #
+      # @raise [ArgumentError] in place of ProcessExecuter::ArgumentError
+      #
+      # @raise [Git::Error] in place of ProcessExecuter::SpawnError (binary not found or
+      #   failed to launch)
+      #
+      # @raise [Git::ProcessIOError] in place of ProcessExecuter::ProcessIOError
+      #
+      # @raise [Git::ProcessIOError] when a timeout race causes Errno::ESRCH. On Ruby 4.0+,
+      #   `Process.kill` raises `Errno::ESRCH` when the spawned process exits between the
+      #   timeout firing and the kill signal being delivered. This is a race in
+      #   process_executer's timeout handling and is semantically equivalent to a timeout.
+      #
+      # @return [Object] the return value of the block
+      #
+      # @api private
+      #
+      def run_process_executer
+        yield
+      rescue ProcessExecuter::ArgumentError => e
+        raise ::ArgumentError, e.message
+      rescue ProcessExecuter::SpawnError => e
+        raise Git::Error, e.message, cause: e.cause
+      rescue ProcessExecuter::ProcessIOError => e
+        raise Git::ProcessIOError, e.message, cause: e.cause
+      rescue Errno::ESRCH => e
+        # Ruby 4.0+: Process.kill raises Errno::ESRCH when the spawned process exits
+        # in the narrow window between the timeout firing and the kill signal being sent.
+        # This is a known race in process_executer's timeout handling.
+        raise Git::ProcessIOError, "Git process no longer exists (timeout race): #{e.message}", cause: e
+      end
+
+      # Build the git command line from the available sources to send to `Process.spawn`
+      #
+      # @param args [Array<String>] command-line arguments to append after global options
+      #
+      # @return [Array<String>]
+      #
+      # @raise [ArgumentError] if any element of args is itself an Array
+      #
+      # @api private
+      #
+      def build_git_cmd(args)
+        raise ArgumentError, 'The args array can not contain an array' if args.any?(Array)
+
+        [binary_path, *global_opts, *args].map(&:to_s)
+      end
+
+      # Log the result of a git command at info/debug level
+      #
+      # @param result [ProcessExecuter::Result] the raw process result
+      #
+      # @param command [Array<String>] the full command that was run
+      #
+      # @param processed_out [String] the post-processed stdout string
+      #
+      # @param processed_err [String] the post-processed stderr string
+      #
+      # @return [void]
+      #
+      # @api private
+      #
+      def log_result(result, command, processed_out, processed_err)
+        logger.info { "#{command} exited with status #{result}" }
+        logger.debug { "stdout:\n#{processed_out.inspect}\nstderr:\n#{processed_err.inspect}" }
+      end
+
+      # Build a {Git::CommandLine::Result} and raise on timeout, signal, or failure
+      #
+      # @param command [Array<String>] the full command that was run
+      #
+      # @param result [ProcessExecuter::Result] the raw process result
+      #
+      # @param processed_out [String] processed stdout string
+      #
+      # @param processed_err [String] processed stderr string
+      #
+      # @param timeout [Numeric, nil] the timeout value (for error context)
+      #
+      # @param raise_on_failure [Boolean] whether to raise on non-zero exit status
+      #
+      # @return [Git::CommandLine::Result]
+      #
+      # @raise [Git::TimeoutError] if the command timed out
+      #
+      # @raise [Git::SignaledError] if the command was terminated by a signal
+      #
+      # @raise [Git::FailedError] if the command failed and raise_on_failure is true
+      #
+      # @api private
+      #
+      # rubocop:disable Metrics/ParameterLists
+      def command_line_result(command, result, processed_out, processed_err, timeout, raise_on_failure)
+        Git::CommandLine::Result.new(command, result, processed_out, processed_err).tap do |processed_result|
+          raise Git::TimeoutError.new(processed_result, timeout) if result.timed_out?
+
+          raise Git::SignaledError, processed_result if result.signaled?
+
+          raise Git::FailedError, processed_result if raise_on_failure && !result.success?
+        end
+      end
+      # rubocop:enable Metrics/ParameterLists
+    end
+  end
+end