git 5.0.0.beta.5 → 5.0.0

data/lib/git/branch_info.rb

@@ -9,54 +9,60 @@ module Git
   #
   # @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 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 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 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
+  # @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/)?remotes/(?<remote_name>[^/]+)/)? # optional 'refs?/remotes/<remote_name>/'
-    (?<branch_name>.+)                   # branch name (everything else)
-    \z                              # end of string
+    \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 Creating from git branch output
+  # @example Local branch with upstream tracking
   #   info = Git::BranchInfo.new(
-  #     refname: 'main',
+  #     refname: 'refs/heads/main',
   #     target_oid: 'abc123def456789012345678901234567890abcd',
   #     current: true,
-  #     worktree: false,
+  #     worktree_path: nil,
   #     symref: nil,
-  #     upstream: nil
+  #     upstream: 'refs/remotes/origin/main'
   #   )
   #   info.current?     #=> true
   #   info.remote?      #=> false
   #   info.short_name   #=> 'main'
+  #   info.upstream     #=> 'refs/remotes/origin/main'
   #
-  # @example Remote branch
+  # @example Remote-tracking branch
   #   info = Git::BranchInfo.new(
-  #     refname: 'remotes/origin/main',
+  #     refname: 'refs/remotes/origin/main',
   #     target_oid: 'abc123def456789012345678901234567890abcd',
   #     current: false,
-  #     worktree: false,
+  #     worktree_path: nil,
   #     symref: nil,
   #     upstream: nil
   #   )
@@ -64,25 +70,6 @@ module Git
   #   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
@@ -93,13 +80,24 @@ module Git
   #
   #   The full reference name of the branch
   #
-  #   @return [String] the branch refname (e.g., 'main', 'remotes/origin/main')
+  #   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
+  #   The commit object ID (SHA) that this branch points to (aka HEAD)
   #
-  #   @return [String, nil] the full 40-character object ID, or nil if unavailable
+  #   @return [String, nil] the full 40-character object ID, or nil if branch is
+  #   unborn (no commits yet)
   #
   # @!attribute [r] current
   #
@@ -107,11 +105,28 @@ module Git
   #
   #   @return [Boolean] true if this is the current branch
   #
-  # @!attribute [r] worktree
+  #   @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
   #
-  #   Whether this branch is checked out in another linked worktree
+  #   The absolute path of the *other* linked worktree this branch is checked
+  #   out in, or nil.
   #
-  #   @return [Boolean] true if checked out in a different worktree
+  #   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
   #
@@ -121,27 +136,94 @@ module Git
   #
   # @!attribute [r] upstream
   #
-  #   The configured upstream/tracking branch
+  #   The configured upstream/tracking branch refname as reported by git
   #
-  #   @return [Git::BranchInfo, nil] the upstream branch info, or nil if no upstream is configured
+  #   @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., 'origin/main') have upstream: nil
+  #   @note Remote-tracking branches (e.g., `'refs/remotes/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
+  #   @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, :target_oid, :current, :worktree, :symref, :upstream) do
+  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 worktree
-    def worktree? = worktree
+    # @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?
@@ -149,30 +231,7 @@ module Git
     # @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

@@ -30,7 +30,7 @@ module Git
 
       @base = base
 
-      branch_repository.branches_all.each do |branch_info|
+      branch_repository.branch_list.each do |branch_info|
         branch = Git::Branch.new(base, branch_info)
 
         @branches[branch_info.refname] = branch

data/lib/git/log.rb

@@ -222,7 +222,8 @@ module Git
     # @deprecated Use {#execute} and call `each` on the result.
     def each(&)
       Git::Deprecation.warn(
-        'Calling Git::Log#each is deprecated. Call #execute and then #each on the result object.'
+        'Calling Git::Log#each is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #each on the result object.'
       )
       run_log_if_dirty
       @commits.each(&)
@@ -231,7 +232,8 @@ module Git
     # @deprecated Use {#execute} and call `size` on the result.
     def size
       Git::Deprecation.warn(
-        'Calling Git::Log#size is deprecated. Call #execute and then #size on the result object.'
+        'Calling Git::Log#size is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #size on the result object.'
       )
       run_log_if_dirty
       @commits.size
@@ -240,7 +242,8 @@ module Git
     # @deprecated Use {#execute} and call `to_s` on the result.
     def to_s
       Git::Deprecation.warn(
-        'Calling Git::Log#to_s is deprecated. Call #execute and then #to_s on the result object.'
+        'Calling Git::Log#to_s is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #to_s on the result object.'
       )
       run_log_if_dirty
       @commits.join("\n")
@@ -249,7 +252,8 @@ module Git
     # @deprecated Use {#execute} and call the method on the result.
     def first
       Git::Deprecation.warn(
-        'Calling Git::Log#first is deprecated. Call #execute and then #first on the result object.'
+        'Calling Git::Log#first is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #first on the result object.'
       )
       run_log_if_dirty
       @commits.first
@@ -258,7 +262,8 @@ module Git
     # @deprecated Use {#execute} and call the method on the result.
     def last
       Git::Deprecation.warn(
-        'Calling Git::Log#last is deprecated. Call #execute and then #last on the result object.'
+        'Calling Git::Log#last is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #last on the result object.'
       )
       run_log_if_dirty
       @commits.last
@@ -273,7 +278,8 @@ module Git
     #
     def [](index)
       Git::Deprecation.warn(
-        'Calling Git::Log#[] is deprecated. Call #execute and then #[] on the result object.'
+        'Calling Git::Log#[] is deprecated and will be removed in v6.0.0. ' \
+        'Call #execute and then #[] on the result object.'
       )
       run_log_if_dirty
       @commits[index]

data/lib/git/object.rb

@@ -485,7 +485,7 @@ module Git
       #
       def set_commit(data) # rubocop:disable Naming/AccessorMethodName
         Git::Deprecation.warn(
-          'Git::Object::Commit#set_commit is deprecated and will be removed in a future version. ' \
+          'Git::Object::Commit#set_commit is deprecated and will be removed in v6.0.0. ' \
           'Use #from_data instead.'
         )
         from_data(data)
@@ -660,7 +660,10 @@ module Git
     # @deprecated use `Git::Object::Tag.new` instead
     #
     private_class_method def self.new_tag(base, objectish)
-      Git::Deprecation.warn('Git::Object.new with is_tag argument is deprecated. Use Git::Object::Tag.new instead.')
+      Git::Deprecation.warn(
+        'Git::Object.new with is_tag argument is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Object::Tag.new instead.'
+      )
       Git::Object::Tag.new(base, objectish)
     end
 

data/lib/git/parsers/branch.rb

@@ -38,18 +38,21 @@ module Git
     module Branch
       # Format string for git branch --format
       #
-      # Fields (pipe-delimited):
-      # 1. refname - full ref name (e.g., refs/heads/main, refs/remotes/origin/main)
-      # 2. objectname - full SHA of the commit the branch points to
-      # 3. HEAD - '*' if current branch, empty otherwise
+      # Fields (null-delimited):
+      # 1. refname      - full ref name (e.g., refs/heads/main, refs/remotes/origin/main)
+      # 2. objectname  - full SHA of the commit the branch points to
+      # 3. HEAD         - '*' if current branch, empty otherwise
       # 4. worktreepath - path if checked out in another worktree, empty otherwise
-      # 5. symref - target ref if symbolic reference, empty otherwise
-      # 6. upstream - full upstream ref (e.g., refs/remotes/origin/main), empty if none
+      # 5. symref       - target ref if symbolic reference, empty otherwise
+      # 6. upstream     - full upstream ref (e.g., refs/remotes/origin/main), empty if none
       #
-      FORMAT_STRING = '%(refname)|%(objectname)|%(HEAD)|%(worktreepath)|%(symref)|%(upstream)'
+      # Null bytes (%00) are used as field delimiters so that worktree paths
+      # containing special characters (including '|') parse correctly.
+      #
+      FORMAT_STRING = '%(refname)%00%(objectname)%00%(HEAD)%00%(worktreepath)%00%(symref)%00%(upstream)'
 
       # Delimiter used in format output
-      FIELD_DELIMITER = '|'
+      FIELD_DELIMITER = "\0"
 
       # Regex to parse successful deletion lines from stdout
       # Matches: Deleted branch branchname (was abc123).
@@ -65,52 +68,84 @@ module Git
 
       # Parse git branch --list output into BranchInfo objects
       #
-      # @example
-      #   Git::Parsers::Branch.parse_list("refs/heads/main|abc1234|*|||\nrefs/heads/feature|def5678||||\n")
-      #   # => [#<data Git::BranchInfo refname="main", ...>, #<data Git::BranchInfo refname="feature", ...>]
+      # @example Parse NUL-delimited branch list output
+      #   Git::Parsers::Branch.parse_list(
+      #     "refs/heads/main\0abc1234\0*\0\0\0\n" \
+      #     "refs/heads/feature\0def5678\0\0\0\0\n"
+      #   )
+      #   # => [#<data Git::BranchInfo refname="refs/heads/main", ...>,
+      #   #     #<data Git::BranchInfo refname="refs/heads/feature", ...>]
       #
       # @param stdout [String] output from git branch --list --format=...
       #
+      # @param remote_names [Array<String>] configured remote names used to resolve
+      #   remote-tracking refs with slash-containing remote names
+      #
       # @return [Array<Git::BranchInfo>] parsed branch information
       #
-      def parse_list(stdout)
-        stdout.split("\n").filter_map { |line| parse_branch_line(line) }
+      def parse_list(stdout, remote_names: [])
+        stdout.split("\n").filter_map { |line| parse_branch_line(line, remote_names: remote_names) }
       end
 
       # Parse a single formatted branch line
       #
-      # @param line [String] the line to parse (pipe-delimited fields)
+      # @param line [String] the line to parse (NUL-delimited fields)
+      #
+      # @param remote_names [Array<String>] configured remote names used to resolve
+      #   remote-tracking refs with slash-containing remote names
       #
       # @return [Git::BranchInfo, nil] branch info object, or nil if line should be skipped
       #
-      def parse_branch_line(line)
+      def parse_branch_line(line, remote_names: [])
         fields = line.split(FIELD_DELIMITER, 6)
 
         return nil if non_branch_entry?(fields[0])
 
-        build_branch_info(fields)
+        build_branch_info(fields, remote_names: remote_names)
       end
 
       # Build a BranchInfo from parsed fields
       #
-      # @param fields [Array<String>] the parsed fields: [refname, objectname, head, worktreepath, symref, upstream]
+      # @param fields [Array<String>] the parsed fields:
+      #   [refname, objectname, head, worktreepath, symref, upstream]
+      #
+      # @param remote_names [Array<String>] configured remote names used to resolve
+      #   remote-tracking refs with slash-containing remote names
       #
       # @return [Git::BranchInfo] the branch info object
       #
-      def build_branch_info(fields)
+      def build_branch_info(fields, remote_names: [])
         raw_refname, objectname, head, worktreepath, symref, upstream = fields
-        current = head == '*'
-
         Git::BranchInfo.new(
-          refname: normalize_refname(raw_refname),
+          refname: raw_refname,
           target_oid: presence(objectname),
-          current: current,
-          worktree: in_other_worktree?(worktreepath, current),
+          current: head == '*',
+          worktree_path: head == '*' ? nil : presence(worktreepath),
           symref: presence(symref),
-          upstream: build_upstream_info(upstream)
+          upstream: build_upstream_info(upstream),
+          remote_name: resolve_remote_name(raw_refname, remote_names)
         )
       end
 
+      # Resolve a remote-tracking refname to a configured remote name
+      #
+      # @param refname [String] the branch refname to inspect
+      #
+      # @param remote_names [Array<String>] configured remote names
+      #
+      # @return [String, nil] the resolved remote name, or nil for local branches
+      #
+      def resolve_remote_name(refname, remote_names)
+        remote_path = refname[%r{\A(?:refs/)?remotes/(.+)\z}, 1]
+        return nil if remote_path.nil?
+
+        configured_remote_name = remote_names
+                                 .select { |remote_name| remote_path.start_with?("#{remote_name}/") }
+                                 .max_by(&:length)
+
+        configured_remote_name || Git::BranchInfo.fallback_remote_name(refname)
+      end
+
       # Check if the refname represents a detached HEAD state or non-branch entry
       #
       # Git outputs special entries for detached HEAD and non-branch states:
@@ -125,53 +160,16 @@ module Git
         refname.match?(/^\(HEAD detached/) || refname.match?(/^\(not a branch\)/)
       end
 
-      # Normalize a full refname to the expected format
-      #
-      # Converts:
-      # - refs/heads/main -> main
-      # - refs/remotes/origin/main -> remotes/origin/main
-      #
-      # @param refname [String] the full refname from git
-      #
-      # @return [String] normalized refname
-      #
-      def normalize_refname(refname)
-        refname.sub(%r{^refs/heads/}, '').sub(%r{^refs/}, '')
-      end
-
-      # Check if the branch is checked out in another worktree
-      #
-      # worktree is true when the branch is checked out in ANOTHER worktree
-      # (worktreepath is non-empty AND it's not the current branch)
-      #
-      # @param worktreepath [String, nil] the worktree path from git output
-      #
-      # @param current [Boolean] whether this is the current branch
-      #
-      # @return [Boolean] true if checked out in another worktree
-      #
-      def in_other_worktree?(worktreepath, current)
-        has_worktree = !worktreepath.nil? && !worktreepath.empty?
-        has_worktree && !current
-      end
-
-      # Build upstream BranchInfo from upstream refname
+      # Return the raw upstream refname string, or nil if empty
       #
       # @param upstream_ref [String, nil] the upstream ref (e.g., 'refs/remotes/origin/main')
       #
-      # @return [Git::BranchInfo, nil] upstream branch info or nil
+      # @return [String, nil] the raw upstream refname, or nil
       #
       def build_upstream_info(upstream_ref)
         return nil if upstream_ref.nil? || upstream_ref.empty?
 
-        Git::BranchInfo.new(
-          refname: normalize_refname(upstream_ref),
-          target_oid: nil, # We don't have upstream's OID from this format
-          current: false,
-          worktree: false,
-          symref: nil,
-          upstream: nil # Upstream branches don't have their own upstream in this context
-        )
+        upstream_ref
       end
 
       # Return value if non-empty, nil otherwise