feat: allow deprecation behavior env var

Add support for a GIT_DEPRECATION_BEHAVIOR environment variable that
configures the ActiveSupport deprecation behavior when the gem is
loaded. Any behavior name accepted by the installed ActiveSupport
version is valid (e.g. 'silence', 'log', 'raise', 'report').

If the variable is set to an unrecognised value, loading the gem raises
ArgumentError with the list of accepted values.

Also marks Git::Deprecation as @api public since users need to
reference it to configure deprecation handling in code.

Author: jcouball

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.

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'

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.

tests/units/test_deprecations.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'open3'
+require 'rbconfig'
 require_relative '../test_helper'
 
 # Consolidated deprecation tests to ensure all deprecated entry points emit
@@ -214,3 +216,36 @@ def test_repository_path_accessor_deprecation
     @git.repo.path
   end
 end
+
+# Tests for the GIT_DEPRECATION_BEHAVIOR environment variable
+class TestGitDeprecationBehaviorEnvVar < Test::Unit::TestCase
+  GEM_ROOT = File.expand_path('../..', __dir__)
+  RUBY_EXE = RbConfig.ruby
+
+  DEPRECATION_SCRIPT = <<~RUBY
+    require 'git'
+    Git::Deprecation.warn('deprecated message')
+  RUBY
+
+  LOAD_SCRIPT = "require 'git'"
+
+  def run_with_env(env_vars, script)
+    Open3.capture3(env_vars, RUBY_EXE, '-Ilib', '-e', script, chdir: GEM_ROOT)
+  end
+
+  def test_silence_behavior_suppresses_warnings
+    _out, err, status = run_with_env({ 'GIT_DEPRECATION_BEHAVIOR' => 'silence' }, DEPRECATION_SCRIPT)
+
+    assert status.success?, "Script failed unexpectedly:\n#{err}"
+    assert_no_match(/DEPRECATION WARNING: deprecated message/, err)
+  end
+
+  def test_invalid_behavior_raises_argument_error
+    allowed_behaviors = ActiveSupport::Deprecation::DEFAULT_BEHAVIORS.keys.map(&:to_s)
+    _out, err, status = run_with_env({ 'GIT_DEPRECATION_BEHAVIOR' => 'silent' }, LOAD_SCRIPT)
+
+    assert !status.success?, 'Expected script to fail but it succeeded'
+    assert_match(/Invalid GIT_DEPRECATION_BEHAVIOR="silent"/, err)
+    assert_match(/expected one of: #{Regexp.escape(allowed_behaviors.join(', '))}/, err)
+  end
+end