git 1.19.1 → 5.5.0

data/lib/git/branch_delete_failure.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents a branch that failed to be deleted
+  #
+  # This is an immutable data object returned as part of {Git::BranchDeleteResult}
+  # when one or more branches could not be deleted.
+  #
+  # @example
+  #   failure = Git::BranchDeleteFailure.new(
+  #     name: 'nonexistent',
+  #     error_message: "branch 'nonexistent' not found."
+  #   )
+  #   failure.name          #=> 'nonexistent'
+  #   failure.error_message #=> "branch 'nonexistent' not found."
+  #
+  # @see Git::BranchDeleteResult
+  #
+  # @see Git::Commands::Branch::Delete
+  #
+  # @api public
+  #
+  # @!attribute [r] name
+  #   The name of the branch that failed to be deleted
+  #
+  #   @return [String]
+  #
+  # @!attribute [r] error_message
+  #   The error message from git explaining why the branch could not be deleted
+  #
+  #   @return [String]
+  #
+  BranchDeleteFailure = Data.define(:name, :error_message)
+end

data/lib/git/branch_delete_result.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'git/branch_info'
+require 'git/branch_delete_failure'
+
+module Git
+  # Represents the result of a branch delete operation
+  #
+  # This is an immutable data object returned by {Git::Commands::Branch::Delete#call}.
+  # It contains information about which branches were successfully deleted and which
+  # failed to be deleted, along with the reason for each failure.
+  #
+  # Git's `git branch -d` command uses "best effort" semantics - it deletes as many
+  # branches as possible and reports errors for those that couldn't be deleted. This
+  # result object reflects that behavior, allowing callers to inspect both
+  # successes and failures.
+  #
+  # @example Successful deletion of all branches
+  #   result = branch_delete.call('feature-1', 'feature-2')
+  #   result.success?            #=> true
+  #   result.deleted.map(&:name) #=> ['feature-1', 'feature-2']
+  #   result.not_deleted         #=> []
+  #
+  # @example Partial failure (some branches deleted, some not found)
+  #   result = branch_delete.call('feature-1', 'nonexistent', 'feature-2')
+  #   result.success?                    #=> false
+  #   result.deleted.map(&:name)         #=> ['feature-1', 'feature-2']
+  #   result.not_deleted.first.name          #=> 'nonexistent'
+  #   result.not_deleted.first.error_message #=> "branch 'nonexistent' not found."
+  #
+  # @see Git::BranchInfo
+  #
+  # @see Git::BranchDeleteFailure
+  #
+  # @see Git::Commands::Branch::Delete
+  #
+  # @api public
+  #
+  # @!attribute [r] deleted
+  #   Branches that were successfully deleted
+  #
+  #   @return [Array<Git::BranchInfo>]
+  #
+  # @!attribute [r] not_deleted
+  #   Branches that could not be deleted, with the reason for each failure
+  #
+  #   @return [Array<Git::BranchDeleteFailure>]
+  #
+  BranchDeleteResult = Data.define(:deleted, :not_deleted) do
+    # Returns true if all requested branches were successfully deleted
+    #
+    # @example Check if the delete operation succeeded
+    #   result = branch_delete.call('feature-branch')
+    #   if result.success?
+    #     puts "All branches deleted successfully"
+    #   else
+    #     puts "Some branches could not be deleted:"
+    #     result.not_deleted.each { |f| puts "  #{f.name}: #{f.error_message}" }
+    #   end
+    #
+    # @return [Boolean] true if no branches failed to delete, false otherwise
+    def success?
+      not_deleted.empty?
+    end
+  end
+end

data/lib/git/branch_info.rb

@@ -0,0 +1,237 @@
+# 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
+  #
+  # @example Parse branch refnames
+  #   'main' => { remote_name: nil, branch_name: 'main' }
+  #   'refs/heads/main' => { remote_name: nil, branch_name: 'main' }
+  #   'remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
+  #   'refs/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' }
+  #
+  # @note This regex handles both raw full refs (e.g., `refs/heads/main`) as stored in
+  #   {Git::BranchInfo#refname} and normalized short-form refs (e.g., `main`,
+  #   `remotes/origin/main`) used elsewhere.
+  #
+  # @note This regex is a fallback for branch refnames parsed without configured
+  #   remote context. Remote names containing '/' can only be resolved reliably
+  #   when the parser is given the configured remote names. See:
+  #   https://github.com/ruby-git/ruby-git/issues/919
+  #
+  # @api private
+  BRANCH_REFNAME_REGEXP = %r{
+    \A                                            # start of string
+    (?:refs/heads/)?                              # optional refs/heads/ prefix (stripped)
+    (?:(?:refs/)?remotes/(?<remote_name>[^/]+)/)? # optional refs?/remotes/<remote_name>/
+    (?<branch_name>.+)                            # branch name (everything else)
+    \z                                            # end of string
+  }x
+
+  # Sentinel for distinguishing omitted BranchInfo remote_name from explicit nil
+  REMOTE_NAME_NOT_GIVEN = Object.new.freeze
+  private_constant :REMOTE_NAME_NOT_GIVEN
+
+  # 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 Local branch with upstream tracking
+  #   info = Git::BranchInfo.new(
+  #     refname: 'refs/heads/main',
+  #     target_oid: 'abc123def456789012345678901234567890abcd',
+  #     current: true,
+  #     worktree_path: nil,
+  #     symref: nil,
+  #     upstream: 'refs/remotes/origin/main'
+  #   )
+  #   info.current?     #=> true
+  #   info.remote?      #=> false
+  #   info.short_name   #=> 'main'
+  #   info.upstream     #=> 'refs/remotes/origin/main'
+  #
+  # @example Remote-tracking branch
+  #   info = Git::BranchInfo.new(
+  #     refname: 'refs/remotes/origin/main',
+  #     target_oid: 'abc123def456789012345678901234567890abcd',
+  #     current: false,
+  #     worktree_path: nil,
+  #     symref: nil,
+  #     upstream: nil
+  #   )
+  #   info.remote?      #=> true
+  #   info.remote_name  #=> 'origin'
+  #   info.short_name   #=> 'main'
+  #
+  # @see Git::Repository::Branching#branch_list for the repository method that returns these
+  #
+  # @see Git::Commands::Branch::List for the command that produces these
+  #
+  # @api public
+  #
+  # @!attribute [r] refname
+  #
+  #   The full reference name of the branch
+  #
+  #   Must be the full refname as returned by git (e.g., 'refs/heads/main',
+  #   'refs/remotes/origin/main') because the short name alone is not guaranteed to
+  #   be unique (e.g., 'main' could exist as both a local and remote branch).
+  #
+  #   @return [String] the branch refname (e.g., 'refs/heads/main',
+  #     'refs/remotes/origin/main')
+  #
+  # @!attribute [r] remote_name
+  #
+  #   @return [String, nil] the resolved or fallback-derived remote name, or nil
+  #     for local branches
+  #
+  # @!attribute [r] target_oid
+  #
+  #   The commit object ID (SHA) that this branch points to (aka HEAD)
+  #
+  #   @return [String, nil] the full 40-character object ID, or nil if branch is
+  #   unborn (no commits yet)
+  #
+  # @!attribute [r] current
+  #
+  #   Whether this branch is currently checked out in the current worktree
+  #
+  #   @return [Boolean] true if this is the current branch
+  #
+  #   @note A branch can be current ({#current?} true) or in another worktree
+  #     ({#other_worktree?} true), but never both. A branch not checked out
+  #     anywhere has both false.
+  #
+  # @!attribute [r] worktree_path
+  #
+  #   The absolute path of the *other* linked worktree this branch is checked
+  #   out in, or nil.
+  #
+  #   This is nil in two distinct cases:
+  #   - The branch is the current branch in this worktree (use {#current?} to
+  #     distinguish that case)
+  #   - The branch is not checked out in any worktree
+  #
+  #   This path is suppressed for the current branch even though git reports it
+  #   via `%(worktreepath)`, because the current worktree's path is already
+  #   known from the repository object and storing it here would make
+  #   {#other_worktree?} incorrect.
+  #
+  #   @return [String, nil] the absolute path of the linked worktree root
+  #     directory (e.g., `'/home/user/projects/my-repo-hotfix'`), or nil if
+  #     the branch is not checked out in a different linked 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 refname as reported by git
+  #
+  #   @return [String, nil] the raw upstream refname from `%(upstream)`
+  #     (e.g., `'refs/remotes/origin/main'`), or nil if no upstream is configured
+  #
+  #   @note Remote-tracking branches (e.g., `'refs/remotes/origin/main'`) have upstream: nil
+  #
+  #   @note This is the raw refname snapshot from when the branch list was read.
+  #     It does not reflect live git state after the snapshot was taken.
+  #
+  BranchInfo = Data.define(:refname, :remote_name, :target_oid, :current, :worktree_path, :symref, :upstream) do
+    # @param refname [String] the full branch refname
+    #
+    # @param remote_name [String, nil] resolved remote name, nil for local branches,
+    #   or omitted to derive from `refname`
+    #
+    # @param target_oid [String, nil] the commit object ID, or nil for unborn branches
+    #
+    # @param current [Boolean] whether this branch is currently checked out
+    #
+    # @param worktree_path [String, nil] path to another linked worktree, or nil
+    #
+    # @param symref [String, nil] symbolic reference target, or nil
+    #
+    # @param upstream [String, nil] upstream refname, or nil
+    #
+    def initialize(refname:, target_oid:, current:, worktree_path:, symref:, upstream:, # rubocop:disable Metrics/ParameterLists
+                   remote_name: REMOTE_NAME_NOT_GIVEN)
+      remote_name = self.class.fallback_remote_name(refname) if remote_name.equal?(REMOTE_NAME_NOT_GIVEN)
+      self.class.validate_remote_name!(refname, remote_name)
+
+      super
+    end
+
+    # @param refname [String] the branch refname to validate
+    #
+    # @param remote_name [String, nil] the remote name to validate
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] if the remote name contradicts the refname type
+    def self.validate_remote_name!(refname, remote_name)
+      if remote_tracking_refname?(refname)
+        unless remote_name.is_a?(String) && !remote_name.empty?
+          raise ArgumentError, 'remote_name must be a non-empty String for remote-tracking refname'
+        end
+
+        remote_ref_prefix = %r{\A(?:refs/)?remotes/#{Regexp.escape(remote_name)}/}
+        raise ArgumentError, 'remote_name must match remote-tracking refname' unless refname.match?(remote_ref_prefix)
+      elsif !remote_name.nil?
+        raise ArgumentError, 'remote_name must be nil for local branch refname'
+      end
+    end
+
+    # @param refname [String] the branch refname to parse
+    #
+    # @return [String, nil] the regex-derived remote name, or nil for local branches
+    def self.fallback_remote_name(refname)
+      refname.match(Git::BRANCH_REFNAME_REGEXP)[:remote_name]
+    end
+
+    # @param refname [String] the branch refname to inspect
+    #
+    # @return [Boolean] true if the refname is a remote-tracking refname
+    def self.remote_tracking_refname?(refname)
+      refname.match?(%r{\A(?:refs/)?remotes/[^/]+/.+})
+    end
+
+    # @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 [String] the short branch name without any remote or heads prefix
+    #   (e.g., 'main' or 'feature/foo')
+    def short_name
+      return refname.delete_prefix('refs/heads/') if remote_name.nil?
+
+      remote_ref_prefix = %r{\A(?:refs/)?remotes/#{Regexp.escape(remote_name)}/}
+      refname.sub(remote_ref_prefix, '')
+    end
+
+    # @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 linked worktree
+    def other_worktree? = !worktree_path.nil?
+
+    # @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] string representation (the full refname)
+    def to_s = refname
+  end
+end

data/lib/git/branches.rb

@@ -1,71 +1,194 @@
+# 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 }
+  #
+  # @deprecated Use {Git::Repository::Branching#branch_list} instead
+  #
+  #   {Git::Repository::Branching#branch_list} returns `Array<Git::BranchInfo>`
+  #   (immutable value objects). Filter it with `select(&:remote?)` or
+  #   `reject(&:remote?)` in place of {#remote} and {#local}, and look a
+  #   branch up by name with `branch_list(name).first` in place of {#[]}.
+  #   Constructing a `Git::Branches` emits a deprecation warning.
+  #
+  # @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
+    #
+    # @deprecated Use {Git::Repository::Branching#branch_list} instead
+    #
+    # @see Git::Repository::Branching#branch_list
+    #
     def initialize(base)
+      Git::Deprecation.warn(
+        'Git::Branches is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#branch_list instead.'
+      )
       @branches = {}
-      
+      @lookup = {}
+
       @base = base
-            
-      @base.lib.branches_all.each do |b|
-        @branches[b[0]] = Git::Branch.new(@base, b[0])
-      end
+
+      load_branches
     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
-      self.select { |b| !b.remote }
+      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 { |b| b.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    
-    
-    def each(&block)
-      @branches.values.each(&block)
     end
-    
-    # Returns the target branch
+
+    # 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 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.inject(@branches) do |branches, branch|
-        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 =~ /^remotes\/.+/
-        
-        branches
-      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 = ''
-      @branches.each do |k, b|
-        out << (b.current ? '* ' : '  ') << b.to_s << "\n"
+      out = +''
+      @branches.each_value do |b|
+        # Git::Branch#current is deprecated too; silence it so one to_s call emits one warning
+        current = Git::Deprecation.silence { b.current }
+        out << (current ? '* ' : '  ') << b.to_s << "\n"
       end
       out
     end
-    
-  end
 
+    private
+
+    # Builds a Git::Branch for every branch in the repository and indexes it
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def load_branches
+      branch_repository.branch_list.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
+
+    # @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