git 5.0.0.beta.3 → 5.0.0.beta.4

data/README.md

@@ -26,10 +26,12 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 - [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)
@@ -64,24 +66,12 @@ Install the gem and add to the application's Gemfile by executing:
 bundle add git
 ```
 
-to install version 1.x:
-
-```shell
-bundle add git --version "~> 1.19"
-```
-
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```shell
 gem install git
 ```
 
-to install version 1.x:
-
-```shell
-gem install git --version "~> 1.19"
-```
-
 ## Quick Start
 
 All functionality for this gem starts with the top-level
@@ -594,6 +584,18 @@ You can silence deprecation warnings by adding this line to your source code:
 Git::Deprecation.behavior = :silence
 ```
 
+Or by setting this environment variable before loading the gem:
+
+```sh
+GIT_DEPRECATION_BEHAVIOR=silence
+```
+
+Accepted environment variable values are the behavior names supported by your
+installed ActiveSupport version.
+
+If `GIT_DEPRECATION_BEHAVIOR` is set to an unsupported value, loading the gem
+raises `ArgumentError` with the accepted behavior names.
+
 See [the Active Support Deprecation
 documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
 for more details.
@@ -602,6 +604,14 @@ If deprecation warnings are silenced, you should reenable them before upgrading
 git gem to the next major version. This will make it easier to identify changes
 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
@@ -654,6 +664,31 @@ notes.
 
 ## 📢 Project Announcements 📢
 
+### 2026-07-11: v5.0.0.beta.4 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.
+
+**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-26: v5.0.0.beta.3 Released
 
 The architectural redesign is approximately **93% complete** and we have published

data/Rakefile

@@ -5,29 +5,11 @@ require 'rake/clean'
 # Load all .rake files from tasks and its subdirectories.
 Dir.glob('tasks/**/*.rake').each { |r| load r }
 
-desc 'Run all tests (TestUnit and RSpec)'
-task 'test-all': %i[test spec]
-
-desc 'Run all tests in parallel (TestUnit and RSpec run concurrently)'
-task 'test-all:parallel' do
-  errors = []
-  mutex = Mutex.new
-  threads = %w[test:parallel spec:parallel].map do |t|
-    Thread.new do
-      Rake::Task[t].invoke
-    rescue Exception => e # rubocop:disable Lint/RescueException
-      mutex.synchronize { errors << e }
-    end
-  end
-  threads.each(&:join)
-  raise errors.first if errors.any?
-end
-
-default_tasks = %i[test spec:unit spec:integration rubocop]
+default_tasks = %i[spec:unit spec:integration rubocop]
 default_tasks << :yard if Rake::Task.task_defined?(:yard)
 default_tasks << :build
 
-default_tasks_parallel = %w[test:parallel spec:unit:parallel spec:integration:parallel rubocop]
+default_tasks_parallel = %w[spec:unit:parallel spec:integration:parallel rubocop]
 default_tasks_parallel << :yard if Rake::Task.task_defined?(:yard)
 default_tasks_parallel << :build
 
@@ -54,7 +36,7 @@ module Rake
       # rake rubocop      # => do not output the task name
       # rake rubocop yard # => output task name for rubocop and yard
       top_level_tasks = Rake.application.top_level_tasks
-      box("Rake task: #{name}") unless top_level_tasks.length == 1 && name == top_level_tasks[0]
+      box("rake #{name}") unless top_level_tasks.length == 1 && name == top_level_tasks[0]
       original_execute(args)
     end
 

data/UPGRADING.md

@@ -1,83 +1,165 @@
 # Upgrading the `git` Gem
 
-> **⚠️ Work in progress — v5.0.0 is currently in beta.**
-> This document is updated incrementally as development continues and is not yet
-> complete. If you encounter a compatibility problem not covered here, please
-> [open an issue](https://github.com/ruby-git/ruby-git/issues).
+This document covers breaking changes and migration steps when upgrading the
+`git` gem to a new major version. Each section describes what changed and how
+to update your code when upgrading from the preceding major version.
 
-- [Upgrading from v4.x to v5.x](#upgrading-from-v4x-to-v5x)
+- [Upgrading to v5.x](#upgrading-to-v5x)
   - [Overview](#overview)
-  - [`Git::Lib` removal](#gitlib-removal)
-    - [Methods with a direct replacement](#methods-with-a-direct-replacement)
-    - [Methods with no replacement](#methods-with-no-replacement)
-    - [Internal plumbing methods (no replacement)](#internal-plumbing-methods-no-replacement)
+  - [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)
+    - [`Git::Lib` removed](#gitlib-removed)
+    - [`Git::CommandLineResult` deprecated](#gitcommandlineresult-deprecated)
   - [Deprecated methods](#deprecated-methods)
+    - [Facade method renames](#facade-method-renames)
+    - [v4.x-style configuration methods](#v4x-style-configuration-methods)
+    - [`Git` module mixin deprecations](#git-module-mixin-deprecations)
 
-## Upgrading from v4.x to v5.x
+## Upgrading to v5.x
 
 ### Overview
 
-The primary goal of v5.0.0 is to move everyone onto a new internal architecture
-while keeping the existing v4.x API working. The vast majority of v4.x code
-requires no changes to run on v5.x.
+v5.0.0 delivers a new internal architecture while keeping the v4.x API working
+for the vast majority of users. Most v4.x code requires **no changes** to run on
+v5.x.
 
-The new architecture delivered in v5.0.0 is the foundation for future API
-improvements across upcoming major releases.
+The new architecture introduces a layered design (`Git::Commands`,
+`Git::Repository`, and associated parsers). Compatibility shims — deprecated
+forwarding methods that map old call patterns to the new API — ensure that v4.x
+code continues to work. These shims emit deprecation warnings that tell you
+exactly what to change and what will be eliminated in v6.0.0.
 
-The new architecture introduces a layered design (`Git::Commands`, `Git::Repository`,
-and associated parsers). Compatibility shims — deprecated forwarding methods that map
-old call patterns to the new API — ensure that v4.x code continues to work. These
-shims emit deprecation warnings that tell you exactly what to change and what will be
-eliminated in a future major release (most likely v6.0.0).
+Hard breaks are limited to a small number of things that had no safe migration
+path. These are described in the [Breaking changes](#breaking-changes) section,
+followed by [Deprecated methods](#deprecated-methods) that still work in v5.x
+but are removed in v6.0.0.
 
-Hard breaks are limited to a small number of methods that had no safe
-migration path — these are described in detail below.
-
-Our intent is to make upgrading to v5.x as smooth as possible. For information
-on how to suppress or configure deprecation warnings, see the
+For information on how to suppress or configure deprecation warnings, see the
 [Deprecations](README.md#deprecations) section of the README.
 
+**Changes at a glance:**
+
+| Change | Type | Impact | Action required |
+|--------|------|--------|-----------------|
+| `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 |
+| `Git::CommandLineResult` deprecated | Deprecation (removed in v6.0.0) | Low; only affects code that references the constant by name | Use `Git::CommandLine::Result` instead |
+
 ---
 
-### `Git::Lib` removal
+### Breaking changes
 
-The object returned by `Git.open`, `Git.clone`, and `Git.init` — the object
-you call methods on to interact with your repository — inadvertently exposed
-a `#lib` method that gave access to `Git::Lib`, the gem's internal
-implementation class. This was never intended to be public; it was an
-implementation detail that leaked out. `Git::Lib` is removed in v5.0.0.
+#### `Git::Base` removed
 
-Calling `#lib` on the repository object returns `self` with a deprecation
-warning so that existing `g.lib.*` call chains continue to work during
-migration. The `#lib` method itself is removed in v6.0.0. Calls to methods
-that have no replacement (see below) raise `NoMethodError` with an
-informative message.
+`Git::Base` — the class previously returned by `Git.open`, `Git.clone`,
+`Git.init`, and `Git.bare` — is removed in v5.0.0. The replacement is
+`Git::Repository`, which is returned by all four entry points and exposes the
+same public API.
 
-Most public behavior previously accessible via `g.lib.*` is available
-directly on the repository object (i.e., `g.*`). A small number of methods
-have no replacement — see below. The sections below list every affected method.
+**Code that must be updated:**
 
-#### Methods with a direct replacement
+```ruby
+# v4.x — explicit Git::Base reference (raises NameError in v5.x)
+repo = Git::Base.new(working_directory: '/path/to/repo')
 
-All of the following `g.lib.*` calls work in v5.x but emit a deprecation
-warning. Migrate to the replacement shown to silence the `g.lib.*` deprecation
-warning; note that some replacements are themselves deprecated — see the table
-notes for the final migration target.
+# v5.x — use the entry-point methods; do not construct Git::Repository directly
+repo = Git.open('/path/to/repo')
+```
 
-| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
-|---------------------------------------------------|-------------|
-| `g.lib.config_get(name)` | `g.config(name)` |
-| `g.lib.config_list` | `g.config` |
-| `g.lib.config_set(name, value)` | `g.config(name, value)` |
+```ruby
+# v4.x — type-checking against Git::Base (raises NameError in v5.x because Git::Base is removed)
+raise unless repo.is_a?(Git::Base)
+
+# v5.x — check against Git::Repository
+raise unless repo.is_a?(Git::Repository)
+```
+
+```ruby
+# v4.x — requiring the internal file (raises LoadError in v5.x)
+require 'git/base'
+
+# v5.x — the public entry point is git itself; no internal require needed
+require 'git'
+```
+
+**Public API is preserved:** `Git::Repository` provides every method that
+`Git::Base` did. Code that simply calls methods on the object returned by
+`Git.open` (e.g., `repo.commit`, `repo.status`, `repo.add`) requires no
+changes.
+
+---
+
+#### Return type of `Git.open`, `Git.clone`, `Git.init`, `Git.bare`
+
+`Git.open`, `Git.clone`, `Git.init`, and `Git.bare` now return
+`Git::Repository` instead of `Git::Base`.
+
+For most callers this is transparent — the returned object responds to the same
+methods. Code that explicitly checks `is_a?(Git::Base)` or `be_a(Git::Base)` in
+tests must be updated:
+
+```ruby
+# v4.x
+expect(Git.open(repo_path)).to be_a(Git::Base)
+
+# v5.x
+expect(Git.open(repo_path)).to be_a(Git::Repository)
+```
+
+`Git::Repository` does not define `.open`, `.bare`, `.clone`, or `.init` class
+methods. Always use `Git.open`, `Git.bare`, `Git.clone`, and `Git.init` to
+construct a repository object.
+
+---
+
+#### `Git::Lib` removed
+
+The object returned by `Git.open`, `Git.clone`, `Git.init`, and `Git.bare` previously
+exposed a `#lib` method that gave access to `Git::Lib`, the gem's internal
+implementation class. `Git::Lib` is removed in v5.0.0.
+
+In v5.x, calling `#lib` on a repo object returns `self` with a deprecation
+warning. This means `g.lib.some_method(args)` is forwarded to
+`g.some_method(args)` — but only if `some_method` exists on `Git::Repository`.
+Methods that were unique to `Git::Lib` and have no counterpart on
+`Git::Repository` raise `NoMethodError` immediately. The `#lib` method itself
+is removed in v6.0.0.
+
+Most public behavior previously accessible via `g.lib.*` is available directly
+on the repository object (`g.*`). See the tables below for every affected
+method.
+
+##### Methods that work via the `#lib` shim (with deprecation warning)
+
+The following v4.x `g.lib.*` call shapes are forwarded to their `Git::Repository`
+counterpart by the `#lib → self` shim. They emit a deprecation warning; migrate
+to the replacement shown to silence it.
+
+> **Note — config return type change:** `g.lib.config_get(name)` returned a
+> `String`; `g.lib.config_list` returned a `Hash`.
+> The v5.x replacements `config_get` and `config_list` return
+> `Git::ConfigEntryInfo` and `Array<Git::ConfigEntryInfo>` respectively — richer
+> objects that expose `.value` (the String), `.key`, `.scope`, and `.origin`.
+>
+> If you only need the String value:
+> - `g.config_get(name)&.value` → replaces `g.lib.config_get(name)`
+> - `g.config_list.to_h { |e| [e.key, e.value] }` → replaces `g.lib.config_list`
+>
+> If your code was using the v4.x public `g.config(name)` API (not `g.lib.*`),
+> that deprecated bridge still returns a `String` in v5.x and continues to work
+> until v6.0.0.
+
+| v4.x call | Replacement in v5.x |
+|-----------|---------------------|
+| `g.lib.config_get(name)` | `g.config_get(name)` — returns `Git::ConfigEntryInfo`; use `.value` for the String |
+| `g.lib.config_list` | `g.config_list` — returns `Array<Git::ConfigEntryInfo>` |
+| `g.lib.config_set(name, value)` | `g.config_set(name, value)` |
 | `g.lib.git_version` | `g.git_version` |
-| `g.lib.global_config_get(name)` | `g.global_config(name)` |
-| `g.lib.global_config_list` | `g.global_config` |
-| `g.lib.global_config_set(name, value)` | `g.global_config(name, value)` |
-| `g.lib.parse_config(file)` | `g.config(file: file)` |
-| `g.lib.stash_list` | `g.stash_list` *(also deprecated — use `g.stashes_all`)* |
+| `g.lib.stash_list` | `g.stashes_all` |
 | `g.lib.unmerged` | `g.unmerged` |
 | `g.lib.change_head_branch(name)` | `g.change_head_branch(name)` |
-| `g.lib.branch_current` | `g.current_branch` |
 | `g.lib.ls_remote(location, opts)` | `g.ls_remote(location, opts)` |
 | `g.lib.current_branch_state` | `g.current_branch_state` |
 
@@ -89,13 +171,27 @@ notes for the final migration target.
 > (`Git::Lib::HeadState.new(:active, 'main')`), update to keyword construction:
 > `Git::Repository::Branching::HeadState.new(state: :active, name: 'main')`.
 
-#### Methods with no replacement
+##### Methods that raise `NoMethodError` in v5.x
+
+These `Git::Lib` method names have no counterpart on `Git::Repository`, so
+`g.lib.method_name` raises `NoMethodError` even in v5.x (the `#lib → self`
+shim cannot forward them). Update call sites directly:
+
+| v4.x call | Replacement in v5.x |
+|-----------|---------------------|
+| `g.lib.global_config_get(name)` | `g.config_get(name, global: true)` |
+| `g.lib.global_config_list` | `g.config_list(global: true)` |
+| `g.lib.global_config_set(name, value)` | `g.config_set(name, value, global: true)` |
+| `g.lib.branch_current` | `g.current_branch` |
+| `g.lib.parse_config(file)` | `g.config_list(file: file)` |
+
+##### Methods with no replacement
 
 | v4.x call | Notes |
 |-----------|-------|
 | `g.lib.list_files(ref_dir)` | Walked `.git/refs/` directly. Use `g.branches`, `g.tags`, or `g.remotes` instead. |
 
-#### Internal plumbing methods (no replacement)
+##### Internal plumbing methods (no replacement)
 
 The following methods were technically public on `Git::Lib` but are internal
 helpers with no plausible external use. They have no replacement in v5.0.0:
@@ -115,27 +211,80 @@ helpers with no plausible external use. They have no replacement in v5.0.0:
 
 ---
 
+#### `Git::CommandLineResult` deprecated
+
+`Git::CommandLineResult` was an alias for `Git::CommandLine::Result` introduced
+for backward compatibility. It is deprecated in v5.0.0 and removed in v6.0.0.
+Accessing `Git::CommandLineResult` emits a deprecation warning.
+
+```ruby
+# v4.x
+result.is_a?(Git::CommandLineResult)
+
+# v5.x
+result.is_a?(Git::CommandLine::Result)
+```
+
+This change is only relevant if your code references `Git::CommandLineResult`
+by name (typically in type checks or documentation). Code that simply uses the
+result object returned by git commands is unaffected.
+
+---
+
 ### Deprecated methods
 
-The following methods are available in v5.x with deprecation warnings and
-are removed in v6.0.0.
+The following methods are available in v5.x with deprecation warnings and are
+removed in v6.0.0. Migrate to the replacement shown to silence the warnings.
+
+#### Facade method renames
+
+Five methods were renamed to follow the project's `noun_verb` naming convention.
+The old names continue to work but emit deprecation warnings:
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
-|---------------------------------------------------|-------------|
-| `g.config_get(name)` | `g.config(name)` |
-| `g.config_list` | `g.config` |
-| `g.config_set(name, value)` | `g.config(name, value)` |
-| `g.global_config_get(name)` | `g.global_config(name)` |
-| `g.global_config_list` | `g.global_config` |
-| `g.global_config_set(name, value)` | `g.global_config(name, value)` |
-| `g.parse_config(file)` | `g.config(file: file)` |
-| `g.stash_list` | `g.stashes_all` |
+|-----------------------------------------------------|-------------|
 | `g.add_remote(name, url, opts)` | `g.remote_add(name, url, opts)` |
 | `g.remove_remote(name)` | `g.remote_remove(name)` |
 | `g.set_remote_url(name, url)` | `g.remote_set_url(name, url)` |
 | `g.add_tag(name, ...)` | `g.tag_add(name, ...)` |
 | `g.delete_tag(name)` | `g.tag_delete(name)` |
-| `include Git; config(...)` | `Git.open(Dir.pwd).config(...)` |
-| `include Git; global_config(...)` | `Git.global_config(...)` |
+
+#### v4.x-style configuration methods
+
+The v4.x `config` and `global_config` methods accepted varying argument shapes
+to read, write, or list configuration. These are replaced by separate,
+purpose-named methods.
+
+> **Return type change:** The v4.x `g.config(name)` returned a `String` and
+> `g.config` returned a `Hash`. The v5.x replacements `config_get` and
+> `config_list` return `Git::ConfigEntryInfo` and `Array<Git::ConfigEntryInfo>`
+> respectively. Use `.value` to get the String value:
+> - `g.config_get(name)&.value` → String or nil
+> - `g.config_list.to_h { |e| [e.key, e.value] }` → Hash (key → value)
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `g.config(name)` | `g.config_get(name)` — returns `Git::ConfigEntryInfo`; use `.value` for the String |
+| `g.config` | `g.config_list` — returns `Array<Git::ConfigEntryInfo>` |
+| `g.config(name, value)` | `g.config_set(name, value)` |
+| `g.global_config(name)` | `g.config_get(name, global: true)` |
+| `g.global_config` | `g.config_list(global: true)` |
+| `g.global_config(name, value)` | `g.config_set(name, value, global: true)` |
+| `g.parse_config(file)` | `g.config_list(file: file)` |
+| `g.stash_list` | `g.stashes_all` |
+
+#### `Git` module mixin deprecations
+
+Extending or including the `Git` module to call `config` and `global_config`
+as bare methods is deprecated:
+
+| Deprecated usage | Replacement |
+|-----------------|-------------|
+| `include Git; config(name)` | `Git.open(Dir.pwd).config_get(name)` |
+| `include Git; config(name, value)` | `Git.open(Dir.pwd).config_set(name, value)` |
+| `include Git; config` | `Git.open(Dir.pwd).config_list` |
+| `include Git; global_config(name)` | `Git.config_get(name, global: true)` |
+| `include Git; global_config(name, value)` | `Git.config_set(name, value, global: true)` |
+| `include Git; global_config` | `Git.config_list(global: true)` |
 
 ---

data/docker/test/Dockerfile

@@ -0,0 +1,32 @@
+FROM ruby
+
+WORKDIR /ruby-git
+
+
+ADD Gemfile git.gemspec ./
+ADD lib/git/version.rb ./lib/git/version.rb
+
+# `git.gemspec`'s `spec.files` shells out to `git ls-files`, which Bundler
+# evaluates below via the Gemfile's `gemspec` directive. Rather than relying
+# on the host's `.git` (which, for a build context copied from a linked git
+# worktree, is a file pointing at an absolute host path that doesn't exist
+# in the image — breaking every git command with "fatal: not a git
+# repository"), always initialize a throwaway repo scoped to the image. This
+# also keeps the image self-contained and avoids ever copying the
+# (potentially large) host `.git` directory in (see `.dockerignore`). A
+# second commit is added below once the full source tree is present, so the
+# final file list is complete.
+RUN git init -q && \
+    git -c user.email=docker@example.com -c user.name=docker add -A && \
+    git -c user.email=docker@example.com -c user.name=docker commit -q -m 'Throwaway repo for Docker test run'
+
+RUN bundle install
+
+ADD . .
+
+# Refresh the throwaway repo now that the full source tree is present, so
+# `git ls-files` reflects every file for `rake build`'s `spec.files`.
+RUN git -c user.email=docker@example.com -c user.name=docker add -A && \
+    git -c user.email=docker@example.com -c user.name=docker commit -q -m 'Add full source' --allow-empty
+
+ENTRYPOINT ["bundle", "exec", "rake", "default"]

data/git.gemspec

@@ -37,8 +37,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'create_github_release', '~> 2.1'
   spec.add_development_dependency 'fuubar', '~> 2.5'
   spec.add_development_dependency 'main_branch_shared_rubocop_config', '~> 0.1'
-  spec.add_development_dependency 'minitar', '~> 1.1'
-  spec.add_development_dependency 'mocha', '~> 2.8'
   spec.add_development_dependency 'parallel_tests', '~> 5.6'
   spec.add_development_dependency 'rake', '~> 13.3'
   spec.add_development_dependency 'rspec', '~> 3.13'
@@ -46,7 +44,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov', '~> 0.22'
   spec.add_development_dependency 'simplecov-lcov', '~> 0.9'
   spec.add_development_dependency 'simplecov-rspec', '~> 0.4'
-  spec.add_development_dependency 'test-unit', '~> 3.7'
 
   if RUBY_ENGINE == 'truffleruby' && Gem::Version.new(RUBY_ENGINE_VERSION) < Gem::Version.new('34.0.0')
     # i18n 1.15+ uses Fiber.[] (Ruby 3.2 Fiber storage) which TruffleRuby < 34.0.0 does not implement
@@ -58,7 +55,9 @@ Gem::Specification.new do |spec|
     spec.add_development_dependency 'redcarpet', '~> 3.6'
     spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
     spec.add_development_dependency 'yard_example_test', '~> 0.2', '>= 0.2.1'
-    spec.add_development_dependency 'yardstick', '~> 0.9'
+
+    # yard-lint requires Ruby >= 3.3, so it is only installed on Ruby 3.3+.
+    spec.add_development_dependency 'yard-lint', '~> 1.8' if Gem.ruby_version >= Gem::Version.new('3.3.0')
   end
 
   # Specify which files should be added to the gem when it is released.

data/lib/git/author.rb

@@ -2,9 +2,28 @@
 
 module Git
   # An author in a Git commit
+  #
+  # @api public
+  #
   class Author
-    attr_accessor :name, :email, :date
+    # @return [String, nil] the author's name
+    attr_accessor :name
 
+    # @return [String, nil] the author's email
+    attr_accessor :email
+
+    # @return [Time, nil] the date the change was authored (author date, not committer date)
+    attr_accessor :date
+
+    # Initializes a new Author object from a string
+    #
+    # @example
+    #   Git::Author.new("John Doe <john.doe@example.com> 1627849923 +0200")
+    #
+    # @param author_string [String] the author string
+    #
+    # @return [void]
+    #
     def initialize(author_string)
       return unless (m = /(.*?) <(.*?)> (\d+) (.*)/.match(author_string))
 

data/lib/git/branch.rb

@@ -139,17 +139,37 @@ module Git
     # Archives this branch and writes the result to a file
     #
     # @example Archive to a tar file
-    #   git.branch('main').archive('/tmp/main.tar')
+    #   git.branch('main').archive('/tmp/main.tar', format: 'tar')
     #
     # @example Archive to a zip file
     #   git.branch('main').archive('/tmp/main.zip', format: 'zip')
     #
+    # @example Archive a remote branch to a tgz file
+    #   git.remote('origin').branch('main').archive('/tmp/main.tgz', format: 'tgz')
+    #
     # @param file [String] path to the destination archive file
     #
     # @param opts [Hash] archive options (see {Git::Repository#archive})
     #
+    # @option opts [String] :format ('zip') archive format for this wrapper:
+    #   `'tar'`, `'zip'`, or `'tgz'`
+    #
+    # @option opts [String] :prefix (nil) prefix prepended to every filename
+    #   in the archive
+    #
+    # @option opts [String] :path (nil) path within the tree to include in the
+    #   archive
+    #
+    # @option opts [String] :remote (nil) retrieve the archive from a remote
+    #   repository
+    #
+    # @option opts [Boolean, nil] :add_gzip (nil) apply gzip compression after
+    #   writing the archive; set automatically when `format: 'tgz'` is given
+    #
     # @return [String] the path to the written archive file
     #
+    # @raise [ArgumentError] when archive options or destination path are invalid
+    #
     # @raise [Git::FailedError] if `git archive` fails
     #
     def archive(file, opts = {})
@@ -175,14 +195,14 @@ module Git
     #
     # @param message [String] commit message used when the block returns truthy
     #
-    # @yield Executes the block with this branch checked out
-    #
-    # @yieldreturn [Object] return a truthy value to commit all changes, a falsy value to hard-reset
-    #
     # @return [String] git's stdout from the final checkout back to the original branch
     #
     # @raise [Git::FailedError] if any of the underlying git operations (checkout, commit, reset) fail
     #
+    # @yield Executes the block with this branch checked out
+    #
+    # @yieldreturn [Object] return a truthy value to commit all changes, a falsy value to hard-reset
+    #
     def in_branch(message = 'in branch work')
       old_current = branch_repository.current_branch
       checkout
@@ -327,7 +347,7 @@ module Git
     #
     # @param commit [String] the commit SHA to point this branch at
     #
-    # @return [Git::CommandLineResult] the result of calling `git update-ref`
+    # @return [Git::CommandLine::Result] the result of calling `git update-ref`
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #