git 4.4.0 → 5.0.0.beta.1

data/lib/git/branch.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'git/path'
+require 'git/base'
+require_relative 'branch_info'
 
 module Git
   # Represents a Git branch
@@ -28,7 +29,7 @@ module Git
     # by {Git::Remote#branch} use the `<remote>/<branch>` form (e.g.
     # `'origin/main'`) which does **not** populate {#remote}.
     #
-    # @example
+    # @example Local and remote-tracking branch full refnames
     #   git.branch('main').full                  #=> 'main'
     #   git.branch('remotes/origin/main').full   #=> 'remotes/origin/main'
     #
@@ -43,7 +44,7 @@ module Git
     # branches and for remote-tracking branches in `<remote>/<branch>` form
     # (such as those returned by {Git::Remote#branch}).
     #
-    # @example
+    # @example Local and remote-tracking branches
     #   git.branch('main').remote                  #=> nil
     #   git.branch('remotes/origin/main').remote   #=> #<Git::Remote 'origin'>
     #   git.remote('origin').branch('main').remote #=> nil  # uses 'origin/main' form
@@ -54,37 +55,39 @@ module Git
 
     # The short branch name without the remote prefix
     #
-    # For branches initialized with a `remotes/` or `refs/remotes/` prefix, the
-    # prefix is stripped and this returns the bare branch name (e.g. `'main'`
-    # rather than `'remotes/origin/main'`). For branches in the
-    # `<remote>/<branch>` form (such as those created by {Git::Remote#branch}),
-    # no stripping occurs and `name` returns the full form (e.g. `'origin/main'`).
+    # For both local and remote-tracking branches this is the bare branch
+    # name (e.g. `'main'` rather than `'remotes/origin/main'`).
     #
-    # @example
-    #   git.branch('main').name                       #=> 'main'
-    #   git.branch('remotes/origin/main').name        #=> 'main'
-    #   git.remote('origin').branch('main').name      #=> 'origin/main'
+    # @example Local and remote-tracking branch short names
+    #   git.branch('main').name                  #=> 'main'
+    #   git.branch('remotes/origin/main').name   #=> 'main'
     #
-    # @return [String] the branch name
+    # @return [String] the short branch name
     #
     attr_accessor :name
 
     # Initialize a new Branch object
     #
-    # @api private
+    # @param base [Git::Base, Git::Repository] the git repository
     #
-    # @note Use {Git::Base#branch} or {Git::Base#branches} instead of constructing directly
+    #   Accepts either a {Git::Base} (legacy) or a {Git::Repository} (new form).
+    #   The `is_a?(Git::Base)` guard will be removed when {Git::Base} is deleted
+    #   in Phase 4.
     #
-    # @param base [Git::Base] the git repository
+    # @param branch_info_or_name [Git::BranchInfo, String] branch info object or name string
     #
-    # @param name [String] the full or short branch name
+    #   Passing a BranchInfo is preferred; String support is for backward compatibility.
     #
-    def initialize(base, name)
-      @full = name
+    # @note Use {Git::Base#branch} or {Git::Base#branches} instead of constructing directly
+    #
+    # @api private
+    #
+    def initialize(base, branch_info_or_name)
       @base = base
       @gcommit = nil
       @stashes = nil
-      @remote, @name = parse_name(name)
+
+      initialize_from_argument(branch_info_or_name)
     end
 
     # Returns the commit at the tip of this branch
@@ -97,7 +100,7 @@ module Git
     # @return [Git::Object] the commit at the tip of this branch
     #
     def gcommit
-      @gcommit ||= @base.gcommit(@full)
+      @gcommit ||= branch_repository.gcommit(@full)
       @gcommit
     end
 
@@ -111,7 +114,7 @@ module Git
     # @return [Git::Stashes] the stash list
     #
     def stashes
-      @stashes ||= Git::Stashes.new(@base)
+      @stashes ||= Git::Stashes.new(branch_repository)
     end
 
     # Checks out this branch, attempting to create it first if it does not already exist
@@ -120,8 +123,10 @@ module Git
     # step is silently ignored and the checkout proceeds regardless.
     #
     # **Note:** for remote-tracking branches (where {#remote} is not `nil`),
-    # {#full} is a ref such as `'remotes/origin/main'`. Checking out a
-    # remote-tracking ref places the repository in a **detached HEAD** state.
+    # `check_if_create` will attempt to create a *local* branch named {#name}
+    # as a side-effect before checking out {#full} (which typically results in
+    # a detached HEAD). This is a known limitation; see
+    # [ruby-git#1280](https://github.com/ruby-git/ruby-git/issues/1280).
     #
     # @example Check out a branch
     #   git = Git.open('.')
@@ -133,7 +138,7 @@ module Git
     #
     def checkout
       check_if_create
-      @base.checkout(@full)
+      branch_repository.checkout(@full)
     end
 
     # Archives this branch and writes the result to a file
@@ -153,7 +158,7 @@ module Git
     # @raise [Git::FailedError] if `git archive` fails
     #
     def archive(file, opts = {})
-      @base.lib.archive(@full, file, opts)
+      branch_repository.archive(@full, file, opts)
     end
 
     # Checks out this branch for the duration of a block, then restores the original branch
@@ -184,14 +189,14 @@ module Git
     # @raise [Git::FailedError] if any of the underlying git operations (checkout, commit, reset) fail
     #
     def in_branch(message = 'in branch work')
-      old_current = @base.lib.branch_current
+      old_current = branch_repository.current_branch
       checkout
       if yield
-        @base.commit_all(message)
+        branch_repository.commit_all(message)
       else
-        @base.reset_hard
+        branch_repository.reset(nil, hard: true)
       end
-      @base.checkout(old_current)
+      branch_repository.checkout(old_current)
     end
 
     # Creates this branch if it does not already exist
@@ -202,8 +207,7 @@ module Git
     # @example Create a new branch
     #   git.branch('feature').create
     #
-    # @return [String, nil] git's stdout from branch creation (typically empty),
-    #   or `nil` if an error was rescued
+    # @return [nil]
     #
     def create
       check_if_create
@@ -211,22 +215,22 @@ module Git
 
     # Deletes this branch
     #
-    # **Note:** this method only works correctly for local branches. Calling it on
-    # a remote-tracking branch (one where {#remote} is not `nil`) will attempt to
-    # delete a *local* branch with the same short name rather than the
-    # remote-tracking ref, which is almost certainly not what you want.
-    # See [ruby-git#1280](https://github.com/ruby-git/ruby-git/issues/1280) for
-    # the planned fix.
+    # Remote-tracking branches (one where {#remote} is not `nil`) delete the
+    # local remote-tracking ref; they do not push a deletion to the remote.
     #
     # @example Delete a local branch
     #   git.branch('old-feature').delete
     #
     # @return [String] git's deletion output
     #
-    # @raise [Git::FailedError] if the branch cannot be deleted
+    # @raise [Git::Error] if the branch cannot be deleted
     #
     def delete
-      @base.lib.branch_delete(@name)
+      if @remote
+        branch_repository.branch_delete("#{@remote.name}/#{@name}", remotes: true)
+      else
+        branch_repository.branch_delete(@name)
+      end
     end
 
     # Returns true if this is the currently checked-out branch
@@ -241,11 +245,11 @@ module Git
     #   git.branch('main').current #=> true
     #
     # @return [Boolean] whether this branch is currently checked out
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
     def current # rubocop:disable Naming/PredicateMethod
-      @base.lib.branch_current == @name
+      branch_repository.current_branch == @name
     end
 
     # Returns true if this branch contains the given commit
@@ -261,11 +265,11 @@ module Git
     # @param commit [String] the commit SHA or ref to check
     #
     # @return [Boolean] whether this branch contains the given commit
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
     def contains?(commit)
-      !@base.lib.branch_contains(commit, name).empty?
+      !branch_repository.branch_contains(commit, name).empty?
     end
 
     # Merges a branch into this branch, or merges this branch into the current branch
@@ -297,26 +301,25 @@ module Git
     #
     #   @return [String] git's stdout from the merge command
     #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status during
-    #   the merge, checkout, commit, or reset operations
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
     def merge(branch = nil, message = nil)
       if branch
         in_branch do
-          @base.merge(branch, message)
+          branch_repository.merge(branch, message)
           false
         end
         # merge a branch into this one
       else
         # merge this branch into the current one
-        @base.merge(@name)
+        branch_repository.merge(@name)
       end
     end
 
     # Updates the git ref for this branch to point to the given commit
     #
     # The target ref depends on whether {#remote} is set:
-    # - When {#remote} is not `nil` (i.e. the branch was initialised with a
+    # - When {#remote} is not `nil` (i.e. the branch was initialized with a
     #   `remotes/<remote>/` or `refs/remotes/<remote>/` prefix), updates
     #   `refs/remotes/<remote>/<name>`.
     # - Otherwise updates `refs/heads/<name>`. Note that branches in the
@@ -329,15 +332,15 @@ module Git
     #
     # @param commit [String] the commit SHA to point this branch at
     #
-    # @return [String] the stdout output from `git update-ref`
+    # @return [Git::CommandLineResult] the result of calling `git update-ref`
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
     def update_ref(commit)
       if @remote
-        @base.lib.update_ref("refs/remotes/#{@remote.name}/#{@name}", commit)
+        branch_repository.update_ref("remotes/#{@remote.name}/#{@name}", commit)
       else
-        @base.lib.update_ref("refs/heads/#{@name}", commit)
+        branch_repository.update_ref(@name, commit)
       end
     end
 
@@ -383,11 +386,51 @@ module Git
 
     private
 
+    # Dispatches initialization to the appropriate strategy
+    #
+    # @param branch_info_or_name [Git::BranchInfo, String] branch info or name string
+    #
+    # @return [nil]
+    #
+    # @api private
+    #
+    def initialize_from_argument(branch_info_or_name)
+      if branch_info_or_name.is_a?(Git::BranchInfo)
+        initialize_from_branch_info(branch_info_or_name)
+      else
+        initialize_from_name(branch_info_or_name)
+      end
+    end
+
+    # Initialize from a BranchInfo object (preferred path)
+    #
+    # @param branch_info [Git::BranchInfo] the branch info
+    #
+    # @return [nil]
+    #
+    def initialize_from_branch_info(branch_info)
+      @full = branch_info.refname
+      @name = branch_info.short_name
+      @remote = branch_info.remote_name ? Git::Remote.new(@base, branch_info.remote_name) : nil
+    end
+
+    # Initialize from a string name (legacy path for backward compatibility)
+    #
+    # @param name [String] the branch name
+    #
+    # @return [nil]
+    #
+    def initialize_from_name(name)
+      @full = name
+      @remote, @name = parse_name(name)
+    end
+
     # Parses a full branch name into remote and short branch name components
     #
-    # Strips an optional `remotes/` or `refs/remotes/` prefix. Only inputs that begin
-    # with one of those prefixes yield a remote object; all other inputs (including
-    # `'origin/master'`) are treated as local branch names with a `nil` remote.
+    # Strips an optional `remotes/` or `refs/remotes/` prefix. Only inputs that
+    # begin with one of those prefixes yield a remote object; all other inputs
+    # (including `'origin/master'`) are treated as local branch names with a
+    # `nil` remote.
     #
     # @example Local branches
     #   parse_name('master')            #=> [nil, 'master']
@@ -399,8 +442,9 @@ module Git
     #
     # @param name [String] the full branch name to parse
     #
-    # @return [Array(Git::Remote, String)] a two-element array with the remote object
-    #   (or `nil`) and the short branch name
+    # @return [Array(Git::Remote, String)] a two-element array; the first element is
+    #   a {Git::Remote} for remote-tracking branches or `nil` for local branches,
+    #   and the second element is the short branch name
     #
     def parse_name(name)
       # Expect this will always match
@@ -412,12 +456,26 @@ module Git
 
     # Creates the branch if it does not already exist, ignoring errors
     #
-    # @return [String, nil] stdout from branch creation, or `nil` if an error was rescued
+    # @return [nil]
     #
     def check_if_create
-      @base.lib.branch_new(@name)
+      branch_repository.branch_new(@name)
     rescue StandardError
       nil
     end
+
+    # Resolves the {Git::Repository} for this branch
+    #
+    # 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]
+    #
+    # @api private
+    #
+    def branch_repository
+      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+    end
   end
 end

data/lib/git/branch_delete_failure.rb

@@ -0,0 +1,31 @@
+# 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,63 @@
+# 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
+    #
+    # @return [Boolean] true if no branches failed to delete, false otherwise
+    #
+    # @example
+    #   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
+    #
+    def success?
+      not_deleted.empty?
+    end
+  end
+end

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