git 4.3.2 → 4.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 317aadaf4169f420466db692337037d90a5a7085dcc84b2b167a9dd5247f369a
-  data.tar.gz: 4308bcfb71982891d57cdec3c75d66c640c96788ac924f246df8c0d76a09fbf1
+  metadata.gz: a24c04e4ade577716464aaf17cdac3f1e1d7e860e60dcd9ed964eb8f0f503b4b
+  data.tar.gz: 7913679e60e68c2f51d9189c150dbf8310244afd71a38a0a7ff88845e58d2d96
 SHA512:
-  metadata.gz: 6e0b4a0da59ed13a76d46c68619ce882cdfaf9512b5ed3b1c0da3c57f5a763804cf866e3cd6ec374191d1cf506ab05953e4ad62878d28c771cb746be11cf2d94
-  data.tar.gz: a3db0a284e6211bfd9684422748b998df7cb8f21d8654f6a4e399879b7670287bc515bccfd7fdd885219fa39c167b738ab2b6ca694801523f5ffdb58d51d82ac
+  metadata.gz: 3e768e8f510d5919d7bacae8095da345e8446546e39e0567aaa2b242700fc4a2045bd6328bd8c5bfa0876375380b679f07aaa33992ebf4828b5298999e033201
+  data.tar.gz: a80276c4a8d613aae86a1adfdaa5f39aabfd3f85e9b4f3dc703612a4fea7afc452f37b9b5d4f3a6d632a2a1e8d12427a5f6f35697ed8daa16e8b2aaebfca5d29

data/.github/workflows/continuous_integration.yml

@@ -53,3 +53,68 @@ jobs:
 
       - name: Test Gem
         run: bundle exec rake test:gem
+
+  # The branch ruleset cannot require the matrix job above directly. A required status
+  # check is matched by name, and `build`'s name is a template -- GitHub only expands it
+  # into "Ruby 3.2 on ubuntu-latest" and friends when it evaluates the matrix. The
+  # job-level `if:` short-circuits before that happens, so a release PR reports one check
+  # named literally "Ruby ${{ matrix.ruby }} on ${{ matrix.operating-system }}" and the
+  # six expanded names never report at all. Required checks that never report block a PR
+  # indefinitely rather than passing, which is what stranded the v5.0.5 release PR on
+  # main and the v4.4.1 release PR here.
+  #
+  # So the ruleset requires this job instead: one stable name, no matrix, no template to
+  # expand. It also decouples the required-check list from the matrix, so adding or
+  # dropping a Ruby version no longer needs a matching ruleset edit.
+  #
+  # Unlike main, this branch has no separate lint job: `rake default` runs RuboCop and
+  # YARD inside every matrix leg, so this one check covers everything CI does here.
+  #
+  # This job carries the same release-PR guard as the matrix above, so that a release PR
+  # reports it as skipped rather than as a success for specs that never ran. Skipping is
+  # safe here and was not safe for `build`: this job's name is a literal string, so the
+  # check run exists and reports a skipped conclusion whether or not the job runs, and
+  # rulesets treat skipped as passing. A matrix job's name does not exist at all until the
+  # matrix is evaluated, which is the whole reason this job exists.
+  #
+  # `always()` is load-bearing and must stay. Without a status check function a job-level
+  # `if:` implies `success()`, so a failing matrix would skip this job -- and a skipped
+  # required check counts as passing, meaning a red build would merge. `always()` forces a
+  # real verdict on every run that is not a release PR. `!cancelled()` is not a substitute:
+  # a cancelled run would then skip the gate, and a skipped conclusion is one rulesets treat
+  # as passing -- so a build that never finished would stop blocking the merge.
+  #
+  # The case below accepts `success` only. `build` and this job now carry the same release-PR
+  # guard, so this job runs exactly when `build` ran; a `skipped` result would mean the two
+  # guards have drifted apart, and failing closed on it turns that into a loud failure rather
+  # than a silent pass.
+  #
+  # Note that a matrix leg marked `experimental: Yes` carries continue-on-error, and a
+  # continue-on-error failure does not fail the job as a whole -- so it does not fail this
+  # gate either. That is what `experimental` is for; no leg currently sets it.
+  build-complete:
+    name: All Specs Passed
+
+    needs: [build]
+
+    # Report a verdict on every non-release PR regardless of the matrix result, and skip
+    # on release PRs, where the matrix was never meant to run.
+    if: >-
+      always() &&
+      (github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' && !startsWith(github.event.pull_request.head.ref, 'release-please--')))
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check the result of the build job
+        run: |
+          case "${{ needs.build.result }}" in
+            success)
+              echo "build: ${{ needs.build.result }}"
+              ;;
+            *)
+              echo "::error::build: ${{ needs.build.result }}"
+              exit 1
+              ;;
+          esac

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.3.2"
+  ".": "4.4.1"
 }

data/CHANGELOG.md

@@ -5,6 +5,32 @@
 
 # Change Log
 
+## [4.4.1](https://github.com/ruby-git/ruby-git/compare/v4.4.0...v4.4.1) (2026-08-09)
+
+
+### Bug Fixes
+
+* Pin LC_ALL to a locale that exists on the host platform ([690360e](https://github.com/ruby-git/ruby-git/commit/690360e386bac1dafb7b5bd0adbf10072e834f69)), closes [#1669](https://github.com/ruby-git/ruby-git/issues/1669)
+
+
+### Other Changes
+
+* Add a matrix-free All Specs Passed gate to 4.x ([5352d6d](https://github.com/ruby-git/ruby-git/commit/5352d6d4edfcb52c544139e265fb3636bc1937b7)), closes [#1675](https://github.com/ruby-git/ruby-git/issues/1675)
+* Skip the All Specs Passed gate on release PRs ([52473b2](https://github.com/ruby-git/ruby-git/commit/52473b21a733499eb274a7b03d53f1a0efbf5c86)), closes [#1675](https://github.com/ruby-git/ruby-git/issues/1675)
+
+## [4.4.0](https://github.com/ruby-git/ruby-git/compare/v4.3.2...v4.4.0) (2026-07-11)
+
+
+### Features
+
+* Allow deprecation behavior env var ([fd622be](https://github.com/ruby-git/ruby-git/commit/fd622bea6513d78f2dbed8dc19c110be80d07ec8))
+* Warn on first direct access to Git::Lib constant ([52059c6](https://github.com/ruby-git/ruby-git/commit/52059c63d5c23b4d80025b95332e946aba942f0c))
+
+
+### Other Changes
+
+* Improve YARD documentation for Git::Branch ([#1277](https://github.com/ruby-git/ruby-git/issues/1277)) ([0769bf9](https://github.com/ruby-git/ruby-git/commit/0769bf91a21ecb24d48a31439de073b689bc62b6))
+
 ## [4.3.2](https://github.com/ruby-git/ruby-git/compare/v4.3.1...v4.3.2) (2026-03-31)
 
 

data/README.md

@@ -589,6 +589,18 @@ You can silence deprecation warnings by adding this line to your source code:
 Git::Deprecation.behavior = :silence
 ```
 
+Or by setting this environment variable before loading the gem:
+
+```sh
+GIT_DEPRECATION_BEHAVIOR=silence
+```
+
+Accepted environment variable values are the behavior names supported by your
+installed ActiveSupport version.
+
+If `GIT_DEPRECATION_BEHAVIOR` is set to an unsupported value, loading the gem
+raises `ArgumentError` with the accepted behavior names.
+
 See [the Active Support Deprecation
 documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
 for more details.

data/lib/git/base.rb

@@ -23,14 +23,14 @@ module Git
     def self.clone(repository_url, directory, options = {})
       lib_options = {}
       lib_options[:git_ssh] = options[:git_ssh] if options.key?(:git_ssh)
-      new_options = Git::Lib.new(lib_options, options[:log]).clone(repository_url, directory, options)
+      new_options = LibImpl.new(lib_options, options[:log]).clone(repository_url, directory, options)
       normalize_paths(new_options, bare: options[:bare] || options[:mirror])
       new(new_options)
     end
 
     # (see Git.default_branch)
     def self.repository_default_branch(repository, options = {})
-      Git::Lib.new(nil, options[:log]).repository_default_branch(repository)
+      LibImpl.new(nil, options[:log]).repository_default_branch(repository)
     end
 
     # Returns (and initialize if needed) a Git::Config instance
@@ -90,7 +90,7 @@ module Git
       #   repository you have a Git::Base instance for.  This would not
       #   change the existing interface (other than adding to it).
       #
-      Git::Lib.new(options).init(init_options)
+      LibImpl.new(options).init(init_options)
 
       new(options)
     end
@@ -335,7 +335,7 @@ module Git
     # actual 'git' forked system calls.  At some point I hope to replace the Git::Lib
     # class with one that uses native methods or libgit C bindings
     def lib
-      @lib ||= Git::Lib.new(self, @logger)
+      @lib ||= LibImpl.new(self, @logger)
     end
 
     # Returns the per-instance git_ssh configuration value.

data/lib/git/branch.rb

@@ -4,9 +4,81 @@ require 'git/path'
 
 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
+    #   git.branch('main').full                  #=> 'main'
+    #   git.branch('remotes/origin/main').full   #=> 'remotes/origin/main'
+    #
+    # @return [String] the full refname
+    #
+    attr_accessor :full
+
+    # 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
+    #   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 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'`).
+    #
+    # @example
+    #   git.branch('main').name                       #=> 'main'
+    #   git.branch('remotes/origin/main').name        #=> 'main'
+    #   git.remote('origin').branch('main').name      #=> 'origin/main'
+    #
+    # @return [String] the branch name
+    #
+    attr_accessor :name
 
+    # Initialize a new Branch object
+    #
+    # @api private
+    #
+    # @note Use {Git::Base#branch} or {Git::Base#branches} instead of constructing directly
+    #
+    # @param base [Git::Base] the git repository
+    #
+    # @param name [String] the full or short branch name
+    #
     def initialize(base, name)
       @full = name
       @base = base
@@ -15,29 +87,102 @@ module Git
       @remote, @name = parse_name(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
     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)
     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`),
+    # {#full} is a ref such as `'remotes/origin/main'`. Checking out a
+    # remote-tracking ref places the repository in a **detached HEAD** state.
+    #
+    # @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)
     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)
     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
       checkout
@@ -49,22 +194,112 @@ module Git
       @base.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 [String, nil] git's stdout from branch creation (typically empty),
+    #   or `nil` if an error was rescued
+    #
     def create
       check_if_create
     end
 
+    # 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.
+    #
+    # @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
+    #
     def delete
       @base.lib.branch_delete(@name)
     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
     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?
     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 during
+    #   the merge, checkout, commit, or reset operations
+    #
     def merge(branch = nil, message = nil)
       if branch
         in_branch do
@@ -78,6 +313,26 @@ module Git
       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
+    #   `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 [String] the stdout output from `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)
@@ -86,17 +341,38 @@ module Git
       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 +383,25 @@ module Git
 
     private
 
-    # Given a full branch name return an Array containing the remote and branch names.
+    # 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.
     #
-    # 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 '/').
+    # @example Local branches
+    #   parse_name('master')            #=> [nil, 'master']
+    #   parse_name('origin/master')     #=> [nil, 'origin/master']
     #
-    # Example:
-    #   # local branches
-    #   parse_name('master') #=> [nil, 'master']
-    #   parse_name('origin/master') #=> [nil, 'origin/master']
-    #   parse_name('origin/master/v2') #=> [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']
     #
-    #   # 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 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
     #
-    # 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,6 +410,10 @@ module Git
       [remote, branch_name]
     end
 
+    # 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
+    #
     def check_if_create
       @base.lib.branch_new(@name)
     rescue StandardError

data/lib/git/lib.rb

@@ -2075,7 +2075,7 @@ module Git
     # @example Unsetting an environment variable (used by worktree_command_line)
     #   env_overrides('GIT_INDEX_FILE' => nil)
     #   # => { 'GIT_DIR' => '/path/to/.git', 'GIT_WORK_TREE' => '/path/to/worktree',
-    #   #      'GIT_INDEX_FILE' => nil, 'GIT_SSH' => <git_ssh_value>, 'LC_ALL' => 'en_US.UTF-8' }
+    #   #      'GIT_INDEX_FILE' => nil, 'GIT_SSH' => <git_ssh_value>, 'LC_ALL' => <pinned_locale> }
     #   # When passed to Process.spawn, GIT_INDEX_FILE will be unset in the environment
     #
     # @see https://ruby-doc.org/core/Process.html#method-c-spawn Process.spawn
@@ -2088,10 +2088,67 @@ module Git
         'GIT_WORK_TREE' => @git_work_dir,
         'GIT_INDEX_FILE' => @git_index_file,
         'GIT_SSH' => resolved_git_ssh,
-        'LC_ALL' => 'en_US.UTF-8'
+        # Pin the locale so git's behavior does not depend on the user's environment.
+        # Added for issue #753, where a German user's `git branch` output
+        # ("* (HEAD losgelöst bei origin/25.1)") broke branch parsing.
+        #
+        # The pin has two halves, and both are load-bearing here:
+        #
+        # - Messages: keeps git's human-readable text in English. `BRANCH_LINE_REGEXP`
+        #   matches the literal English strings "(HEAD detached at ...)" and
+        #   "(not a branch)" in `git branch -a` output, which is the exact issue #753
+        #   failure mode.
+        # - Ctype: makes git's regex engine match *characters* rather than *bytes*.
+        #   Under a C ctype, `grep` and `log --grep` silently return wrong answers —
+        #   with exit status zero — for any pattern whose metacharacters span
+        #   non-ASCII text.
+        #
+        # So do not "simplify" this to `C`: that yields English messages and a broken
+        # ctype, which is the worst of both. A pinned locale the host does not have
+        # degrades to that same C ctype, which is why each branch below has to name a
+        # locale that actually exists on the platform it applies to:
+        #
+        # - Non-Darwin: `C.UTF-8`. Stock Debian, Ubuntu, and RHEL images generate no
+        #   `en_US.UTF-8`, so pinning it there produced exactly the silent breakage
+        #   above. (musl ignores the locale name for ctype, so Alpine is UTF-8 either
+        #   way.)
+        # - Darwin: `en_US.UTF-8`, which every macOS release ships. `C.UTF-8` did not
+        #   arrive until macOS 15, so macOS 11–14 — including Intel Macs that are
+        #   hardware-capped below 15 — would break under it. Delete this branch once
+        #   macOS 14 and earlier are out of support.
+        #
+        # Windows takes the non-Darwin branch, where the value makes no difference:
+        # Git for Windows folds case and runs PCRE in UTF mode under every value, and
+        # matches bytes for `.` and POSIX classes under every value — measured on git
+        # 2.55.0 against `en_US.UTF-8`, `C.UTF-8`, `C`, and no pin at all.
+        #
+        # RHEL 7 (glibc 2.17) has neither locale and gets a C ctype whatever is pinned.
+        # It is EOL, and there is deliberately no public override for this value.
+        'LC_ALL' => darwin_platform? ? 'en_US.UTF-8' : 'C.UTF-8'
       }.merge(additional_overrides)
     end
 
+    # Whether this process is running on macOS
+    #
+    # Checks `RUBY_DESCRIPTION` as well as `RUBY_PLATFORM` because JRuby reports
+    # `RUBY_PLATFORM` as `"java"` on every host and records the real platform only in
+    # `RUBY_DESCRIPTION` (as, for example, `"... [arm64-darwin]"`). Testing
+    # `RUBY_PLATFORM` alone would put JRuby on macOS onto the non-Darwin branch, which is
+    # the one platform pairing that branch must not be given. This is the same detection
+    # the test suite uses for Windows, and for the same reason.
+    #
+    # Test the platform plainly rather than sniffing the Darwin version: `RUBY_PLATFORM`
+    # records the version Ruby was *built* against, so a Ruby built on macOS 14 still
+    # reports `darwin23` when run on macOS 15.
+    #
+    # @return [Boolean] true if this process is running on macOS
+    #
+    # @api private
+    #
+    def darwin_platform?
+      RUBY_PLATFORM.include?('darwin') || RUBY_DESCRIPTION.include?('darwin')
+    end
+
     # Resolve the git_ssh value to use for this instance
     #
     # @return [String, nil] the resolved git_ssh value

data/lib/git/status.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# These would be required by the main `git.rb` file
-
 module Git
   # The Status class gets the status of a git repository. It identifies which
   # files have been modified, added, or deleted, including untracked files.

data/lib/git/version.rb

@@ -3,5 +3,5 @@
 module Git
   # The current gem version
   # @return [String] the current gem version.
-  VERSION = '4.3.2'
+  VERSION = '4.4.1'
 end

data/lib/git.rb

@@ -1,10 +1,29 @@
 # frozen_string_literal: true
 
-require 'active_support'
 require 'active_support/deprecation'
 
+# Define Git::Deprecation before requiring the rest of the library to ensure that
+# any deprecation warnings emitted during the loading of the library are properly
+# configured according to the GIT_DEPRECATION_BEHAVIOR environment variable.
+#
 module Git
+  # The deprecation instance used to emit deprecation warnings for the Git gem
+  #
+  # @api public
   Deprecation = ActiveSupport::Deprecation.new('5.0.0', 'Git')
+
+  if (behavior = ENV.fetch('GIT_DEPRECATION_BEHAVIOR', nil))
+    behavior = behavior.strip
+    allowed_behaviors = ActiveSupport::Deprecation::DEFAULT_BEHAVIORS.keys.map(&:to_s)
+
+    unless allowed_behaviors.include?(behavior)
+      raise ArgumentError,
+            "Invalid GIT_DEPRECATION_BEHAVIOR=#{behavior.inspect}; " \
+            "expected one of: #{allowed_behaviors.join(', ')}"
+    end
+
+    Deprecation.behavior = behavior.to_sym
+  end
 end
 
 require 'git/author'
@@ -44,12 +63,28 @@ require 'git/worktrees'
 # @author Scott Chacon (mailto:schacon@gmail.com)
 #
 module Git # rubocop:disable Style/OneClassPerFile
+  # Internal alias for Git::Lib, used by the gem itself after the public constant
+  # is deprecated. Code outside the gem should not reference this constant.
+  # @api private
+  LibImpl = remove_const(:Lib)
+
+  # @api private
+  def self.const_missing(name)
+    return super unless name == :Lib
+
+    Git::Deprecation.warn(
+      'Git::Lib is deprecated and will be removed in version 5.x. ' \
+      'Use the #lib accessor on the object returned by Git.init, Git.open, or Git.clone instead.'
+    )
+    const_set(:Lib, LibImpl)
+  end
+
   # g.config('user.name', 'Scott Chacon') # sets value
   # g.config('user.email', 'email@email.com')  # sets value
   # g.config('user.name')  # returns 'Scott Chacon'
   # g.config # returns whole config hash
   def config(name = nil, value = nil)
-    lib = Git::Lib.new
+    lib = LibImpl.new
     if name && value
       # set value
       lib.config_set(name, value)
@@ -287,7 +322,7 @@ module Git # rubocop:disable Style/OneClassPerFile
   # g.config('user.name')  # returns 'Scott Chacon'
   # g.config # returns whole config hash
   def self.global_config(name = nil, value = nil)
-    lib = Git::Lib.new(nil, nil)
+    lib = LibImpl.new(nil, nil)
     if name && value
       # set value
       lib.global_config_set(name, value)
@@ -369,7 +404,7 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @param [String|NilClass] location the target repository location or nil for '.'
   # @return [{String=>Hash}] the available references of the target repo.
   def self.ls_remote(location = nil, options = {})
-    Git::Lib.new.ls_remote(location, options)
+    LibImpl.new.ls_remote(location, options)
   end
 
   # Open a an existing Git working directory

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 4.3.2
+  version: 4.4.1
 platform: ruby
 authors:
 - Scott Chacon and others
@@ -310,8 +310,8 @@ licenses:
 metadata:
   homepage_uri: http://github.com/ruby-git/ruby-git
   source_code_uri: http://github.com/ruby-git/ruby-git
-  changelog_uri: https://rubydoc.info/gems/git/4.3.2/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/4.3.2
+  changelog_uri: https://rubydoc.info/gems/git/4.4.1/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/4.4.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -328,7 +328,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - git 2.28.0 or greater
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: An API to create, read, and manipulate Git repositories
 test_files: []