git 4.1.0 → 4.3.0

data/README.md

@@ -7,21 +7,30 @@
 
 [![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git)
 [![Documentation](https://img.shields.io/badge/Documentation-Latest-green)](https://rubydoc.info/gems/git/)
-[![Change Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md)
-[![Build Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=main)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
+[![Change
+Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md)
+[![Build
+Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=main)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
+[![Conventional
+Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
+[![AI Policy](https://img.shields.io/badge/AI%20Policy-Required-blue)](AI_POLICY.md)
 
 - [Summary](#summary)
 - [Install](#install)
-- [Major Objects](#major-objects)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+  - [Configuration](#configuration)
+  - [Read Operations](#read-operations)
+  - [Write Operations](#write-operations)
+  - [Index and Tree Operations](#index-and-tree-operations)
 - [Errors Raised By This Gem](#errors-raised-by-this-gem)
 - [Specifying And Handling Timeouts](#specifying-and-handling-timeouts)
 - [Deprecations](#deprecations)
-- [Examples](#examples)
-- [Ruby version support policy](#ruby-version-support-policy)
-- [Git version support policy](#git-version-support-policy)
-- [License](#license)
+- [Project Policies](#project-policies)
+  - [Ruby Version Support Policy](#ruby-version-support-policy)
+  - [Git Version Support Policy](#git-version-support-policy)
 - [📢 Project Announcements 📢](#-project-announcements-)
+  - [2026-01-07: AI Policy Introduced](#2026-01-07-ai-policy-introduced)
   - [2025-07-09: Architectural Redesign](#2025-07-09-architectural-redesign)
   - [2025-07-07: We Now Use RuboCop](#2025-07-07-we-now-use-rubocop)
   - [2025-06-06: Default Branch Rename](#2025-06-06-default-branch-rename)
@@ -34,11 +43,15 @@ command line.
 
 Get started by obtaining a repository object by:
 
-- opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
-- initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
-- cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
+- opening an existing working copy with
+  [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
+- initializing a new repository with
+  [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
+- cloning a repository with
+  [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
 
-Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
+Methods that can be called on a repository object are documented in
+[Git::Base](https://rubydoc.info/gems/git/Git/Base)
 
 ## Install
 
@@ -66,169 +79,92 @@ to install version 1.x:
 gem install git --version "~> 1.19"
 ```
 
-## Major Objects
-
-**Git::Base** - The object returned from a `Git.open` or `Git.clone`. Most major actions are called from this object.
-
-**Git::Object** - The base object for your tree, blob and commit objects, returned from `@git.gtree` or `@git.object` calls.  the `Git::AbstractObject` will have most of the calls in common for all those objects.
+## Quick Start
 
-**Git::Diff** - returns from a `@git.diff` command.  It is an Enumerable that returns `Git::Diff:DiffFile` objects from which you can get per file patches and insertion/deletion statistics.  You can also get total statistics from the Git::Diff object directly.
+All functionality for this gem starts with the top-level
+[`Git`](https://rubydoc.info/gems/git/Git) module. This module can be used to run
+non-repo scoped `git` commands such as `config`.
 
-**Git::Status** - returns from a `@git.status` command.  It is an Enumerable that returns
-`Git:Status::StatusFile` objects for each object in git, which includes files in the working
-directory, in the index and in the repository.  Similar to running 'git status' on the command line to determine untracked and changed files.
+The `Git` module also has factory methods such as `open`, `clone`, and `init` which
+return a [`Git::Base`](https://rubydoc.info/gems/git/Git/Base) object. The
+`Git::Base` object is used to run repo-specific `git` commands such as `add`,
+`commit`, `push`, and `log`.
 
-**Git::Branches** - Enumerable object that holds `Git::Branch objects`.  You can call .local or .remote on it to filter to just your local or remote branches.
-
-**Git::Remote**- A reference to a remote repository that is tracked by this repository.
-
-**Git::Log** - An Enumerable object that references all the `Git::Object::Commit`
-objects that encompass your log query, which can be constructed through methods on
-the `Git::Log object`, like:
+Clone, read status, and log:
 
 ```ruby
-git.log
-  .max_count(:all)
-  .object('README.md')
-  .since('10 years ago')
-  .between('v1.0.7', 'HEAD')
-  .map { |commit| commit.sha }
-```
-
-A maximum of 30 commits are returned if `max_count` is not called. To get all commits
-that match the log query, call `max_count(:all)`.
-
-Note that `git.log.all` adds the `--all` option to the underlying `git log` command.
-This asks for the logs of all refs (basically all commits reachable by HEAD,
-branches, and tags). This does not control the maximum number of commits returned. To
-control how many commits are returned, you should call `max_count`.
-
-**Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
-
-## Errors Raised By This Gem
-
-The git gem will only raise an `ArgumentError` or an error that is a subclass of
-`Git::Error`. It does not explicitly raise any other types of errors.
-
-It is recommended to rescue `Git::Error` to catch any runtime error raised by
-this gem unless you need more specific error handling.
+require 'git'
 
-```ruby
-begin
-  # some git operation
-rescue Git::Error => e
-  puts "An error occurred: #{e.message}"
-end
+repo = Git.clone('https://github.com/ruby-git/ruby-git.git', 'ruby-git')
+repo.status.changed.each { |f| puts "changed: #{f.path}" }
+repo.log(5).each { |c| puts c.message }
 ```
 
-See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
-
-## Specifying And Handling Timeouts
-
-The timeout feature was added in git gem version `2.0.0`.
-
-A timeout for git command line operations can be set either globally or for specific
-method calls that accept a `:timeout` parameter.
-
-The timeout value must be a real, non-negative `Numeric` value that specifies a
-number of seconds a `git` command will be given to complete before being sent a KILL
-signal. This library may hang if the `git` command does not terminate after receiving
-the KILL signal.
-
-When a command times out, it is killed by sending it the `SIGKILL` signal and a
-`Git::TimeoutError` is raised. This error derives from the `Git::SignaledError` and
-`Git::Error`.
-
-If the timeout value is `0` or `nil`, no timeout will be enforced.
-
-If a method accepts a `:timeout` parameter and a receives a non-nil value, the value
-of this parameter will override the global timeout value. In this context, a value of
-`nil` (which is usually the default) will use the global timeout value and a value of
-`0` will turn off timeout enforcement for that method call no matter what the global
-value is.
-
-To set a global timeout, use the `Git.config` object:
+Open an existing repo and commit:
 
 ```ruby
-Git.config.timeout = nil # a value of nil or 0 means no timeout is enforced
-Git.config.timeout = 1.5 # can be any real, non-negative Numeric interpreted as number of seconds
-```
-
-The global timeout can be overridden for a specific method if the method accepts a
-`:timeout` parameter:
+require 'git'
 
-```ruby
-repo_url = 'https://github.com/ruby-git/ruby-git.git'
-Git.clone(repo_url) # Use the global timeout value
-Git.clone(repo_url, timeout: nil) # Also uses the global timeout value
-Git.clone(repo_url, timeout: 0) # Do not enforce a timeout
-Git.clone(repo_url, timeout: 10.5)  # Timeout after 10.5 seconds raising Git::SignaledError
+repo = Git.open('/path/to/repo')
+repo.add(all: true)
+repo.commit('chore: update files')
+repo.push
 ```
 
-If the command takes too long, a `Git::TimeoutError` will be raised:
+Initialize a new repo and make the first commit:
 
 ```ruby
-begin
-  Git.clone(repo_url, timeout: 10)
-rescue Git::TimeoutError => e
-  e.result.tap do |r|
-    r.class #=> Git::CommandLineResult
-    r.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
-    r.status.timeout? #=> true
-    r.git_cmd # The git command ran as an array of strings
-    r.stdout # The command's output to stdout until it was terminated
-    r.stderr # The command's output to stderr until it was terminated
-  end
-end
-```
-
-## Deprecations
-
-This gem uses ActiveSupport's deprecation mechanism to report deprecation warnings.
-
-You can silence deprecation warnings by adding this line to your source code:
+require 'git'
 
-```ruby
-Git::Deprecation.behavior = :silence
+repo = Git.init('my_project')
+repo.add(all: true)
+repo.commit('initial commit')
 ```
 
-See [the Active Support Deprecation
-documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
-for more details.
-
-If deprecation warnings are silenced, you should reenable them before upgrading the
-git gem to the next major version. This will make it easier to identify changes
-needed for the upgrade.
-
 ## Examples
 
-Here are a bunch of examples of how to use the Ruby/Git package.
+Beyond the basics covered in Quick Start, these examples show the full range of
+options and variations for each operation.
 
-Require the 'git' gem.
+### Configuration
+
+Configure the `git` command line:
 
 ```ruby
-require 'git'
+# Global config (in ~/.gitconfig)
+settings = Git.global_config # returns a Hash
+username = Git.global_config('user.email')
+Git.global_config('user.email', 'user@example.com')
+
+# Repository config
+repo = Git.open('path/to/repo')
+settings = repo.config # returns a Hash
+username = repo.config('user.email')
+repo.config('user.email', 'anotheruser@example.com')
 ```
 
-Git env config
+Configure the git gem:
 
 ```ruby
 Git.configure do |config|
-  # If you want to use a custom git binary
-  config.binary_path = '/git/bin/path'
-
-  # If you need to use a custom SSH script
-  config.git_ssh = '/path/to/ssh/script'
+  config.binary_path = '/usr/local/bin/git'
+  config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
 end
-```
 
-_NOTE: Another way to specify where is the `git` binary is through the environment variable `GIT_PATH`_
+# or
+
+Git.config.binary_path = '/usr/local/bin/git'
+Git.config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
+```
 
 **How SSH configuration is determined:**
 
-- If `git_ssh` is not specified in the API call, the global config (`Git.configure { |c| c.git_ssh = ... }`) is used.
-- If `git_ssh: nil` is specified, SSH is disabled for that instance (no SSH key or script will be used).
-- If `git_ssh` is a non-empty string, it is used for that instance (overriding the global config).
+- If `git_ssh` is not specified in the API call, the global config (`Git.configure {
+  |c| c.git_ssh = ... }`) is used.
+- If `git_ssh: nil` is specified, SSH is disabled for that instance (no SSH key or
+  script will be used).
+- If `git_ssh` is a non-empty string, it is used for that instance (overriding the
+  global config).
 
 You can also specify a custom SSH script on a per-repository basis:
 
@@ -244,43 +180,46 @@ git = Git.clone('git@github.com:user/repo.git', 'local-dir',
 git = Git.init('new-repo', git_ssh: 'ssh -i /path/to/private_key')
 ```
 
-This is especially useful in multi-threaded applications where different repositories require different SSH credentials.
+This is especially useful in multi-threaded applications where different repositories
+require different SSH credentials.
+
+### Read Operations
 
-Here are the operations that need read permission only.
+Here are the operations that need read permission only:
 
 ```ruby
-g = Git.open(working_dir, :log => Logger.new(STDOUT))
+repo = Git.open(working_dir, :log => Logger.new(STDOUT))
 
-g.index
-g.index.readable?
-g.index.writable?
-g.repo
-g.dir
+repo.index
+repo.index.readable?
+repo.index.writable?
+repo.repo
+repo.dir
 
 # ls-tree with recursion into subtrees (list files)
-g.ls_tree("HEAD", recursive: true)
+repo.ls_tree("HEAD", recursive: true)
 
 # log - returns a Git::Log object, which is an Enumerator of Git::Commit objects
 # default configuration returns a max of 30 commits
-g.log
-g.log(200) # 200 most recent commits
-g.log.since('2 weeks ago') # default count of commits since 2 weeks ago.
-g.log(200).since('2 weeks ago') # commits since 2 weeks ago, limited to 200.
-g.log.between('v2.5', 'v2.6')
-g.log.each {|l| puts l.sha }
-g.gblob('v2.5:Makefile').log.since('2 weeks ago')
+repo.log
+repo.log(200) # 200 most recent commits
+repo.log.since('2 weeks ago') # default count of commits since 2 weeks ago.
+repo.log(200).since('2 weeks ago') # commits since 2 weeks ago, limited to 200.
+repo.log.between('v2.5', 'v2.6')
+repo.log.each {|l| puts l.sha }
+repo.gblob('v2.5:Makefile').log.since('2 weeks ago')
 
-g.object('HEAD^').to_s  # git show / git rev-parse
-g.object('HEAD^').contents
-g.object('v2.5:Makefile').size
-g.object('v2.5:Makefile').sha
+repo.object('HEAD^').to_s  # git show / git rev-parse
+repo.object('HEAD^').contents
+repo.object('v2.5:Makefile').size
+repo.object('v2.5:Makefile').sha
 
-g.gtree(treeish)
-g.gblob(treeish)
-g.gcommit(treeish)
+repo.gtree(treeish)
+repo.gblob(treeish)
+repo.gcommit(treeish)
 
 
-commit = g.gcommit('1cc8667014381')
+commit = repo.gcommit('1cc8667014381')
 
 commit.gtree
 commit.parent.sha
@@ -292,60 +231,74 @@ commit.committer.name
 commit.date.strftime("%m-%d-%y")
 commit.message
 
-tree = g.gtree("HEAD^{tree}")
+tree = repo.gtree("HEAD^{tree}")
 
 tree.blobs
 tree.subtrees
 tree.children # blobs and subtrees
 
-g.rev_parse('v2.0.0:README.md')
-
-g.branches # returns Git::Branch objects
-g.branches.local
-g.current_branch
-g.branches.remote
-g.branches[:main].gcommit
-g.branches['origin/main'].gcommit
-
-g.grep('hello')  # implies HEAD
-g.blob('v2.5:Makefile').grep('hello')
-g.tag('v2.5').grep('hello', 'docs/')
-g.describe()
-g.describe('0djf2aa')
-g.describe('HEAD', {:all => true, :tags => true})
-
-g.diff(commit1, commit2).size
-g.diff(commit1, commit2).stats
-g.diff(commit1, commit2).name_status
-g.gtree('v2.5').diff('v2.6').insertions
-g.diff('gitsearch1', 'v2.5').path('lib/')
-g.diff('gitsearch1', 'v2.5').path('lib/', 'docs/', 'README.md')  # multiple paths
-g.diff('gitsearch1', @git.gtree('v2.5'))
-g.diff('gitsearch1', 'v2.5').path('docs/').patch
-g.gtree('v2.5').diff('v2.6').patch
-
-g.gtree('v2.5').diff('v2.6').each do |file_diff|
+repo.rev_parse('v2.0.0:README.md')
+
+repo.branches # returns Git::Branch objects
+repo.branches.local
+repo.current_branch
+repo.branches.remote
+repo.branches[:main].gcommit
+repo.branches['origin/main'].gcommit
+
+repo.grep('hello')  # implies HEAD
+repo.blob('v2.5:Makefile').grep('hello')
+repo.tag('v2.5').grep('hello', 'docs/')
+repo.describe()
+repo.describe('0djf2aa')
+repo.describe('HEAD', {:all => true, :tags => true})
+
+repo.diff(commit1, commit2).size
+repo.diff(commit1, commit2).stats
+repo.diff(commit1, commit2).name_status
+repo.gtree('v2.5').diff('v2.6').insertions
+repo.diff('gitsearch1', 'v2.5').path('lib/')
+repo.diff('gitsearch1', 'v2.5').path('lib/', 'docs/', 'README.md')  # multiple paths
+repo.diff('gitsearch1', repo.gtree('v2.5'))
+repo.diff('gitsearch1', 'v2.5').path('docs/').patch
+repo.gtree('v2.5').diff('v2.6').patch
+
+repo.gtree('v2.5').diff('v2.6').each do |file_diff|
   puts file_diff.path
   puts file_diff.patch
   puts file_diff.blob(:src).contents
 end
 
-g.worktrees # returns Git::Worktree objects
-g.worktrees.count
-g.worktrees.each do |worktree|
+repo.worktrees # returns Git::Worktree objects
+repo.worktrees.count
+repo.worktrees.each do |worktree|
   worktree.dir
   worktree.gcommit
   worktree.to_s
 end
 
-g.config('user.name')  # returns 'Scott Chacon'
-g.config # returns whole config hash
+# Check repository integrity with fsck
+result = repo.fsck
+result.dangling.each { |obj| puts "dangling #{obj.type}: #{obj.sha}" }
+result.missing.each { |obj| puts "missing #{obj.type}: #{obj.sha}" }
+
+# Check if repository has any issues
+puts "Repository is clean" if result.empty?
+
+# fsck with options
+result = repo.fsck(unreachable: true, strict: true)
+
+# Suppress dangling object output
+result = repo.fsck(dangling: false)
+
+repo.config('user.name')  # returns 'Scott Chacon'
+repo.config # returns whole config hash
 
 # Configuration can be set when cloning using the :config option.
 # This option can be an single configuration String or an Array
 # if multiple config items need to be set.
 #
-g = Git.clone(
+repo = Git.clone(
   git_uri, destination_path,
   :config => [
     'core.sshCommand=ssh -i /home/user/.ssh/id_rsa',
@@ -353,11 +306,11 @@ g = Git.clone(
   ]
 )
 
-g.tags # returns array of Git::Tag objects
+repo.tags # returns array of Git::Tag objects
 
-g.show()
-g.show('HEAD')
-g.show('v2.8', 'README.md')
+repo.show()
+repo.show('HEAD')
+repo.show('v2.8', 'README.md')
 
 Git.ls_remote('https://github.com/ruby-git/ruby-git.git') # returns a hash containing the available references of the repo.
 Git.ls_remote('/path/to/local/repo')
@@ -366,207 +319,316 @@ Git.ls_remote() # same as Git.ls_remote('.')
 Git.default_branch('https://github.com/ruby-git/ruby-git') #=> 'main'
 ```
 
+### Write Operations
+
 And here are the operations that will need to write to your git repository.
 
 ```ruby
-g = Git.init
-  Git.init('project')
-  Git.init('/home/schacon/proj',
-  { :repository => '/opt/git/proj.git',
-      :index => '/tmp/index'} )
+repo = Git.init # default is the current directory
+repo = Git.init('project')
+repo = Git.init(
+  '/home/schacon/proj',
+  { :repository => '/opt/git/proj.git', :index => '/tmp/index'}
+)
 
 # Clone from a git url
 git_url = 'https://github.com/ruby-git/ruby-git.git'
-# Clone into the ruby-git directory
-g = Git.clone(git_url)
+repo = Git.clone(git_url)
 
 # Clone into /tmp/clone/ruby-git-clean
 name = 'ruby-git-clean'
 path = '/tmp/clone'
-g = Git.clone(git_url, name, :path => path)
-g.dir #=> /tmp/clone/ruby-git-clean
+repo = Git.clone(git_url, name, :path => path)
+repo.dir #=> /tmp/clone/ruby-git-clean
 
-g.config('user.name', 'Scott Chacon')
-g.config('user.email', 'email@email.com')
+repo.config('user.name', 'Scott Chacon')
+repo.config('user.email', 'email@email.com')
 
 # Clone can take a filter to tell the serve to send a partial clone
-g = Git.clone(git_url, name, :path => path, :filter => 'tree:0')
+repo = Git.clone(git_url, name, :path => path, :filter => 'tree:0')
 
 # Clone can control single-branch behavior (nil default keeps current git behavior)
-g = Git.clone(git_url, name, :path => path, :depth => 1, :single_branch => false)
+repo = Git.clone(git_url, name, :path => path, :depth => 1, :single_branch => false)
 
 # Clone can take an optional logger
-logger = Logger.new
-g = Git.clone(git_url, NAME, :log => logger)
+logger = Logger.new(STDOUT)
+repo = Git.clone(git_url, 'my-repo', :log => logger)
 
-g.add                                   # git add -- "."
-g.add(:all=>true)                       # git add --all -- "."
-g.add('file_path')                      # git add -- "file_path"
-g.add(['file_path_1', 'file_path_2'])   # git add -- "file_path_1" "file_path_2"
+repo.add                                   # git add -- "."
+repo.add(:all=>true)                       # git add --all -- "."
+repo.add('file_path')                      # git add -- "file_path"
+repo.add(['file_path_1', 'file_path_2'])   # git add -- "file_path_1" "file_path_2"
 
-g.remove()                                # git rm -f -- "."
-g.remove('file.txt')                      # git rm -f -- "file.txt"
-g.remove(['file.txt', 'file2.txt'])       # git rm -f -- "file.txt" "file2.txt"
-g.remove('file.txt', :recursive => true)  # git rm -f -r -- "file.txt"
-g.remove('file.txt', :cached => true)     # git rm -f --cached -- "file.txt"
+repo.remove()                                # git rm -f -- "."
+repo.remove('file.txt')                      # git rm -f -- "file.txt"
+repo.remove(['file.txt', 'file2.txt'])       # git rm -f -- "file.txt" "file2.txt"
+repo.remove('file.txt', :recursive => true)  # git rm -f -r -- "file.txt"
+repo.remove('file.txt', :cached => true)     # git rm -f --cached -- "file.txt"
 
-g.commit('message')
-g.commit_all('message')
+repo.commit('message')
+repo.commit_all('message')
 
 # Sign a commit using the gpg key configured in the user.signingkey config setting
-g.config('user.signingkey', '0A46826A')
-g.commit('message', gpg_sign: true)
+repo.config('user.signingkey', '0A46826A')
+repo.commit('message', gpg_sign: true)
 
 # Sign a commit using a specified gpg key
 key_id = '0A46826A'
-g.commit('message', gpg_sign: key_id)
+repo.commit('message', gpg_sign: key_id)
 
 # Skip signing a commit (overriding any global gpgsign setting)
-g.commit('message', no_gpg_sign: true)
+repo.commit('message', no_gpg_sign: true)
 
-g = Git.clone(repo, 'myrepo')
-g.chdir do
-new_file('test-file', 'blahblahblah')
-g.status.changed.each do |file|
-  puts file.blob(:index).contents
-end
+repo = Git.clone(git_url, 'myrepo')
+repo.chdir do
+  File.write('test-file', 'blahblahblah')
+  repo.status.changed.each do |file|
+    puts file.blob(:index).contents
+  end
 end
 
-g.reset # defaults to HEAD
-g.reset_hard(Git::Commit)
+repo.reset # defaults to HEAD
+repo.reset_hard(Git::Commit)
 
-g.branch('new_branch') # creates new or fetches existing
-g.branch('new_branch').checkout
-g.branch('new_branch').delete
-g.branch('existing_branch').checkout
-g.branch('main').contains?('existing_branch')
+repo.branch('new_branch') # creates new or fetches existing
+repo.branch('new_branch').checkout
+repo.branch('new_branch').delete
+repo.branch('existing_branch').checkout
+repo.branch('main').contains?('existing_branch')
 
 # delete remote branch
-g.push('origin', 'remote_branch_name', force: true, delete: true)
+repo.push('origin', 'remote_branch_name', force: true, delete: true)
 
-g.checkout('new_branch')
-g.checkout('new_branch', new_branch: true, start_point: 'main')
-g.checkout(g.branch('new_branch'))
+repo.checkout('new_branch')
+repo.checkout('new_branch', new_branch: true, start_point: 'main')
+repo.checkout(repo.branch('new_branch'))
 
-g.branch(name).merge(branch2)
-g.branch(branch2).merge  # merges HEAD with branch2
+repo.branch(name).merge(branch2)
+repo.branch(branch2).merge  # merges HEAD with branch2
 
-g.branch(name).in_branch(message) { # add files }  # auto-commits
-g.merge('new_branch')
-g.merge('new_branch', 'merge commit message', no_ff: true)
-g.merge('origin/remote_branch')
-g.merge(g.branch('main'))
-g.merge([branch1, branch2])
+repo.branch(name).in_branch(message) { # add files }  # auto-commits
+repo.merge('new_branch')
+repo.merge('new_branch', 'merge commit message', no_ff: true)
+repo.merge('origin/remote_branch')
+repo.merge(repo.branch('main'))
+repo.merge([branch1, branch2])
 
-g.merge_base('branch1', 'branch2')
+repo.merge_base('branch1', 'branch2')
 
-r = g.add_remote(name, uri)  # Git::Remote
-r = g.add_remote(name, Git::Base)  # Git::Remote
+r = repo.add_remote(name, uri)  # Git::Remote
+r = repo.add_remote(name, Git::Base)  # Git::Remote
 
-g.remotes  # array of Git::Remotes
-g.remote(name).fetch
-g.remote(name).remove
-g.remote(name).merge
-g.remote(name).merge(branch)
+repo.remotes  # array of Git::Remotes
+repo.remote(name).fetch
+repo.remote(name).remove
+repo.remote(name).merge
+repo.remote(name).merge(branch)
 
-g.remote_set_branches('origin', '*', add: true) # append additional fetch refspecs
-g.remote_set_branches('origin', 'feature', 'release/*') # replace fetch refspecs
+repo.remote_set_branches('origin', '*', add: true) # append additional fetch refspecs
+repo.remote_set_branches('origin', 'feature', 'release/*') # replace fetch refspecs
 
-g.fetch
-g.fetch(g.remotes.first)
-g.fetch('origin', {:ref => 'some/ref/head'} )
-g.fetch(all: true, force: true, depth: 2)
-g.fetch('origin', {:'update-head-ok' => true})
+repo.fetch
+repo.fetch(repo.remotes.first)
+repo.fetch('origin', {:ref => 'some/ref/head'} )
+repo.fetch(all: true, force: true, depth: 2)
+repo.fetch('origin', {:'update-head-ok' => true})
 
-g.pull
-g.pull(Git::Repo, Git::Branch) # fetch and a merge
+repo.pull
+repo.pull(Git::Repo, Git::Branch) # fetch and a merge
 
-g.add_tag('tag_name') # returns Git::Tag
-g.add_tag('tag_name', 'object_reference')
-g.add_tag('tag_name', 'object_reference', {:options => 'here'})
-g.add_tag('tag_name', {:options => 'here'})
+repo.add_tag('tag_name') # returns Git::Tag
+repo.add_tag('tag_name', 'object_reference')
+repo.add_tag('tag_name', 'object_reference', {:options => 'here'})
+repo.add_tag('tag_name', {:options => 'here'})
 
-Options:
-  :a | :annotate
-  :d
-  :f
-  :m | :message
-  :s
+repo.delete_tag('tag_name')
 
-g.delete_tag('tag_name')
+repo.repack
 
-g.repack
-
-g.push
-g.push(g.remote('name'))
+repo.push
+repo.push(repo.remote('name'))
 
 # delete remote branch
-g.push('origin', 'remote_branch_name', force: true, delete: true)
+repo.push('origin', 'remote_branch_name', force: true, delete: true)
 
 # push all branches to remote at one time
-g.push('origin', all: true)
+repo.push('origin', all: true)
 
-g.worktree('/tmp/new_worktree').add
-g.worktree('/tmp/new_worktree', 'branch1').add
-g.worktree('/tmp/new_worktree').remove
-g.worktrees.prune
+repo.worktree('/tmp/new_worktree').add
+repo.worktree('/tmp/new_worktree', 'branch1').add
+repo.worktree('/tmp/new_worktree').remove
+repo.worktrees.prune
 ```
 
+### Index and Tree Operations
+
 Some examples of more low-level index and tree operations
 
 ```ruby
-g.with_temp_index do
+repo.with_temp_index do
 
-  g.read_tree(tree3) # calls self.index.read_tree
-  g.read_tree(tree1, :prefix => 'hi/')
+  repo.read_tree(tree3) # calls self.index.read_tree
+  repo.read_tree(tree1, :prefix => 'hi/')
 
-  c = g.commit_tree('message')
+  c = repo.commit_tree('message')
   # or #
-  t = g.write_tree
-  c = g.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
+  t = repo.write_tree
+  c = repo.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
 
-  g.branch('branch_name').update_ref(c)
-  g.update_ref(branch, c)
+  repo.branch('branch_name').update_ref(c)
+  repo.update_ref(branch, c)
 
-  g.with_temp_working do # new blank working directory
-    g.checkout
-    g.checkout(another_index)
-    g.commit # commits to temp_index
+  repo.with_temp_working do # new blank working directory
+    repo.checkout
+    repo.checkout(another_index)
+    repo.commit # commits to temp_index
   end
 end
 
-g.set_index('/path/to/index')
-
+repo.set_index('/path/to/index')
 
-g.with_index(path) do
+repo.with_index(path) do
   # calls set_index, then switches back after
 end
 
-g.with_working(dir) do
+repo.with_working(dir) do
 # calls set_working, then switches back after
 end
 
-g.with_temp_working(dir) do
-  g.checkout_index(:prefix => dir, :path_limiter => path)
+repo.with_temp_working(dir) do
+  repo.checkout_index(:prefix => dir, :path_limiter => path)
   # do file work
-  g.commit # commits to index
+  repo.commit # commits to index
 end
 ```
 
-## Ruby version support policy
+## Errors Raised By This Gem
 
-This gem will be expected to function correctly on:
+The git gem will only raise an `ArgumentError` or an error that is a subclass of
+`Git::Error`. It does not explicitly raise any other types of errors.
 
-- All non-EOL versions of the MRI Ruby on Mac, Linux, and Windows
-- The latest version of JRuby on Linux
-- The latest version of Truffle Ruby on Linus
+It is recommended to rescue `Git::Error` to catch any runtime error raised by this
+gem unless you need more specific error handling.
 
-It is this project's intent to support the latest version of JRuby on Windows
-once the following JRuby bug is fixed:
+```ruby
+begin
+  # some git operation
+rescue Git::Error => e
+  puts "An error occurred: #{e.message}"
+end
+```
 
-jruby/jruby#7515
+See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
 
-## Git version support policy
+## Specifying And Handling Timeouts
+
+The timeout feature was added in git gem version `2.0.0`.
+
+A timeout for git command line operations can be set either globally or for specific
+method calls that accept a `:timeout` parameter.
+
+The timeout value must be a real, non-negative `Numeric` value that specifies a
+number of seconds a `git` command will be given to complete before being sent a KILL
+signal. This library may hang if the `git` command does not terminate after receiving
+the KILL signal.
+
+When a command times out, it is killed by sending it the `SIGKILL` signal and a
+`Git::TimeoutError` is raised. This error derives from the `Git::SignaledError` and
+`Git::Error`.
+
+If the timeout value is `0` or `nil`, no timeout will be enforced.
+
+If a method accepts a `:timeout` parameter and a receives a non-nil value, the value
+of this parameter will override the global timeout value. In this context, a value of
+`nil` (which is usually the default) will use the global timeout value and a value of
+`0` will turn off timeout enforcement for that method call no matter what the global
+value is.
+
+To set a global timeout, use the `Git.config` object:
+
+```ruby
+Git.config.timeout = nil # a value of nil or 0 means no timeout is enforced
+Git.config.timeout = 1.5 # can be any real, non-negative Numeric interpreted as number of seconds
+```
+
+The global timeout can be overridden for a specific method if the method accepts a
+`:timeout` parameter:
+
+```ruby
+repo_url = 'https://github.com/ruby-git/ruby-git.git'
+Git.clone(repo_url) # Use the global timeout value
+Git.clone(repo_url, timeout: nil) # Also uses the global timeout value
+Git.clone(repo_url, timeout: 0) # Do not enforce a timeout
+Git.clone(repo_url, timeout: 10.5)  # Timeout after 10.5 seconds raising Git::SignaledError
+```
+
+If the command takes too long, a `Git::TimeoutError` will be raised:
+
+```ruby
+begin
+  Git.clone(repo_url, timeout: 10)
+rescue Git::TimeoutError => e
+  e.result.tap do |r|
+    r.class #=> Git::CommandLineResult
+    r.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
+    r.status.timeout? #=> true
+    r.git_cmd # The git command ran as an array of strings
+    r.stdout # The command's output to stdout until it was terminated
+    r.stderr # The command's output to stderr until it was terminated
+  end
+end
+```
+
+## Deprecations
+
+This gem uses ActiveSupport's deprecation mechanism to report deprecation warnings.
+
+You can silence deprecation warnings by adding this line to your source code:
+
+```ruby
+Git::Deprecation.behavior = :silence
+```
+
+See [the Active Support Deprecation
+documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
+for more details.
+
+If deprecation warnings are silenced, you should reenable them before upgrading the
+git gem to the next major version. This will make it easier to identify changes
+needed for the upgrade.
+
+## Project Policies
+
+These documents set expectations for behavior, contribution workflows, AI-assisted
+changes, decision making, maintainer roles, and licensing. Please review them before
+opening issues or pull requests.
+
+| Document | Description |
+| -------- | ----------- |
+| [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) | We follow the Ruby community Code of Conduct; expect respectful, harassment-free participation and report concerns to maintainers. |
+| [CONTRIBUTING](CONTRIBUTING.md) | How to report issues, submit PRs with Conventional Commits, meet coding/testing standards, and follow the Code of Conduct. |
+| [AI_POLICY](AI_POLICY.md) | AI-assisted contributions are welcome. Contributors are expected to read and apply the AI Policy, and ensure any AI-assisted work meets our quality, security, and licensing standards. |
+| [Ruby version support policy](#ruby-version-support-policy) | Supported Ruby runtimes and platforms; bump decisions and CI coverage expectations. |
+| [Git version support policy](#git-version-support-policy) | Minimum supported git version and how version bumps are communicated and enforced. |
+| [GOVERNANCE](GOVERNANCE.md) | Principles-first governance defining maintainer/project lead roles, least-privilege access, consensus/majority decisions, and nomination/emeritus steps. |
+| [MAINTAINERS](MAINTAINERS.md) | Lists active maintainers (Project Lead noted) and emeritus alumni with links; see governance for role scope. |
+| [LICENSE](LICENSE) | MIT License terms for using, modifying, and redistributing this project. |
+
+### Ruby Version Support Policy
+
+This gem is expected to function correctly on:
+
+- All [non-EOL versions](https://www.ruby-lang.org/en/downloads/branches/) of the MRI
+  Ruby on Mac, Linux, and Windows
+- The latest version of JRuby 9.4+ on Linux
+- The latest version of TruffleRuby 24+ on Linux
+
+It is this project's intent to support the latest version of JRuby on Windows once
+the [process_executer](https://github.com/main-branch/process_executer) gem properly
+supports subprocess status reporting on JRuby for Windows (see
+[main-branch/process_executer#156](https://github.com/main-branch/process_executer/issues/156)).
+
+### Git Version Support Policy
 
 This gem requires git version 2.28.0 or greater as specified in the gemspec. This
 requirement reflects:
@@ -585,12 +647,18 @@ gem as new git features are adopted or as maintaining backward compatibility bec
 impractical. Such changes will be clearly documented in the CHANGELOG and release
 notes.
 
-## License
+## 📢 Project Announcements 📢
 
-Licensed under MIT License Copyright (c) 2008  Scott Chacon. See LICENSE for further
-details.
+### 2026-01-07: AI Policy Introduced
 
-## 📢 Project Announcements 📢
+We have adopted a formal [AI Policy](AI_POLICY.md) to clarify expectations for
+AI-assisted contributions. Please review it before opening a PR to ensure your
+changes are fully understood, meet our quality bar, and respect licensing
+requirements.
+
+We chose a principles-based policy to respect contributors’ time and expertise. It’s
+quick to read, easy to remember, and avoids unnecessary policy overhead while still
+setting clear expectations.
 
 ### 2025-07-09: Architectural Redesign
 
@@ -643,11 +711,12 @@ rake rubocop
 RuboCop is also run  as part of the default rake task (by running `rake`) that is run
 in our Continuous Integration workflow.
 
-Going forward, any PRs that have any Robocop offenses will not be merged. In
-certain rare cases, it might be acceptable to disable a  RuboCop check for the most
-limited scope possible.
+Going forward, any PRs that have any Robocop offenses will not be merged. In certain
+rare cases, it might be acceptable to disable a  RuboCop check for the most limited
+scope possible.
 
-If you have a problem fixing a  RuboCop offense, don't be afraid to ask a contributor.
+If you have a problem fixing a  RuboCop offense, don't be afraid to ask a
+contributor.
 
 ### 2025-06-06: Default Branch Rename