git 4.3.2 → 5.0.0.beta.1

data/lib/git/branch.rb

@@ -1,102 +1,381 @@
 # frozen_string_literal: true
 
-require 'git/path'
+require 'git/base'
+require_relative 'branch_info'
 
 module Git
   # Represents a Git branch
+  #
+  # Branch objects provide access to branch metadata and operations like checkout,
+  # delete, and merge. They should be obtained via {Git::Base#branch} or
+  # {Git::Base#branches}, not constructed directly.
+  #
+  # @example Getting a branch
+  #   git = Git.open('.')
+  #   branch = git.branch('main')
+  #   branch.checkout
+  #
+  # @example Listing branches
+  #   git.branches.each { |b| puts b.name }
+  #
+  # @api public
+  #
   class Branch
-    attr_accessor :full, :remote, :name
+    # The full refname of this branch
+    #
+    # For local branches this is the short name (e.g. `'main'`). For
+    # remote-tracking branches obtained via {Git::Base#branches} this includes
+    # the `remotes/` prefix (e.g. `'remotes/origin/main'`). Branches constructed
+    # by {Git::Remote#branch} use the `<remote>/<branch>` form (e.g.
+    # `'origin/main'`) which does **not** populate {#remote}.
+    #
+    # @example Local and remote-tracking branch full refnames
+    #   git.branch('main').full                  #=> 'main'
+    #   git.branch('remotes/origin/main').full   #=> 'remotes/origin/main'
+    #
+    # @return [String] the full refname
+    #
+    attr_accessor :full
 
-    def initialize(base, name)
-      @full = name
+    # The remote for this branch, or `nil` for local or bare-name remote-tracking branches
+    #
+    # Set to a {Git::Remote} object only when this branch was initialized with a
+    # `remotes/<remote>/` or `refs/remotes/<remote>/` prefix. `nil` for local
+    # branches and for remote-tracking branches in `<remote>/<branch>` form
+    # (such as those returned by {Git::Remote#branch}).
+    #
+    # @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
+    #
+    # @return [Git::Remote, nil] the remote object, or `nil`
+    #
+    attr_accessor :remote
+
+    # The short branch name without the remote prefix
+    #
+    # For both local and remote-tracking branches this is the bare branch
+    # name (e.g. `'main'` rather than `'remotes/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 short branch name
+    #
+    attr_accessor :name
+
+    # Initialize a new Branch object
+    #
+    # @param base [Git::Base, Git::Repository] the git repository
+    #
+    #   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 branch_info_or_name [Git::BranchInfo, String] branch info object or name string
+    #
+    #   Passing a BranchInfo is preferred; String support is for backward compatibility.
+    #
+    # @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
+    #
+    # The result is memoized after the first call.
+    #
+    # @example Get the tip commit
+    #   git.branch('main').gcommit #=> #<Git::Object ...>
+    #
+    # @return [Git::Object] the commit at the tip of this branch
+    #
     def gcommit
-      @gcommit ||= @base.gcommit(@full)
+      @gcommit ||= branch_repository.gcommit(@full)
       @gcommit
     end
 
+    # Returns the stash list for this repository
+    #
+    # The result is memoized after the first call.
+    #
+    # @example Iterate over stash entries
+    #   git.branch('main').stashes.each { |s| puts s }
+    #
+    # @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
+    #
+    # Branch creation is attempted via {#check_if_create}; any error from that
+    # step is silently ignored and the checkout proceeds regardless.
+    #
+    # **Note:** for remote-tracking branches (where {#remote} is not `nil`),
+    # `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('.')
+    #   git.branch('main').checkout
+    #
+    # @return [String] git's stdout from the checkout
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def checkout
       check_if_create
-      @base.checkout(@full)
+      branch_repository.checkout(@full)
     end
 
+    # Archives this branch and writes the result to a file
+    #
+    # @example Archive to a tar file
+    #   git.branch('main').archive('/tmp/main.tar')
+    #
+    # @example Archive to a zip file
+    #   git.branch('main').archive('/tmp/main.zip', format: 'zip')
+    #
+    # @param file [String] path to the destination archive file
+    #
+    # @param opts [Hash] archive options (see {Git::Base#archive})
+    #
+    # @return [String] the path to the written archive file
+    #
+    # @raise [Git::FailedError] if `git archive` fails
+    #
     def archive(file, opts = {})
-      @base.lib.archive(@full, file, opts)
+      branch_repository.archive(@full, file, opts)
     end
 
-    # g.branch('new_branch').in_branch do
-    #   # create new file
-    #   # do other stuff
-    #   return true # auto commits and switches back
-    # end
+    # Checks out this branch for the duration of a block, then restores the original branch
+    #
+    # If the block returns a truthy value, all pending changes are committed with the
+    # given message before switching back to the original branch. If the block returns
+    # a falsy value, a hard reset is performed before switching back.
+    #
+    # **Note:** the restore checkout is not wrapped in `ensure`. If the block,
+    # the commit, or the reset raises an exception, the repository will be left
+    # checked out on this branch rather than restored to the original.
+    #
+    # @example Commit a new file on a feature branch
+    #   git.branch('feature').in_branch('Add README') do
+    #     File.write('README.md', '# Hello')
+    #     git.add('README.md')
+    #     true  # commit and return to original branch
+    #   end
+    #
+    # @param message [String] commit message used when the block returns truthy
+    #
+    # @yield Executes the block with this branch checked out
+    #
+    # @yieldreturn [Object] return a truthy value to commit all changes, a falsy value to hard-reset
+    #
+    # @return [String] git's stdout from the final checkout back to the original branch
+    #
+    # @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
+    #
+    # Silently ignores any error raised during branch creation (including the case
+    # where the branch already exists).
+    #
+    # @example Create a new branch
+    #   git.branch('feature').create
+    #
+    # @return [nil]
+    #
     def create
       check_if_create
     end
 
+    # Deletes this branch
+    #
+    # 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::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
+    #
+    # **Note:** this compares the current branch's short name against {#name}.
+    # For a remote-tracking branch (where {#remote} is not `nil`), {#name} is
+    # still the bare short name (e.g. `'main'`), so this will return `true`
+    # whenever the *local* branch with that name is checked out — not the
+    # remote-tracking ref itself.
+    #
+    # @example Check whether currently on main
+    #   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
+    #
     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
+    #
+    # **Note:** this queries local branches by short name. For a remote-tracking
+    # branch (where {#remote} is not `nil`), it checks the *local* branch with
+    # the same {#name} rather than the remote-tracking ref, which may give an
+    # inaccurate result.
+    #
+    # @example Check if a commit is reachable from this branch
+    #   git.branch('main').contains?('abc1234') #=> true
+    #
+    # @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
+    #
     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
+    #
+    # @overload merge(branch, message = nil)
+    #
+    #   Temporarily checks out this branch, merges the given branch into it,
+    #   then restores the original branch.
+    #
+    #   **Note:** if `self` is a remote-tracking branch (where {#remote} is not
+    #   `nil`), this delegates to {#checkout} which has the detached-HEAD
+    #   side-effect described there. The remote-tracking ref will not be updated.
+    #
+    #   @example Merge a feature branch into main
+    #     git.branch('main').merge('feature')
+    #
+    #   @param branch [String] the name of the branch to merge into this one
+    #
+    #   @param message [String, nil] commit message for the merge commit
+    #
+    #   @return [String] git's stdout from the final checkout back to the original branch
+    #
+    # @overload merge()
+    #
+    #   Merges this branch into the currently checked-out branch.
+    #
+    #   @example Merge main into the current branch
+    #     git.branch('main').merge
+    #
+    #   @return [String] git's stdout from the merge command
+    #
+    # @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 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
+    #   `<remote>/<branch>` form (e.g. those returned by {Git::Remote#branch})
+    #   have `remote == nil` and therefore update `refs/heads/<remote>/<name>`,
+    #   **not** `refs/remotes/...`.
+    #
+    # @example Advance a local branch to a new commit
+    #   git.branch('feature').update_ref('abc1234def5678')
+    #
+    # @param commit [String] the commit SHA to point this branch at
+    #
+    # @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
 
+    # Returns this branch as a single-element array containing its full refname
+    #
+    # @example Get branch as array
+    #   git.branch('main').to_a #=> ['main']
+    #
+    # @return [Array<String>] a single-element array containing the full refname
+    #
     def to_a
       [@full]
     end
 
+    # Returns the full refname of this branch as a string
+    #
+    # @example Get branch as string
+    #   git.branch('main').to_s #=> 'main'
+    #
+    # @return [String] the full refname
+    #
     def to_s
       @full
     end
 
+    # Regular expression for parsing branch refnames
+    #
+    # Matches full and short refnames, capturing an optional remote name and the
+    # branch name. Used internally to identify remote-tracking branches.
+    #
+    # @api private
+    #
     BRANCH_NAME_REGEXP = %r{
       ^
-        # Optional 'refs/remotes/' at the beggining to specify a remote tracking branch
+        # Optional 'remotes/' or 'refs/remotes/' at the beginning to specify a remote tracking branch
         # with a <remote_name>. <remote_name> is nil if not present.
         (?:
           (?:(?:refs/)?remotes/)(?<remote_name>[^/]+)/
@@ -107,26 +386,66 @@ module Git
 
     private
 
-    # Given a full branch name return an Array containing the remote and branch names.
+    # Dispatches initialization to the appropriate strategy
+    #
+    # @param branch_info_or_name [Git::BranchInfo, String] branch info or name string
+    #
+    # @return [nil]
     #
-    # Removes 'remotes' from the beggining of the name (if present).
-    # Takes the second part (splittign by '/') as the remote name.
-    # Takes the rest as the repo name (can also hold one or more '/').
+    # @api private
     #
-    # Example:
-    #   # local branches
-    #   parse_name('master') #=> [nil, 'master']
-    #   parse_name('origin/master') #=> [nil, 'origin/master']
-    #   parse_name('origin/master/v2') #=> [nil, 'origin/master']
+    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)
     #
-    #   # remote branches
-    #   parse_name('remotes/origin/master') #=> ['origin', 'master']
-    #   parse_name('remotes/origin/master/v2') #=> ['origin', 'master/v2']
-    #   parse_name('refs/remotes/origin/master') #=> ['origin', 'master']
-    #   parse_name('refs/remotes/origin/master/v2') #=> ['origin', 'master/v2']
+    # @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.
+    #
+    # @example Local branches
+    #   parse_name('master')            #=> [nil, 'master']
+    #   parse_name('origin/master')     #=> [nil, 'origin/master']
+    #
+    # @example Remote-tracking branches
+    #   parse_name('remotes/origin/master')      #=> [#<Git::Remote 'origin'>, 'master']
+    #   parse_name('refs/remotes/origin/master') #=> [#<Git::Remote 'origin'>, 'master']
+    #
+    # @param name [String] the full branch name to parse
+    #
+    # @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
     #
-    # param [String] name branch full name.
-    # return [<Git::Remote,NilClass,String>] an Array containing the remote and branch names.
     def parse_name(name)
       # Expect this will always match
       match = name.match(BRANCH_NAME_REGEXP)
@@ -135,10 +454,28 @@ module Git
       [remote, branch_name]
     end
 
+    # Creates the branch if it does not already exist, ignoring errors
+    #
+    # @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