git 5.1.0 → 5.3.0

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2008 Scott Chacon
+Copyright (c) 2008 Scott Chacon, 2020 James Couball, and the ruby-git contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -3,7 +3,7 @@
 # @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)
@@ -22,33 +22,36 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 
 - [Summary](#summary)
 - [Install](#install)
-- [Quick Start](#quick-start)
+- [Quick start](#quick-start)
 - [Examples](#examples)
-  - [Gem Configuration](#gem-configuration)
-  - [Git Configuration](#git-configuration)
+  - [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)
+- [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)
-- [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)
-  - [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)
+- [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 started by obtaining a repository object by:
+Get a repository object by:
 
 - opening an existing working copy with
   [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
@@ -57,14 +60,14 @@ Get started by obtaining a repository object by:
 - 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::Repository](https://rubydoc.info/gems/git/Git/Repository)
+[Git::Repository](https://rubydoc.info/gems/git/Git/Repository) documents the
+methods you can call on a repository object.
 
 ## 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.
+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:
 
@@ -72,21 +75,21 @@ Install the gem and add to the application's Gemfile by executing:
 bundle add git
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+If you are not using bundler to manage dependencies, install the gem by executing:
 
 ```shell
 gem install git
 ```
 
-## Quick Start
+## Quick start
 
 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`](https://rubydoc.info/gems/git/Git) module. Use this module to run non-repo
+scoped `git` commands such as `config`.
 
 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. The
-`Git::Repository` object is used to run repo-specific `git` commands such as `add`,
+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`.
 
 Clone, read status, and log:
@@ -125,7 +128,7 @@ repo.commit('initial commit')
 These examples cover configuring the gem and git itself. For the full set of
 repository operations, see [Full API](#full-api) below.
 
-### Gem Configuration
+### Gem configuration
 
 Configure the git gem:
 
@@ -141,7 +144,7 @@ Git.config.binary_path = '/usr/local/bin/git'
 Git.config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
 ```
 
-**How SSH configuration is determined:**
+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.
@@ -167,7 +170,7 @@ 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.
 
-### Git Configuration
+### Git configuration
 
 Read and set `git` configuration values (via `git config`):
 
@@ -188,21 +191,21 @@ repo.config_set('user.email', 'anotheruser@example.com')
 
 ### Full API
 
-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.
+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.
 
-## 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.
+The git gem raises only `ArgumentError` or errors that subclass `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.
+Rescue `Git::Error` to catch any runtime error raised by this gem, unless you need
+more specific error handling.
 
 ```ruby
 begin
@@ -214,27 +217,25 @@ end
 
 See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
 
-## Specifying and Handling Timeouts
+## 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.
+Set a timeout for git command line operations either globally or per method call for
+methods 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.
+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.
 
-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`.
+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`.
 
-If the timeout value is `0` or `nil`, no timeout will be enforced.
+If the timeout value is `0` or `nil`, no timeout is 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.
+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.
 
 To set a global timeout, use the `Git.config` object:
 
@@ -254,7 +255,7 @@ 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
 ```
 
-If the command takes too long, a `Git::TimeoutError` will be raised:
+If the command takes too long, the gem raises `Git::TimeoutError`:
 
 ```ruby
 begin
@@ -297,22 +298,22 @@ 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.
+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.
 
 For the full list of deprecated methods and their replacements, see
 [UPGRADING.md](UPGRADING.md).
 
-## Platform Limitations
+## Platform limitations
 
-### Regex Metacharacters on Git for Windows
+### 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
+The failure is silent. Nothing raises, and the result is indistinguishable from a
 pattern that genuinely does not occur:
 
 ```ruby
@@ -340,9 +341,10 @@ repo.full_log_commits(grep: '^.PFEL', perl_regexp: true)
 
 Two caveats:
 
-- **PCRE is a different dialect** than git's default POSIX basic/extended regular
-  expressions. Selecting it is a deliberate choice by the caller, so the gem does not
-  substitute it automatically based on the host.
+- **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...`.
@@ -353,23 +355,23 @@ regular expressions with no PCRE mode, so `config_get`, `config_get_all`,
 match a metacharacter against a non-ASCII character on Git for Windows. Match on ASCII
 text or an exact value instead.
 
-`config_replace_all` deserves particular care, because there the failure is not merely 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:
+`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:
 
 ```ruby
 # Existing value of test.desc is 'ÄPFEL sind gut'
 repo.config_replace_all('test.desc', 'NEW', '^.PFEL')
 
 repo.config_get_all('test.desc').map(&:value)
-# => ["NEW"]                     elsewhere — replaced, as intended
-# => ["ÄPFEL sind gut", "NEW"]   on Windows — original kept, duplicate added
+# => ["NEW"]                     elsewhere, replaced as intended
+# => ["ÄPFEL sind gut", "NEW"]   on Windows, original kept and duplicate added
 ```
 
 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
+## Project policies
 
 These documents set expectations for behavior, contribution workflows, AI-assisted
 changes, decision making, maintainer roles, and licensing. Please review them before
@@ -382,11 +384,13 @@ opening issues or pull requests.
 | [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. |
 
-### Ruby Version Support Policy
+### Ruby version support policy
 
 This gem is expected to function correctly on:
 
@@ -395,18 +399,18 @@ This gem is expected to function correctly on:
 - 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
+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)).
 
-### Git Version Support Policy
+### Git version support policy
 
 This gem requires git version 2.28.0 or greater as specified in the gemspec. This
 requirement reflects:
 
 - The minimum git version necessary to support all features provided by this gem
-- A reasonable balance between supporting older systems and leveraging modern git
+- A reasonable balance between supporting older systems and using modern git
   capabilities
 - The practical limitations of testing across multiple git versions in CI
 
@@ -416,16 +420,68 @@ guaranteed. Users on older git versions should upgrade to at least 2.28.0.
 
 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 clearly documented in the CHANGELOG and release
-notes.
+impractical. Such changes will be documented in the CHANGELOG and release notes.
 
-## Project Announcements
+### Deprecation policy
 
-### 2026-07-28: v5.0.0 Released
+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.
 
-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.
+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 most recent previous major series is maintained on a branch named for that
+series, currently `4.x`. It receives 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 the
+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.
 
 **v5.0.0 is a major release with breaking changes.** See
 [UPGRADING.md](UPGRADING.md) for the complete migration guide.
@@ -442,100 +498,85 @@ Or:
 gem install git
 ```
 
-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.
+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
+### 2026-01-07: AI policy introduced
 
 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
-
-The git gem is undergoing a significant architectural redesign for the upcoming
-v5.0.0 release. The current architecture has several design challenges that make it
-difficult to maintain and evolve. This redesign aims to address these issues by
-introducing a clearer, more robust, and more testable structure.
+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.
 
-We have prepared detailed documents outlining the analysis of the current
-architecture and the proposed changes. We encourage our community and contributors to
-review them:
+### 2025-07-09: Architectural redesign
 
-1. [Analysis of the Current Architecture](redesign/1_architecture_existing.md): A
-   breakdown of the existing design and its challenges.
-2. [The Proposed Redesign](redesign/2_architecture_redesign.md): An overview of the
-   new three-layered architecture.
-3. [Implementation Plan](redesign/3_architecture_implementation.md): The step-by-step
-   plan for implementing the redesign.
+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.
 
-Your feedback is welcome! Please feel free to open an issue to discuss the proposed
-changes.
+**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.
 
-> **DON'T PANIC!**
->
-> While this is a major internal refactoring, our goal is to keep the primary public
-API on the main repository object as stable as possible. Most users who rely on
-documented methods like `g.commit`, `g.add`, and `g.status` should find the
-transition to v5.0.0 straightforward.
->
-> The breaking changes will primarily affect users who have been relying on the
-internal g.lib accessor, which will be removed as part of this cleanup. For more
-details, please see the "Impact on Users" section in [the redesign
-document](redesign/2_architecture_redesign.md).
+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/).
 
-### 2025-07-07: We Now Use RuboCop
+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.
 
-To improve code consistency and maintainability, the `ruby-git` project has now
-adopted [RuboCop](https://rubocop.org/) as our static code analyzer and formatter.
+### 2025-07-07: We now use RuboCop
 
-This integration is a key part of our ongoing commitment to making `ruby-git` a
-high-quality, stable, and easy-to-contribute-to project. All new contributions will
-be expected to adhere to the style guidelines enforced by our RuboCop configuration.
+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.
 
- RuboCop can be run from the project's Rakefile:
+Run RuboCop from the project's Rakefile:
 
 ```shell
 rake rubocop
 ```
 
-RuboCop is also run  as part of the default rake task (by running `rake`) that is run
-in our Continuous Integration workflow.
+RuboCop also runs as part of the default rake task, which our continuous integration
+workflow runs.
 
-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.
+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
+If you have a problem fixing a RuboCop offense, don't be afraid to ask a
 contributor.
 
-### 2025-06-06: Default Branch Rename
+### 2025-06-06: Default branch rename
 
-On June 6th, 2025, the default branch was renamed from 'master' to 'main'.
+On June 6, 2025, we renamed the default branch from `master` to `main`.
 
-Instructions for renaming your local or forked branch to match can be found in the
-gist [Default Branch Name
+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
+### 2025-05-15: We've switched to Conventional Commits
 
-To enhance our development workflow, enable automated changelog generation, and pave
-the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional
-Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit
-messages.
+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.
 
-Going forward, all commits to this repository **MUST** adhere to the Conventional
-Commits standard. Commits not adhering to this standard will cause the CI build to
-fail. PRs will not be merged if they include non-conventional commits.
+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.
 
-A git pre-commit hook may be installed to validate your conventional commit messages
-before pushing them to GitHub by running `bin/setup` in the project root.
+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.
 
 Read more about this change in the [Commit Message Guidelines section of
-CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines)
+CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines).