git 5.0.0.beta.1 → 5.0.0.beta.2

data/lib/git/parsers/ls_remote.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Git
+  module Parsers
+    # Parser for `git ls-remote` command output
+    #
+    # @api private
+    #
+    module LsRemote
+      module_function
+
+      # Parse `git ls-remote` stdout lines into a structured Hash
+      #
+      # @param lines [Array<String>] the individual stdout lines
+      #
+      # @return [Hash{String => Hash}] a map of ref type to ref data
+      #
+      #   The structure differs by key:
+      #
+      #   - `"head"` maps directly to `{ ref: String, sha: String }`
+      #   - Other keys (e.g. `"branches"`, `"tags"`) map to
+      #     `{ name => { ref: String, sha: String } }`
+      #
+      def parse_output(lines)
+        lines.each_with_object(Hash.new { |h, k| h[k] = {} }) do |line, hsh|
+          type, name, value = parse_line(line)
+          if name
+            hsh[type][name] = value
+          else
+            hsh[type].update(value)
+          end
+        end
+      end
+
+      # Parse a single `git ls-remote` output line
+      #
+      # @param line [String] a single line from ls-remote stdout
+      #
+      # @return [Array(String, String|nil, Hash)] `[type, name, value]` where
+      #   `value` is `{ ref: String, sha: String }`
+      #
+      # @raise [Git::UnexpectedResultError] if the line is not in `<sha>\t<ref>` format
+      #
+      def parse_line(line)
+        unless line.include?("\t") && line.match?(/\A[0-9a-f]{4,}\t/)
+          raise Git::UnexpectedResultError, "Unexpected ls-remote output line: #{line.inspect}"
+        end
+
+        sha, info = line.split("\t", 2)
+        ref, type, name = info.split('/', 3)
+
+        type ||= 'head'
+        type = 'branches' if type == 'heads'
+
+        value = { ref: ref, sha: sha }
+
+        [type, name, value]
+      end
+
+      # Parse `git ls-remote --symref <repo> HEAD` output into a branch name
+      #
+      # @param output [String] command stdout
+      #
+      # @return [String] the default branch name
+      #
+      # @raise [Git::UnexpectedResultError] when the branch cannot be determined
+      #
+      def parse_default_branch(output)
+        match_data = output.match(%r{^ref: refs/remotes/[^/]+/(?<default_branch>[^\t]+)\t})
+        return match_data[:default_branch] if match_data
+
+        match_data = output.match(%r{^ref: refs/heads/(?<default_branch>[^\t]+)\tHEAD$})
+        return match_data[:default_branch] if match_data
+
+        raise Git::UnexpectedResultError, 'Unable to determine the default branch'
+      end
+    end
+  end
+end

data/lib/git/remote.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'git/base'
 require 'git/branch'
 require 'git/branch_info'
 
@@ -8,9 +7,8 @@ module Git
   # A remote in a Git repository
   #
   # Remote objects provide access to remote metadata and operations like fetch,
-  # merge, and remove. They should be obtained via {Git::Base#remote} or the
-  # `remote` factory method on a `Git::Repository` instance, not constructed
-  # directly.
+  # merge, and remove. They should be obtained via `Git::Repository#remote`,
+  # not constructed directly.
   #
   # @example Getting a remote
   #   git = Git.open('.')
@@ -40,16 +38,11 @@ module Git
 
     # Initialize a new Remote 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 base [Git::Repository] the git repository
     #
     # @param name [String] the remote name (e.g. `'origin'`)
     #
-    # @note Use {Git::Base#remote} or the `remote` factory method on a
-    #   `Git::Repository` instance instead of constructing directly
+    # @note Use `Git::Repository#remote` instead of constructing directly
     #
     # @api private
     #
@@ -66,7 +59,7 @@ module Git
     # @example Fetch from origin
     #   git.remote('origin').fetch
     #
-    # @param opts [Hash] fetch options (see {Git::Base#fetch})
+    # @param opts [Hash] fetch options (see `Git::Repository#fetch`)
     #
     # @return [String] git's stdout from the fetch
     #
@@ -119,7 +112,7 @@ module Git
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
     def remove
-      remote_repository.remove_remote(@name)
+      remote_repository.remote_remove(@name)
     end
 
     # Returns the name of this remote as a string
@@ -135,18 +128,12 @@ module Git
 
     private
 
-    # Resolves the {Git::Repository} for this remote
-    #
-    # 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 remote_repository
-      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+      @base
     end
 
     def build_branch_info(refname)

data/lib/git/repository/branching.rb

@@ -11,7 +11,9 @@ require 'git/commands/branch/show_current'
 require 'git/commands/checkout/branch'
 require 'git/commands/checkout/files'
 require 'git/commands/checkout_index'
+require 'git/commands/rev_parse'
 require 'git/commands/update_ref/update'
+require 'git/commands/symbolic_ref/update'
 require 'git/parsers/branch'
 require 'git/repository/shared_private'
 
@@ -24,7 +26,17 @@ module Git
     #
     # @api public
     #
-    module Branching
+    module Branching # rubocop:disable Metrics/ModuleLength
+      # Represents the state of HEAD in a repository
+      #
+      # @!attribute [r] state
+      #   @return [Symbol] one of `:active`, `:unborn`, or `:detached`
+      #
+      # @!attribute [r] name
+      #   @return [String] the branch name, or `'HEAD'` when detached
+      #
+      HeadState = Data.define(:state, :name)
+
       # Option keys accepted by {#checkout}
       #
       CHECKOUT_ALLOWED_OPTS = %i[force f new_branch b start_point].freeze
@@ -54,6 +66,39 @@ module Git
         name.empty? ? 'HEAD' : name
       end
 
+      # Returns the current HEAD state as a structured value object
+      #
+      # HEAD can be in one of three states:
+      #
+      # - **`:active`** — HEAD points to a branch ref that has at least one commit.
+      # - **`:unborn`** — HEAD points to a branch ref that has been created but has
+      #   no commits yet (e.g. immediately after `git init` before any commit).
+      # - **`:detached`** — HEAD points directly to a commit SHA rather than a branch.
+      #
+      # @example Active branch
+      #   repo.current_branch_state
+      #   # => #<data Git::Repository::Branching::HeadState state=:active, name="main">
+      #
+      # @example Unborn branch (no commits yet)
+      #   repo.current_branch_state
+      #   # => #<data Git::Repository::Branching::HeadState state=:unborn, name="main">
+      #
+      # @example Detached HEAD
+      #   repo.current_branch_state
+      #   # => #<data Git::Repository::Branching::HeadState state=:detached, name="HEAD">
+      #
+      # @return [Git::Repository::Branching::HeadState] the current HEAD state
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def current_branch_state
+        branch_name = Git::Commands::Branch::ShowCurrent.new(@execution_context).call.stdout.strip
+        return HeadState.new(state: :detached, name: 'HEAD') if branch_name.empty?
+
+        state = Private.get_branch_state(@execution_context, branch_name)
+        HeadState.new(state: state, name: branch_name)
+      end
+
       # Restore working tree files from a tree-ish
       #
       # @example Restore README.md to its HEAD state
@@ -89,22 +134,22 @@ module Git
       # @param branch [String, nil] the branch to check out; defaults to nil
       #   (i.e. restore HEAD state)
       #
-      # @param options [Hash] options for the checkout command
+      # @param opts [Hash] options for the checkout command
       #
-      # @option options [Boolean, nil] :force (nil) discard local changes when
+      # @option opts [Boolean, nil] :force (nil) discard local changes when
       #   switching branches
       #
-      # @option options [Boolean, String, nil] :new_branch (nil) when `true`,
+      # @option opts [Boolean, String, nil] :new_branch (nil) when `true`,
       #   creates a new branch named `branch` from `:start_point`
       #
       #   When a `String`, creates a new branch with that name, using `branch`
       #   as the start point.
       #
-      # @option options [Boolean, String, nil] :b (nil) alias for `:new_branch`
+      # @option opts [Boolean, String, nil] :b (nil) alias for `:new_branch`
       #
-      # @option options [Boolean, nil] :f (nil) alias for `:force`
+      # @option opts [Boolean, nil] :f (nil) alias for `:force`
       #
-      # @option options [String, nil] :start_point (nil) the commit or branch to
+      # @option opts [String, nil] :start_point (nil) the commit or branch to
       #   start the new branch from; used together with `new_branch: true`
       #
       # @return [String] git's stdout from the checkout
@@ -113,15 +158,15 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      def checkout(branch = nil, options = {})
-        if branch.is_a?(Hash) && options.empty?
-          options = branch
+      def checkout(branch = nil, opts = {})
+        if branch.is_a?(Hash) && opts.empty?
+          opts = branch
           branch = nil
         end
 
-        SharedPrivate.assert_valid_opts!(CHECKOUT_ALLOWED_OPTS, **options)
+        SharedPrivate.assert_valid_opts!(CHECKOUT_ALLOWED_OPTS, **opts)
 
-        target, translated_opts = Private.translate_checkout_opts(branch, options)
+        target, translated_opts = Private.translate_checkout_opts(branch, opts)
         Git::Commands::Checkout::Branch.new(@execution_context).call(target, **translated_opts).stdout
       end
 
@@ -215,6 +260,71 @@ module Git
         local_branch?(branch) || remote_branch?(branch)
       end
 
+      # Checks whether the named branch exists locally
+      #
+      # @example Check whether main exists locally
+      #   repo.is_local_branch?('main')  # => true
+      #
+      # @param branch [String] the local branch name to look up
+      #
+      # @return [Boolean] `true` if the branch exists locally, `false` otherwise
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated use {#local_branch?} instead
+      #
+      def is_local_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+        Git::Deprecation.warn(
+          'Git::Repository#is_local_branch? is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#local_branch? instead.'
+        )
+        local_branch?(branch)
+      end
+
+      # Checks whether the named branch exists as a remote-tracking branch
+      #
+      # @example Check whether master exists on any remote
+      #   repo.is_remote_branch?('master')  # => true
+      #
+      # @param branch [String] the short branch name to look up across all remotes
+      #
+      # @return [Boolean] `true` if a remote-tracking branch with that short name
+      #   exists, `false` otherwise
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated use {#remote_branch?} instead
+      #
+      def is_remote_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+        Git::Deprecation.warn(
+          'Git::Repository#is_remote_branch? is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#remote_branch? instead.'
+        )
+        remote_branch?(branch)
+      end
+
+      # Checks whether the named branch exists locally or as a remote-tracking branch
+      #
+      # @example Check whether main exists anywhere
+      #   repo.is_branch?('main')  # => true
+      #
+      # @param branch [String] the branch name to look up
+      #
+      # @return [Boolean] `true` if the branch exists locally or remotely,
+      #   `false` otherwise
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @deprecated use {#branch?} instead
+      #
+      def is_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+        Git::Deprecation.warn(
+          'Git::Repository#is_branch? is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#branch? instead.'
+        )
+        branch?(branch)
+      end
+
       # Option keys accepted by {#branch_new}
       #
       BRANCH_NEW_ALLOWED_OPTS = %i[].freeze
@@ -307,6 +417,39 @@ module Git
         result.stdout.strip
       end
 
+      # Writes the HEAD symbolic ref to point at the given branch
+      #
+      # Sets `HEAD` to `refs/heads/<branch_name>` via `git symbolic-ref`. This is
+      # equivalent to running `git symbolic-ref HEAD refs/heads/<branch_name>` on
+      # the command line and is the mechanism git uses internally for branch
+      # renaming and orphan-branch checkout.
+      #
+      # @example Change HEAD to point to an existing branch
+      #   repo.change_head_branch('main')
+      #
+      # @example Initialize a repository with a custom default branch name (unborn-branch pattern)
+      #   repo = Git.init('/path/to/repo')
+      #   repo.change_head_branch('my-branch')
+      #   # HEAD now points at refs/heads/my-branch before any commits exist
+      #
+      # @note Pointing HEAD at a branch that does not yet exist places the
+      #   repository in unborn-branch state. This is intentional for repository
+      #   initialization workflows — for example, setting a custom default branch
+      #   name before any commits land — but is unexpected if done by mistake.
+      #   The repository will appear to have no commits until the first commit is
+      #   made on the new branch.
+      #
+      # @param branch_name [String] the branch name to point HEAD at
+      #
+      # @return [void]
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def change_head_branch(branch_name)
+        Git::Commands::SymbolicRef::Update.new(@execution_context).call('HEAD', "refs/heads/#{branch_name}")
+        nil
+      end
+
       # Returns the `git branch --list --contains` stdout for a given commit
       #
       # The output format is the human-readable `git branch` listing: each
@@ -472,6 +615,34 @@ module Git
       module Private
         module_function
 
+        # Determines whether the given branch ref points to an existing commit
+        #
+        # Returns `:active` when the branch ref resolves successfully. Returns
+        # `:unborn` when the branch ref exists but has no commits yet (exit
+        # status 1 with empty stderr from `git rev-parse --verify --quiet`).
+        # Re-raises for any other failure.
+        #
+        # @param execution_context [Git::ExecutionContext::Repository] the
+        #   execution context for git commands
+        #
+        # @param branch_name [String] the branch name to verify
+        #
+        # @return [:active, :unborn] the branch ref state
+        #
+        # @raise [Git::FailedError] if git exits with a failure unrelated to an
+        #   unborn branch
+        #
+        # @api private
+        #
+        def get_branch_state(execution_context, branch_name)
+          Git::Commands::RevParse.new(execution_context).call(branch_name, verify: true, quiet: true)
+          :active
+        rescue Git::FailedError => e
+          raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
+
+          :unborn
+        end
+
         # Translates legacy checkout options to the new command interface
         #
         # Legacy callers passed combinations like:

data/lib/git/repository/committing.rb

@@ -28,53 +28,52 @@ module Git
 
       # Record staged changes as a new commit
       #
-      # @overload commit(message = nil, **options)
+      # @example Commit with a message
+      #   repo.commit('Add README')
       #
-      #   @example Commit with a message
-      #     repo.commit('Add README')
+      # @example Amend the previous commit, reusing its message
+      #   repo.commit(nil, amend: true)
       #
-      #   @example Amend the previous commit, reusing its message
-      #     repo.commit(nil, amend: true)
+      # @example Stage all modified files and commit
+      #   repo.commit('Cleanup', all: true)
       #
-      #   @example Stage all modified files and commit
-      #     repo.commit('Cleanup', all: true)
+      # @param message [String, nil] the commit message; pass `nil` to omit
+      #   (e.g. when using `:amend` to reuse the previous message)
       #
-      #   @param message [String, nil] the commit message; pass `nil` to omit
-      #     (e.g. when using `:amend` to reuse the previous message)
+      # @param opts [Hash] options for the commit command
       #
-      #   @param options [Hash] options for the commit command
+      # @option opts [Boolean, nil] :all (nil) automatically stage modified and
+      #   deleted files before committing
       #
-      #   @option options [Boolean, nil] :all (nil) automatically stage modified and
-      #     deleted files before committing
+      # @option opts [Boolean, nil] :amend (nil) replace the tip of the current
+      #   branch with a new commit
       #
-      #   @option options [Boolean, nil] :amend (nil) replace the tip of the current
-      #     branch with a new commit
+      # @option opts [Boolean, nil] :allow_empty (nil) allow committing with no
+      #   changes
       #
-      #   @option options [Boolean, nil] :allow_empty (nil) allow committing with no
-      #     changes
+      # @option opts [Boolean, nil] :allow_empty_message (nil) allow committing
+      #   with an empty message
       #
-      #   @option options [Boolean, nil] :allow_empty_message (nil) allow committing
-      #     with an empty message
+      # @option opts [String] :author (nil) override the commit author in
+      #   `A U Thor <author@example.com>` format
       #
-      #   @option options [String] :author (nil) override the commit author in
-      #     `A U Thor <author@example.com>` format
+      # @option opts [String] :date (nil) override the author date
       #
-      #   @option options [String] :date (nil) override the author date
+      # @option opts [Boolean, nil] :gpg_sign (nil) GPG-sign the commit
       #
-      #   @option options [Boolean, nil] :gpg_sign (nil) GPG-sign the commit
+      # @option opts [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
       #
-      #   @option options [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
+      # @option opts [Boolean, nil] :no_verify (nil) bypass the pre-commit and
+      #   commit-msg hooks
       #
-      #   @option options [Boolean, nil] :no_verify (nil) bypass the pre-commit and
-      #     commit-msg hooks
+      # @return [String] git's stdout from the commit
       #
-      #   @return [String] git's stdout from the commit
+      # @raise [ArgumentError] when unsupported options are provided
       #
-      #   @raise [ArgumentError] when unsupported options are provided
-      #
-      #   @raise [Git::FailedError] when git exits with a non-zero exit status
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
-      def commit(message = nil, **opts)
+      def commit(message, opts = {})
+        opts = opts.dup
         if opts.key?(:add_all)
           Git::Deprecation.warn('The :add_all option for #commit is deprecated, use :all instead')
           opts[:all] = opts.delete(:add_all)
@@ -90,25 +89,23 @@ module Git
 
       # Commit all modified tracked files without explicitly staging them first
       #
-      # Equivalent to `commit(message, all: true, **options)`.
+      # Equivalent to calling {#commit} with `all: true` merged into `opts`.
       #
-      # @overload commit_all(message, **options)
+      # @example Commit all changes with a message
+      #   repo.commit_all('Update everything')
       #
-      #   @example Commit all changes with a message
-      #     repo.commit_all('Update everything')
+      # @param message [String] the commit message
       #
-      #   @param message [String] the commit message
+      # @param opts [Hash] additional options forwarded to {#commit}
       #
-      #   @param options [Hash] additional options forwarded to {#commit}
+      # @return [String] git's stdout from the commit
       #
-      #   @return [String] git's stdout from the commit
+      # @raise [ArgumentError] when unsupported options are provided
       #
-      #   @raise [ArgumentError] when unsupported options are provided
-      #
-      #   @raise [Git::FailedError] when git exits with a non-zero exit status
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
-      def commit_all(*, **)
-        commit(*, all: true, **)
+      def commit_all(message, opts = {})
+        commit(message, opts.merge(all: true))
       end
 
       # Create a commit object from a tree SHA without moving HEAD
@@ -116,37 +113,36 @@ module Git
       # Unlike {#commit}, this does not read the index; it directly wraps
       # `git commit-tree`.
       #
-      # @overload commit_tree(tree, **options)
+      # @example Commit a tree with a parent
+      #   repo.commit_tree('deadbeef', message: 'snapshot', parent: 'HEAD')
       #
-      #   @example Commit a tree with a parent
-      #     repo.commit_tree('deadbeef', message: 'snapshot', parent: 'HEAD')
+      # @param tree [String, nil] the tree SHA to commit; defaults to `nil`
       #
-      #   @param tree [String] the tree SHA to commit
+      # @param opts [Hash] options for the commit-tree command
       #
-      #   @param options [Hash] options for the commit-tree command
+      # @option opts [String] :m (nil) the commit message (short form)
       #
-      #   @option options [String] :m (nil) the commit message (short form)
+      # @option opts [String] :message (nil) the commit message (normalized
+      #   to `:m` before passing to the command)
       #
-      #   @option options [String] :message (nil) the commit message (normalized
-      #     to `:m` before passing to the command)
+      # @option opts [String, Array<String>] :p (nil) parent commit SHA(s)
       #
-      #   @option options [String, Array<String>] :p (nil) parent commit SHA(s)
+      # @option opts [String] :parent (nil) a single parent commit SHA
+      #   (normalized to `:p`)
       #
-      #   @option options [String] :parent (nil) a single parent commit SHA
-      #     (normalized to `:p`)
+      # @option opts [Array<String>] :parents (nil) multiple parent commit
+      #   SHAs (normalized to `:p`)
       #
-      #   @option options [Array<String>] :parents (nil) multiple parent commit
-      #     SHAs (normalized to `:p`)
+      # @return [String] the SHA of the newly created commit object
       #
-      #   @return [String] the SHA of the newly created commit object
+      # @raise [ArgumentError] when unsupported options are provided
       #
-      #   @raise [ArgumentError] when unsupported options are provided
-      #
-      #   @raise [Git::FailedError] when git exits with a non-zero exit status
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
-      def commit_tree(tree, **opts)
+      def commit_tree(tree = nil, opts = {}) # rubocop:disable Metrics/AbcSize
         SharedPrivate.assert_valid_opts!(COMMIT_TREE_ALLOWED_OPTS, **opts)
 
+        opts = opts.dup
         opts[:p] = opts.delete(:parents) if opts.key?(:parents)
         opts[:p] = opts.delete(:parent) if opts.key?(:parent)
         opts[:m] = opts.delete(:message) if opts.key?(:message)
@@ -172,19 +168,19 @@ module Git
       #
       # Combines {#write_tree} and {#commit_tree} in a single call.
       #
-      # @overload write_and_commit_tree(**options)
+      # @example Commit the current index as a snapshot
+      #   commit_sha = repo.write_and_commit_tree(message: 'snapshot')
       #
-      #   @example Commit the current index as a snapshot
-      #     commit_sha = repo.write_and_commit_tree(message: 'snapshot')
+      # @param opts [Hash] options forwarded to {#commit_tree}
       #
-      #   @param options [Hash] options forwarded to {#commit_tree}
+      # @return [String] the SHA of the newly created commit object
       #
-      #   @return [String] the SHA of the newly created commit object
+      # @raise [ArgumentError] when unsupported options are provided
       #
-      #   @raise [Git::FailedError] when git exits with a non-zero exit status
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
-      def write_and_commit_tree(**)
-        commit_tree(write_tree, **)
+      def write_and_commit_tree(opts = {})
+        commit_tree(write_tree, opts)
       end
     end
   end