git 5.0.0.beta.4 → 5.0.0

data/README.md

@@ -19,22 +19,17 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 - [Install](#install)
 - [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)
+  - [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)
-- [Upgrading from v4.x to v5.0.0](#upgrading-from-v4x-to-v500)
 - [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-07-11: v5.0.0.beta.4 Released](#2026-07-11-v500beta4-released)
-  - [2026-06-26: v5.0.0.beta.3 Released](#2026-06-26-v500beta3-released)
-  - [2026-06-25: v5.0.0.beta.2 Released](#2026-06-25-v500beta2-released)
-  - [2026-06-04: v5.0.0.beta.1 Released](#2026-06-04-v500beta1-released)
+- [Project Announcements](#project-announcements)
+  - [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)
@@ -60,6 +55,10 @@ Methods that can be called on a repository object are documented in
 
 ## Install
 
+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.
+
 Install the gem and add to the application's Gemfile by executing:
 
 ```shell
@@ -90,7 +89,7 @@ require 'git'
 
 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 }
+repo.log(5).execute.each { |c| puts c.message }
 ```
 
 Open an existing repo and commit:
@@ -116,27 +115,10 @@ repo.commit('initial commit')
 
 ## Examples
 
-Beyond the basics covered in Quick Start, these examples show the full range of
-options and variations for each operation.
-
-### Configuration
+These examples cover configuring the gem and git itself. For the full set of
+repository operations, see [Full API](#full-api) below.
 
-Configure the `git` command line:
-
-```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')
-```
+### Gem Configuration
 
 Configure the git gem:
 
@@ -178,326 +160,36 @@ 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.
 
-### Read Operations
-
-Here are the operations that need read permission only:
-
-```ruby
-repo = Git.open(working_dir, :log => Logger.new(STDOUT))
-
-repo.index            # Pathname to the index file
-repo.index.readable?  # check if index is readable
-repo.index.writable?  # check if index is writable
-repo.repo             # Pathname to the .git directory
-repo.dir              # Pathname to the working directory
-
-# ls-tree with recursion into subtrees (list files)
-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
-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')
-
-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
-
-repo.gtree(treeish)
-repo.gblob(treeish)
-repo.gcommit(treeish)
-
-
-commit = repo.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 = repo.gtree("HEAD^{tree}")
-
-tree.blobs
-tree.subtrees
-tree.children # blobs and subtrees
-
-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
-
-repo.worktrees # returns Git::Worktree objects
-repo.worktrees.count
-repo.worktrees.each do |worktree|
-  worktree.dir
-  worktree.gcommit
-  worktree.to_s
-end
-
-# 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_get('user.name')&.value  # returns 'Scott Chacon'
-repo.config_list                     # returns Array<Git::ConfigEntryInfo>
-
-# 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.
-#
-repo = Git.clone(
-  git_uri, destination_path,
-  :config => [
-    'core.sshCommand=ssh -i /home/user/.ssh/id_rsa',
-    'submodule.recurse=true'
-  ]
-)
-
-repo.tags # returns array of Git::Tag objects
-
-repo.show()
-repo.show('HEAD')
-repo.show('v2.8', 'README.md')
+### Git Configuration
 
-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('.')
-
-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.
+Read and set `git` configuration values (via `git config`):
 
 ```ruby
-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'
-repo = Git.clone(git_url)
-
-# Clone into /tmp/clone/ruby-git-clean
-name = 'ruby-git-clean'
-path = '/tmp/clone'
-repo = Git.clone(git_url, name, :path => path)
-repo.dir #=> /tmp/clone/ruby-git-clean
-
-repo.config_set('user.name', 'Scott Chacon')
-repo.config_set('user.email', 'email@email.com')
-
-# Clone can take a filter to tell the serve to send a partial clone
-repo = Git.clone(git_url, name, :path => path, :filter => 'tree:0')
-
-# Clone can control single-branch behavior (nil default keeps current git behavior)
-repo = Git.clone(git_url, name, :path => path, :depth => 1, :single_branch => false)
-
-# Clone can take an optional logger
-logger = Logger.new(STDOUT)
-repo = Git.clone(git_url, 'my-repo', :log => logger)
-
-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"
-
-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"
-
-repo.commit('message')
-repo.commit_all('message')
-
-# Sign a commit using the gpg key configured in the user.signingkey config setting
-repo.config_set('user.signingkey', '0A46826A')
-repo.commit('message', gpg_sign: true)
-
-# Sign a commit using a specified gpg key
-key_id = '0A46826A'
-repo.commit('message', gpg_sign: key_id)
-
-# Skip signing a commit (overriding any global gpgsign setting)
-repo.commit('message', no_gpg_sign: true)
-
-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
-
-repo.reset # defaults to HEAD
-repo.reset_hard(Git::Commit)
-
-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
-repo.push('origin', 'remote_branch_name', force: true, delete: true)
-
-repo.checkout('new_branch')
-repo.checkout('new_branch', new_branch: true, start_point: 'main')
-repo.checkout(repo.branch('new_branch'))
-
-repo.branch(name).merge(branch2)
-repo.branch(branch2).merge  # merges HEAD with 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])
-
-repo.merge_base('branch1', 'branch2')
-
-r = repo.remote_add(name, uri)  # Git::Remote
-r = repo.remote_add(name, other_repo)  # Git::Remote (other_repo is a Git::Repository instance)
-
-repo.remotes  # array of Git::Remotes
-repo.remote(name).fetch
-repo.remote(name).remove
-repo.remote(name).merge
-repo.remote(name).merge(branch)
-
-repo.remote_set_branches('origin', '*', add: true) # append additional fetch refspecs
-repo.remote_set_branches('origin', 'feature', 'release/*') # replace fetch refspecs
-
-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})
-
-repo.pull
-repo.pull(Git::Repo, Git::Branch) # fetch and a merge
-
-repo.tag_add('tag_name') # returns Git::Object::Tag
-repo.tag_add('tag_name', 'object_reference')
-repo.tag_add('tag_name', 'object_reference', {:options => 'here'})
-repo.tag_add('tag_name', {:options => 'here'})
-
-repo.tag_delete('tag_name')
-
-repo.repack
-
-repo.push
-repo.push(repo.remote('name'))
-
-# delete remote branch
-repo.push('origin', 'remote_branch_name', force: true, delete: true)
-
-# push all branches to remote at one time
-repo.push('origin', all: true)
+# 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)
 
-repo.worktree('/tmp/new_worktree').add
-repo.worktree('/tmp/new_worktree', 'branch1').add
-repo.worktree('/tmp/new_worktree').remove
-repo.worktrees.prune
+# 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')
 ```
 
-### Index and Tree Operations
-
-Some examples of more low-level index and tree operations
-
-```ruby
-repo.with_temp_index do
-
-  repo.read_tree(tree3) # calls self.index.read_tree
-  repo.read_tree(tree1, :prefix => 'hi/')
-
-  c = repo.commit_tree('message')
-  # or #
-  t = repo.write_tree
-  c = repo.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
-
-  repo.branch('branch_name').update_ref(c)
-  repo.update_ref(branch, c)
-
-  repo.with_temp_working do # new blank working directory
-    repo.checkout
-    repo.checkout(another_index)
-    repo.commit # commits to temp_index
-  end
-end
+### Full API
 
-repo.set_index('/path/to/index')
+Quick Start and the configuration sections above cover the most common setup. For
+the complete set of operations — reading history, diffs, branches, remotes,
+worktrees, staging, and low-level index and tree work — see the
+[`Git::Repository`](https://rubydoc.info/gems/git/Git/Repository) reference. It
+documents every method along with the object types 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.
 
-repo.with_index(path) do
-  # calls set_index, then switches back after
-end
-
-repo.with_working(dir) do
-# calls set_working, then switches back after
-end
-
-repo.with_temp_working(dir) do
-  repo.checkout_index(:prefix => dir, :path_limiter => path)
-  # do file work
-  repo.commit # commits to index
-end
-```
-
-## Errors Raised By This Gem
+## 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.
@@ -515,9 +207,7 @@ end
 
 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`.
+## Specifying and Handling Timeouts
 
 A timeout for git command line operations can be set either globally or for specific
 method calls that accept a `:timeout` parameter.
@@ -554,7 +244,7 @@ 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
+Git.clone(repo_url, timeout: 10.5)  # Timeout after 10.5 seconds raising Git::TimeoutError
 ```
 
 If the command takes too long, a `Git::TimeoutError` will be raised:
@@ -607,11 +297,6 @@ needed for the upgrade.
 For the full list of deprecated methods and their replacements, see
 [UPGRADING.md](UPGRADING.md).
 
-## Upgrading from v4.x to v5.0.0
-
-v5.0.0 is a major release with breaking changes. See
-[UPGRADING.md](UPGRADING.md) for a comprehensive migration guide.
-
 ## Project Policies
 
 These documents set expectations for behavior, contribution workflows, AI-assisted
@@ -662,107 +347,32 @@ 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.
 
-## 📢 Project Announcements 📢
+## Project Announcements
 
-### 2026-07-11: v5.0.0.beta.4 Released
+### 2026-07-28: v5.0.0 Released
 
-The architectural redesign is **feature complete** and we have published
-[`git v5.0.0.beta.4`](https://rubygems.org/gems/git/versions/5.0.0.beta.4) as our
-fourth pre-release.
+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
+spanning June–July 2026.
 
-**To try the beta**, add the pre-release version to your `Gemfile`:
-
-```ruby
-gem 'git', '~> 5.0.0.beta'
-```
-
-Or install it directly:
-
-```sh
-gem install git --pre
-```
+**v5.0.0 is a major release with breaking changes.** See
+[UPGRADING.md](UPGRADING.md) for the complete migration guide.
 
-The intent is full backward compatibility with v4.x, but given the size and scope of
-the redesign, some incompatibilities may exist. Please give the latest beta a try and
-[open an issue](https://github.com/ruby-git/ruby-git/issues) if you hit anything
-unexpected — your feedback helps us ship a solid v5.0.0.
-
-See [UPGRADING.md](UPGRADING.md) for a full list of deprecations and breaking changes.
-
-### 2026-06-26: v5.0.0.beta.3 Released
-
-The architectural redesign is approximately **93% complete** and we have published
-[`git v5.0.0.beta.3`](https://rubygems.org/gems/git/versions/5.0.0.beta.3) as our
-third pre-release.
-
-**To try the beta**, add the pre-release version to your `Gemfile`:
-
-```ruby
-gem 'git', '~> 5.0.0.beta'
-```
-
-Or install it directly:
-
-```sh
-gem install git --pre
-```
-
-The intent is full backward compatibility with v4.x, but given the size and scope of
-the redesign, some incompatibilities may exist. Please give the latest beta a try and
-[open an issue](https://github.com/ruby-git/ruby-git/issues) if you hit anything
-unexpected — your feedback helps us ship a solid v5.0.0.
-
-See [UPGRADING.md](UPGRADING.md) for a full list of deprecations and breaking changes.
-
-### 2026-06-25: v5.0.0.beta.2 Released
-
-The architectural redesign is approximately **90% complete** and we have published
-[`git v5.0.0.beta.2`](https://rubygems.org/gems/git/versions/5.0.0.beta.2) as our
-second pre-release.
-
-**To try the beta**, add the pre-release version to your `Gemfile`:
+To install:
 
 ```ruby
-gem 'git', '~> 5.0.0.beta'
+gem 'git', '~> 5.0'
 ```
 
-Or install it directly:
+Or:
 
 ```sh
-gem install git --pre
-```
-
-The intent is full backward compatibility with v4.x, but given the size and scope of
-the redesign, some incompatibilities may exist. Please give the latest beta a try and
-[open an issue](https://github.com/ruby-git/ruby-git/issues) if you hit anything
-unexpected — your feedback helps us ship a solid v5.0.0.
-
-See [UPGRADING.md](UPGRADING.md) for a full list of deprecations and breaking changes.
-
-### 2026-06-04: v5.0.0.beta.1 Released
-
-The architectural redesign is approximately **65% complete** and we have published
-[`git v5.0.0.beta.1`](https://rubygems.org/gems/git/versions/5.0.0.beta.1) as our
-first pre-release.
-
-**To try the beta**, add the pre-release version to your `Gemfile`:
-
-```ruby
-gem 'git', '~> 5.0.0.beta'
-```
-
-Or install it directly:
-
-```sh
-gem install git --pre
+gem install git
 ```
 
-The intent is full backward compatibility with 4.x, but given the size and scope of
-the redesign, some incompatibilities may exist. Please give the latest beta a try and
-[open an issue](https://github.com/ruby-git/ruby-git/issues) if you hit anything
-unexpected — your feedback helps us ship a solid 5.0.0.
-
-See [UPGRADING.md](UPGRADING.md) for a full list of deprecations and breaking changes.
+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.
 
 ### 2026-01-07: AI Policy Introduced
 

data/UPGRADING.md

@@ -9,7 +9,9 @@ to update your code when upgrading from the preceding major version.
   - [Breaking changes](#breaking-changes)
     - [`Git::Base` removed](#gitbase-removed)
     - [Return type of `Git.open`, `Git.clone`, `Git.init`, `Git.bare`](#return-type-of-gitopen-gitclone-gitinit-gitbare)
+    - [Unsupported options raise `ArgumentError`](#unsupported-options-raise-argumenterror)
     - [`Git::Lib` removed](#gitlib-removed)
+    - [`Git::Log#object` is not a path limiter](#gitlogobject-is-not-a-path-limiter)
     - [`Git::CommandLineResult` deprecated](#gitcommandlineresult-deprecated)
   - [Deprecated methods](#deprecated-methods)
     - [Facade method renames](#facade-method-renames)
@@ -45,6 +47,8 @@ For information on how to suppress or configure deprecation warnings, see the
 | `Git::Base` removed | Hard break | High for code that references it by name | Replace with `Git::Repository` (returned by `Git.open` etc.) |
 | `Git::Lib` removed | Hard break | High for `.lib.*` callers | Use the equivalent method directly on the repo object (see table below) |
 | `Git.open` etc. return `Git::Repository` (not `Git::Base`) | Hard break | Low for most callers; breaks `is_a?(Git::Base)` | Update type checks and update `be_a(Git::Base)` in tests |
+| Unsupported options now raise `ArgumentError` | Behavior change | Medium for code passing unknown or misspelled options | Check option names against the documented API |
+| `Git::Log#object` is not a path limiter | Behavior change | Medium for code that used `object(path)` to filter logs by path | Use `Git::Log#path` for path filtering |
 | `Git::CommandLineResult` deprecated | Deprecation (removed in v6.0.0) | Low; only affects code that references the constant by name | Use `Git::CommandLine::Result` instead |
 
 ---
@@ -89,6 +93,32 @@ require 'git'
 `Git.open` (e.g., `repo.commit`, `repo.status`, `repo.add`) requires no
 changes.
 
+**Monkeypatching `Git::Base` is deprecated:** v5.x includes a temporary
+compatibility shim for applications that define instance methods on `Git::Base`.
+Those methods are made available on `Git::Repository` instances, but each method
+definition emits a deprecation warning and this shim will be removed in v6.0.0.
+
+Move custom repository helpers to an application-owned extension module and
+include or prepend that module into `Git::Repository` during application setup:
+
+```ruby
+# Deprecated in v5.x and will be removed in v6.0.0
+module Git::Base
+  def worktree_clean?
+    status.changed.empty?
+  end
+end
+
+# v5.x — keep the extension in application-owned code
+module MyAppGitRepositoryExtensions
+  def worktree_clean?
+    status.changed.empty?
+  end
+end
+
+Git::Repository.include(MyAppGitRepositoryExtensions)
+```
+
 ---
 
 #### Return type of `Git.open`, `Git.clone`, `Git.init`, `Git.bare`
@@ -114,6 +144,27 @@ construct a repository object.
 
 ---
 
+#### Unsupported options raise `ArgumentError`
+
+v5.x validates options more strictly for factory methods and command APIs.
+Unknown options that were silently ignored in v4.x may now raise
+`ArgumentError`. Check option names against the documented API when upgrading,
+especially for calls that pass keyword options through helper methods or shared
+option hashes.
+
+For example, `Git.clone` supports `log:`, not `logger:`. A misspelled or
+unsupported option that v4.x ignored must be corrected:
+
+```ruby
+# v4.x — silently ignored; did not configure clone logging
+Git.clone(url, path, logger: logger)
+
+# v5.x — use the documented option name
+Git.clone(url, path, log: logger)
+```
+
+---
+
 #### `Git::Lib` removed
 
 The object returned by `Git.open`, `Git.clone`, `Git.init`, and `Git.bare` previously
@@ -211,6 +262,30 @@ helpers with no plausible external use. They have no replacement in v5.0.0:
 
 ---
 
+#### `Git::Log#object` is not a path limiter
+
+In previous 4.x releases, some uses of `Git::Log#object(path)` could appear to
+filter log output by path when combined with `#between` or other revision range
+options. This relied on ambiguous `git log` argument handling and was not the
+intended API for path filtering.
+
+In v5.x, `Git::Log#object` should be treated as a revision expression. When both
+`#object` and `#between` are specified, `#between` takes precedence. Code that
+used `#object` to limit commits to a path should use `#path` instead.
+
+```ruby
+# v4.x — ambiguous; could appear to filter commits touching this path
+git.log(500).object('cookbooks/mycookbook').between('1.0.0', 'HEAD').execute
+
+# v5.x — use #path for path filtering
+git.log(500).path('cookbooks/mycookbook').between('1.0.0', 'HEAD').execute
+
+# #object remains appropriate for revision expressions
+git.log.object('HEAD~10..HEAD').execute
+```
+
+---
+
 #### `Git::CommandLineResult` deprecated
 
 `Git::CommandLineResult` was an alias for `Git::CommandLine::Result` introduced