git 1.19.1 → 5.5.0

data/README.md

@@ -3,425 +3,581 @@
 # @title README
 -->
 
-# The Git Gem
+# The git gem
 
 [![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git)
+[![Build Status](https://github.com/ruby-git/ruby-git/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/ruby-git/ruby-git/actions/workflows/continuous_integration.yml)
 [![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=master)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
-[![Code Climate](https://codeclimate.com/github/ruby-git/ruby-git.png)](https://codeclimate.com/github/ruby-git/ruby-git)
+[![Change
+Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md)
+[![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-Doc-blue)](AI_POLICY.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **v5.0.0 is here.** This is a major release with a redesigned internal
+> architecture, but most v4.x code runs unchanged thanks to compatibility
+> shims. See [UPGRADING.md](UPGRADING.md) for the migration guide and
+> [CHANGELOG.md](CHANGELOG.md) for full release notes.
+
+- [Summary](#summary)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Examples](#examples)
+  - [Gem configuration](#gem-configuration)
+  - [Git configuration](#git-configuration)
+  - [Full API](#full-api)
+- [Errors raised by this gem](#errors-raised-by-this-gem)
+- [Specifying and handling timeouts](#specifying-and-handling-timeouts)
+- [Deprecations](#deprecations)
+- [Platform limitations](#platform-limitations)
+  - [Regex metacharacters on Git for Windows](#regex-metacharacters-on-git-for-windows)
+- [Project policies](#project-policies)
+  - [Ruby version support policy](#ruby-version-support-policy)
+  - [Git version support policy](#git-version-support-policy)
+  - [Deprecation policy](#deprecation-policy)
+  - [Release support policy](#release-support-policy)
+- [Project announcements](#project-announcements)
+  - [2026-08-23: v5.x deprecations and the v6.0.0 roadmap](#2026-08-23-v5x-deprecations-and-the-v600-roadmap)
+  - [2026-07-28: v5.0.0 released](#2026-07-28-v500-released)
+  - [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)
+  - [2025-05-15: We've switched to Conventional Commits](#2025-05-15-weve-switched-to-conventional-commits)
+
+## Summary
+
+The [git gem](https://rubygems.org/gems/git) provides a Ruby interface to the `git`
+command line.
+
+Get 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)
+
+[Git::Repository](https://rubydoc.info/gems/git/Git/Repository) documents the
+methods you can call on a repository object.
 
-The [git gem](https://rubygems.org/gems/git) provides an API that can be used to
-create, read, and manipulate Git repositories by wrapping system calls to the `git`
-command line. The API can be used for working with Git in complex interactions
-including branching and merging, object inspection and manipulation, history, patch
-generation and more.
+## Install
 
-## v2.0.0 pre-release
+This gem is a wrapper around the `git` command line, so a `git` executable (version
+2.28.0 or greater) must be installed and on your `PATH`. See the [Git version support
+policy](#git-version-support-policy) for details.
 
-git 2.0.0 is available as a pre-release version for testing! Please give it a try.
+Install the gem and add to the application's Gemfile by executing:
 
-**JRuby on Windows is not yet supported by the 2.x release line. Users running JRuby
-on Windows should continue to use the 1.x release line.**
+```shell
+bundle add git
+```
 
-The changes coming in this major release include:
+If you are not using bundler to manage dependencies, install the gem by executing:
 
-* Create a policy of supported Ruby versions to support only non-EOL Ruby versions
-* Create a policy of supported Git CLI versions (released 2020-12-25)
-* Update the required Ruby version to at least 3.0 (released 2020-07-27)
-* Update the required Git command line version to at least 2.28
-* Update how CLI commands are called to use the [process_executer](https://github.com/main-branch/process_executer)
-  gem which is built on top of [Kernel.spawn](https://ruby-doc.org/3.3.0/Kernel.html#method-i-spawn).
-  See [PR #617](https://github.com/ruby-git/ruby-git/pull/617) for more details
-  on the motivation for this implementation.
+```shell
+gem install git
+```
 
-The tentative plan is to release `2.0.0` near the end of March 2024 depending on
-the feedback received during the pre-release period.
+## Quick start
 
-The `master` branch will be used for `2.x` development. If needed, fixes for `1.x`
-version will be done on the `v1` branch.
+All functionality for this gem starts with the top-level
+[`Git`](https://rubydoc.info/gems/git/Git) module. Use this module to run non-repo
+scoped `git` commands such as `config`.
 
-## Homepage
+The `Git` module also has factory methods such as `open`, `clone`, and `init` which
+return a [`Git::Repository`](https://rubydoc.info/gems/git/Git/Repository) object. Use
+the `Git::Repository` object to run repo-specific `git` commands such as `add`,
+`commit`, `push`, and `log`.
 
-The project source code is at:
+Clone, read status, and log:
 
-http://github.com/ruby-git/ruby-git
+```ruby
+require 'git'
 
-## Documentation
+repo = Git.clone('https://github.com/ruby-git/ruby-git.git', 'ruby-git')
+repo.status_info.changed.each_key { |path| puts "changed: #{path}" }
+repo.log(5).execute.each { |c| puts c.message }
+```
 
-Detailed documentation can be found at:
+Open an existing repo and commit:
 
-https://rubydoc.info/gems/git/Git.html
+```ruby
+require 'git'
 
-Get started by obtaining a repository object by:
+repo = Git.open('/path/to/repo')
+repo.add(all: true)
+repo.commit('chore: update files')
+repo.push
+```
 
-* 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)
+Initialize a new repo and make the first commit:
 
-Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
+```ruby
+require 'git'
 
-## Install
+repo = Git.init('my_project')
+repo.add(all: true)
+repo.commit('initial commit')
+```
+
+## Examples
+
+These examples cover configuring the gem and git itself. For the full set of
+repository operations, see [Full API](#full-api) below.
+
+### Gem configuration
+
+Configure the git gem:
 
-You can install Ruby/Git like this:
+```ruby
+Git.configure do |config|
+  config.binary_path = '/usr/local/bin/git'
+  config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
+end
 
+# or
+
+Git.config.binary_path = '/usr/local/bin/git'
+Git.config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
 ```
-sudo gem install git
+
+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).
+
+You can also specify a custom SSH script on a per-repository basis:
+
+```ruby
+# Use a specific SSH key for a single repository
+git = Git.open('/path/to/repo', git_ssh: 'ssh -i /path/to/private_key')
+
+# Or when cloning
+git = Git.clone('git@github.com:user/repo.git', 'local-dir',
+                git_ssh: 'ssh -i /path/to/private_key')
+
+# Or when initializing
+git = Git.init('new-repo', git_ssh: 'ssh -i /path/to/private_key')
 ```
 
-## Code Status
+This is especially useful in multi-threaded applications where different repositories
+require different SSH credentials.
+
+### Git configuration
 
+Read and set `git` configuration values (via `git config`):
 
-## Major Objects
+```ruby
+# Global config (in ~/.gitconfig)
+entries = Git.config_list(global: true)         # returns Array<Git::ConfigEntryInfo>
+entry   = Git.config_get('user.email', global: true) # returns Git::ConfigEntryInfo or nil
+email    = entry&.value                          # => "user@example.com" or nil
+Git.config_set('user.email', 'user@example.com', global: true)
+
+# Repository config
+repo = Git.open('path/to/repo')
+entries  = repo.config_list                     # returns Array<Git::ConfigEntryInfo>
+entry    = repo.config_get('user.email')        # returns Git::ConfigEntryInfo or nil
+email    = entry&.value                         # => "anotheruser@example.com" or nil
+repo.config_set('user.email', 'anotheruser@example.com')
+```
 
-**Git::Base** - The object returned from a `Git.open` or `Git.clone`. Most major actions are called from this object.
+### Full API
 
-**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.
+The quick start and the configuration sections above cover the most common setup.
+The [`Git::Repository`](https://rubydoc.info/gems/git/Git/Repository) reference
+covers everything else: reading history, diffs, branches, remotes, worktrees,
+staging, and low-level index and tree work. It documents every method and the object
+type each one returns (such as `Git::Log`, `Git::Object::Commit`, `Git::Diff`,
+`Git::Branch`, and `Git::Worktree`), so you can follow the links from a method to
+the full API of its result.
 
-**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.
+## Errors raised by this gem
 
-**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 gem raises only `ArgumentError` or errors that subclass `Git::Error`. It
+does not explicitly raise any other types of errors.
 
-**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.
+Rescue `Git::Error` to catch any runtime error raised by this gem, unless you need
+more specific error handling.
 
-**Git::Remote**- A reference to a remote repository that is tracked by this repository.
+```ruby
+begin
+  # some git operation
+rescue Git::Error => e
+  puts "An error occurred: #{e.message}"
+end
+```
 
-**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:
+See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
 
- `@git.log(20).object("some_file").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] }`
+## Specifying and handling timeouts
 
-Pass the `--all` option to `git log` as follows:
+Set a timeout for git command line operations either globally or per method call for
+methods that accept a `:timeout` parameter.
 
- `@git.log.all.each { |commit| [block] }`
+The timeout value must be a real, non-negative `Numeric` value that specifies the
+number of seconds a `git` command is 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.
 
- **Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
+When a command times out, the gem kills it with the `SIGKILL` signal and raises a
+`Git::TimeoutError`. This error derives from `Git::SignaledError` and `Git::Error`.
 
-## Examples
+If the timeout value is `0` or `nil`, no timeout is enforced.
 
-Here are a bunch of examples of how to use the Ruby/Git package.
+If a method accepts a `:timeout` parameter and receives a non-nil value, that value
+overrides the global timeout. In this context, a value of `nil`, which is usually
+the default, uses the global timeout value, and a value of `0` turns off timeout
+enforcement for that method call no matter what the global value is.
 
-Ruby < 1.9 will require rubygems to be loaded.
+To set a global timeout, use the `Git.config` object:
 
 ```ruby
-require 'rubygems'
+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
 ```
 
-Require the 'git' gem.
+The global timeout can be overridden for a specific method if the method accepts a
+`:timeout` parameter:
+
 ```ruby
-require 'git'
+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::TimeoutError
 ```
 
-Git env config
+If the command takes too long, the gem raises `Git::TimeoutError`:
 
 ```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'
+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
 ```
 
-_NOTE: Another way to specify where is the `git` binary is through the environment variable `GIT_PATH`_
+## Deprecations
+
+This gem uses ActiveSupport's deprecation mechanism to report deprecation warnings.
 
-Here are the operations that need read permission only.
+You can silence deprecation warnings by adding this line to your source code:
 
 ```ruby
-g = Git.open(working_dir, :log => Logger.new(STDOUT))
-
-g.index
-g.index.readable?
-g.index.writable?
-g.repo
-g.dir
-
-g.log   # returns a Git::Log object, which is an Enumerator of Git::Commit objects
-g.log(200)
-g.log.since('2 weeks ago')
-g.log.between('v2.5', 'v2.6')
-g.log.each {|l| puts l.sha }
-g.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
-
-g.gtree(treeish)
-g.gblob(treeish)
-g.gcommit(treeish)
-
-
-commit = g.gcommit('1cc8667014381')
-
-commit.gtree
-commit.parent.sha
-commit.parents.size
-commit.author.name
-commit.author.email
-commit.author.date.strftime("%m-%d-%y")
-commit.committer.name
-commit.date.strftime("%m-%d-%y")
-commit.message
-
-tree = g.gtree("HEAD^{tree}")
-
-tree.blobs
-tree.subtrees
-tree.children # blobs and subtrees
-
-g.revparse('v2.5:Makefile')
-
-g.branches # returns Git::Branch objects
-g.branches.local
-g.current_branch
-g.branches.remote
-g.branches[:master].gcommit
-g.branches['origin/master'].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', @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|
-  puts file_diff.path
-  puts file_diff.patch
-  puts file_diff.blob(:src).contents
-end
+Git::Deprecation.behavior = :silence
+```
 
-g.worktrees # returns Git::Worktree objects
-g.worktrees.count
-g.worktrees.each do |worktree|
-  worktree.dir
-  worktree.gcommit
-  worktree.to_s
-end
+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.
 
-g.config('user.name')  # returns 'Scott Chacon'
-g.config # returns whole config hash
+If `GIT_DEPRECATION_BEHAVIOR` is set to an unsupported value, loading the gem
+raises `ArgumentError` with the accepted behavior names.
 
-# 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(
-  git_uri, destination_path,
-  :config => [
-    'core.sshCommand=ssh -i /home/user/.ssh/id_rsa',
-    'submodule.recurse=true'
-  ]
-)
+See [the Active Support Deprecation
+documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
+for more details.
 
-g.tags # returns array of Git::Tag objects
+Before upgrading the git gem to the next major version, follow the upgrade procedure
+in [UPGRADING.md](UPGRADING.md#upgrading-to-v600). It turns the warnings into errors so
+that you cannot miss one.
 
-g.show()
-g.show('HEAD')
-g.show('v2.8', 'README.md')
+For the full list of deprecated methods and their replacements, see
+[UPGRADING.md](UPGRADING.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')
-Git.ls_remote() # same as Git.ls_remote('.')
+## Platform limitations
 
-Git.default_branch('https://github.com/ruby-git/ruby-git') #=> 'master'
+### Regex metacharacters on Git for Windows
+
+On Git for Windows, git's regex engine matches **bytes** rather than characters. A
+metacharacter such as `.`, or a POSIX character class such as `[[:alpha:]]`, therefore
+never matches a whole multi-byte character. The same call matches on Linux and macOS.
+
+The failure is silent. Nothing raises, and the result is indistinguishable from a
+pattern that genuinely does not occur:
+
+```ruby
+# File content, commit message, and config value are all 'ÄPFEL sind gut'.
+# 'Ä' is two bytes in UTF-8 (C3 84), so '.' has to match both to match the character.
+
+repo.grep('^.PFEL')                              # => {} on Windows, matches elsewhere
+repo.log.grep('^.PFEL').execute.size             # =>  0 on Windows, 1 elsewhere
+repo.config_get_all('test.desc', '^.PFEL')       # => [] on Windows, matches elsewhere
 ```
 
-And here are the operations that will need to write to your git repository.
+This is a property of the regex engine git bundles on that platform, not something the
+gem sets. It is unaffected by the locale: the behavior is identical under `en_US.UTF-8`,
+`C.UTF-8`, `C`, and with no `LC_ALL` set at all. Literal (metacharacter-free) patterns
+and case-insensitive matching are unaffected on every platform.
+
+**Workaround.** Perl-compatible regular expressions do match characters on Git for
+Windows, so the surfaces that can reach a PCRE engine accept an opt-in selector:
 
 ```ruby
-g = Git.init
-  Git.init('project')
-  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)
-
-# 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
-
-g.config('user.name', 'Scott Chacon')
-g.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')
-
-# Clone can take an optional logger
-logger = Logger.new
-g = Git.clone(git_url, NAME, :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"
-
-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"
-
-g.commit('message')
-g.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)
-
-# Sign a commit using a specified gpg key
-key_id = '0A46826A'
-g.commit('message', gpg_sign: key_id)
-
-# Skip signing a commit (overriding any global gpgsign setting)
-g.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
-end
+repo.grep('^.PFEL', nil, perl_regexp: true)      # matches on every platform
+repo.log.perl_regexp.grep('^.PFEL').execute      # matches on every platform
+repo.full_log_commits(grep: '^.PFEL', perl_regexp: true)
+```
 
-g.reset # defaults to HEAD
-g.reset_hard(Git::Commit)
+Two caveats:
 
-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('master').contains?('existing_branch')
+- **PCRE is a different dialect.** Git's other modes are POSIX basic regular
+  expressions (the default) and POSIX extended regular expressions (selected
+  explicitly). Selecting PCRE is a deliberate choice by the caller, so the gem does
+  not substitute it automatically based on the host.
+- **PCRE must be compiled in.** Git for Windows and the mainstream Linux and macOS
+  packages ship it, but git built without `USE_LIBPCRE` fails with `cannot use
+  Perl-compatible regexes...`.
 
-# delete remote branch
-g.push('origin', 'remote_branch_name', force: true, delete: true)
+**There is no workaround for `git config` value patterns.** They are POSIX extended
+regular expressions with no PCRE mode, so `config_get`, `config_get_all`,
+`config_get_regexp`, `config_replace_all`, `config_unset`, and `config_unset_all` cannot
+match a metacharacter against a non-ASCII character on Git for Windows. Match on ASCII
+text or an exact value instead.
 
-g.checkout('new_branch')
-g.checkout('new_branch', new_branch: true, start_point: 'master')
-g.checkout(g.branch('new_branch'))
+`config_replace_all` deserves particular care, because there the failure is worse than
+an empty result. When the value pattern selects nothing, `git config --replace-all`
+*adds* the new value as an additional entry rather than replacing one, and exits zero:
 
-g.branch(name).merge(branch2)
-g.branch(branch2).merge  # merges HEAD with branch2
+```ruby
+# Existing value of test.desc is 'ÄPFEL sind gut'
+repo.config_replace_all('test.desc', 'NEW', '^.PFEL')
 
-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('master'))
-g.merge([branch1, branch2])
+repo.config_get_all('test.desc').map(&:value)
+# => ["NEW"]                     elsewhere, replaced as intended
+# => ["ÄPFEL sind gut", "NEW"]   on Windows, original kept and duplicate added
+```
 
-g.merge_base('branch1', 'branch2')
+So a replace can silently leave the original value in place and add a second entry beside
+it. Confirm with `config_get_all` when the key must end up single-valued.
+
+## Project policies
 
-r = g.add_remote(name, uri)  # Git::Remote
-r = g.add_remote(name, Git::Base)  # Git::Remote
+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. |
+| [Deprecation policy](#deprecation-policy) | When an API may be removed, what a deprecation warning says, and how to upgrade across a major version. |
+| [Release support policy](#release-support-policy) | Which branch releases what, and how long each major series is supported. |
+| [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. |
 
-g.remotes  # array of Git::Remotes
-g.remote(name).fetch
-g.remote(name).remove
-g.remote(name).merge
-g.remote(name).merge(branch)
+### Ruby version support policy
 
-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})
+This gem is expected to function correctly on:
 
-g.pull
-g.pull(Git::Repo, Git::Branch) # fetch and a merge
+- 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
 
-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'})
+This project intends 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)).
 
-Options:
-  :a | :annotate
-  :d
-  :f
-  :m | :message
-  :s
+### Git version support policy
 
-g.delete_tag('tag_name')
+This gem requires git version 2.28.0 or greater as specified in the gemspec. This
+requirement reflects:
 
-g.repack
+- The minimum git version necessary to support all features provided by this gem
+- A reasonable balance between supporting older systems and using modern git
+  capabilities
+- The practical limitations of testing across multiple git versions in CI
 
-g.push
-g.push(g.remote('name'))
+Git 2.28.0 was released on July 27, 2020. While this gem may work with earlier
+versions of git, compatibility with versions prior to 2.28.0 is not tested or
+guaranteed. Users on older git versions should upgrade to at least 2.28.0.
 
-# delete remote branch
-g.push('origin', 'remote_branch_name', force: true, delete: true)
+The supported git version may be increased in future major or minor releases of this
+gem as new git features are adopted or as maintaining backward compatibility becomes
+impractical. Such changes will be documented in the CHANGELOG and release notes.
 
-# push all branches to remote at one time
-g.push('origin', all: true)
+### Deprecation policy
 
-g.worktree('/tmp/new_worktree').add
-g.worktree('/tmp/new_worktree', 'branch1').add
-g.worktree('/tmp/new_worktree').remove
-g.worktrees.prune
-```
+This gem removes an API only in a major release, and only after a normal release
+deprecated it with a runtime warning and documented its replacement in
+[UPGRADING.md](UPGRADING.md). A normal release is one that is not a pre-release. The
+warning names the major release that removes the API once that is decided. Until then
+it says the API will be removed in a future major release.
+
+The recommended way to upgrade across a major version:
+
+1. Upgrade to the latest release of the major series you are on.
+2. Set `GIT_DEPRECATION_BEHAVIOR=raise` (or `Git::Deprecation.behavior = :raise`) in
+   your test suite and, if possible, staging.
+3. Fix each deprecation using the entries in [UPGRADING.md](UPGRADING.md) until the
+   suite is clean.
+4. Upgrade to the next major release.
+
+Because every deprecation warning is present in the last release of a major series,
+this procedure finds every change the next major requires. The version-specific steps
+are in [UPGRADING.md](UPGRADING.md#upgrading-to-v600). See
+[Deprecations](#deprecations) for how to configure the warnings.
+
+### Release support policy
+
+All development happens on `main`, which releases the next version of the gem,
+including the next major version. The next release from `main` is v6.0.0. Every
+further v5.x release is cut from `5.x`.
+
+Each supported previous major series is maintained on a branch named for that
+series, currently `5.x` and `4.x`. These branches receive bug fixes and security
+fixes, and backward-compatible features at the maintainers' discretion. Fixes land on
+`main` first and are backported, except a fix for a problem that exists only in a
+maintenance branch, which targets that branch directly.
+
+Support for a major series ends when the second major after it is released. v4.x is
+supported until v6.0.0 ships, and v5.x until v7.0.0.
+
+## Project announcements
+
+### 2026-08-23: v5.x deprecations and the v6.0.0 roadmap
+
+The road to v6.0.0 is now planned and public. The remaining ActiveRecord-style
+classes (`Git::Branch`, `Git::Remote`, `Git::Stash`, `Git::Worktree`,
+`Git::Object::Tag`, `Git::Status`, `Git::Author`, and their collections) will be
+deprecated during the v5.x series in favor of the immutable `*Info` value-object
+APIs. v6.0.0 will remove each deprecated class once a normal v5.x release has carried
+its deprecation warning and UPGRADING.md entry, per the
+[Deprecation policy](#deprecation-policy). v6.0.0 will not ship until every planned
+deprecation has shipped that way. v6.0.0 also raises the version floors: git ≥ 2.42.0,
+Ruby ≥ 3.4.
+
+[Issue #1717](https://github.com/ruby-git/ruby-git/issues/1717) is the living
+roadmap, tracking scope, sequencing, and status. If your code uses the classes
+above, you can start migrating now. Each deprecation names its replacement, and
+[UPGRADING.md](UPGRADING.md) carries the migration guide as releases ship.
+
+### 2026-07-28: v5.0.0 released
+
+We have published [`git v5.0.0`](https://rubygems.org/gems/git/versions/5.0.0), the
+first stable release of the v5.x series, after five public beta releases in June and
+July 2026.
 
-Some examples of more low-level index and tree operations
+**v5.0.0 is a major release with breaking changes.** See
+[UPGRADING.md](UPGRADING.md) for the complete migration guide.
+
+To install:
 
 ```ruby
-g.with_temp_index do
+gem 'git', '~> 5.0'
+```
 
-  g.read_tree(tree3) # calls self.index.read_tree
-  g.read_tree(tree1, :prefix => 'hi/')
+Or:
 
-  c = g.commit_tree('message')
-  # or #
-  t = g.write_tree
-  c = g.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
+```sh
+gem install git
+```
 
-  g.branch('branch_name').update_ref(c)
-  g.update_ref(branch, c)
+Most v4.x code requires no changes. Compatibility shims keep the old API working
+while emitting deprecation warnings that tell you what to migrate before v6.0.0.
 
-  g.with_temp_working do # new blank working directory
-    g.checkout
-    g.checkout(another_index)
-    g.commit # commits to temp_index
-  end
-end
+### 2026-01-07: AI policy introduced
 
-g.set_index('/path/to/index')
+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
+is quick to read and easy to remember, and it still sets clear expectations.
 
-g.with_index(path) do
-  # calls set_index, then switches back after
-end
+### 2025-07-09: Architectural redesign
 
-g.with_working(dir) do
-# calls set_working, then switches back after
-end
+On this date we announced an architectural redesign of the git gem. The architecture
+at the time was difficult to maintain and evolve; the redesign replaced it with a
+clearer, more testable three-layer structure of commands, parsers, and a
+`Git::Repository` facade.
 
-g.with_temp_working(dir) do
-  g.checkout_index(:prefix => dir, :path_limiter => path)
-  # do file work
-  g.commit # commits to index
-end
+**The redesign shipped in v5.0.0 and is complete.** `Git::Base` and `Git::Lib` are
+gone, along with the `g.lib` accessor. See [UPGRADING.md](UPGRADING.md) for what
+changed and how to migrate.
+
+The three documents written to plan it are kept as a historical record in
+[`archive/v5-redesign/`](archive/v5-redesign/). They describe the state of the code
+before and during the migration and are not current policy. The standards that apply
+to new code live in [`.github/skills/`](.github/skills/).
+
+1. [Analysis of the Current Architecture](archive/v5-redesign/1_architecture_existing.md):
+   a breakdown of the v4.x design and its challenges.
+2. [The Proposed Redesign](archive/v5-redesign/2_architecture_redesign.md): an overview
+   of the three-layer architecture.
+3. [Implementation Plan](archive/v5-redesign/3_architecture_implementation.md): the
+   step-by-step plan that was followed.
+
+### 2025-07-07: We now use RuboCop
+
+To improve code consistency and maintainability, the `ruby-git` project has adopted
+[RuboCop](https://rubocop.org/) as our static code analyzer and formatter. All new
+contributions must follow the style guidelines enforced by our RuboCop
+configuration.
+
+Run RuboCop from the project's Rakefile:
+
+```shell
+rake rubocop
 ```
 
-## License
+RuboCop also runs as part of the default rake task, which our continuous integration
+workflow runs.
+
+PRs with RuboCop offenses will not be merged. In 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.
+
+### 2025-06-06: Default branch rename
+
+On June 6, 2025, we renamed the default branch from `master` to `main`.
+
+Instructions for renaming your local or forked branch to match are in the gist
+[Default Branch Name
+Change](https://gist.github.com/jcouball/580a10e395f7fdfaaa4297bbe816cc7d).
+
+### 2025-05-15: We've switched to Conventional Commits
+
+The `ruby-git` project has adopted the [Conventional Commits
+standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages.
+This enables automated changelog generation and is a step toward continuous
+delivery.
+
+All commits to this repository must follow the Conventional Commits standard.
+Commits that do not follow it will fail the CI build, and PRs that include them will
+not be merged.
+
+To validate your commit messages locally before pushing them to GitHub, install the
+git `commit-msg` hook by running `bin/setup` in the project root.
 
-licensed under MIT License Copyright (c) 2008  Scott Chacon. See LICENSE for further details.
+Read more about this change in the [Commit Message Guidelines section of
+CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines).