git 5.7.1 → 6.0.0

data/README.md

@@ -15,10 +15,12 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 [![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.
+> **v6.0.0 is released.** It is a major release that removes the APIs deprecated
+> during v5.x, raises the minimum Ruby version to 3.3 and the minimum git version
+> to 2.43.0, and changes a few behaviors that had no deprecation path. See
+> [Upgrading to v6.x](UPGRADING.md#upgrading-to-v6x) for the migration guide and
+> [CHANGELOG.md](CHANGELOG.md) for full release notes. v5.x continues to receive
+> fixes from the `5.x` branch.
 
 - [Summary](#summary)
 - [Install](#install)
@@ -38,6 +40,8 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
   - [Deprecation policy](#deprecation-policy)
   - [Release support policy](#release-support-policy)
 - [Project announcements](#project-announcements)
+  - [2026-09-04: v5.x releases move to the 5.x branch](#2026-09-04-v5x-releases-move-to-the-5x-branch)
+  - [2026-09-04: Retired branches deleted](#2026-09-04-retired-branches-deleted)
   - [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)
@@ -66,7 +70,7 @@ 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
+2.43.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:
@@ -146,12 +150,12 @@ Git.config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
 
 How SSH configuration is determined:
 
-- If `git_ssh` is not specified in the API call, the global config (`Git.configure {
-  |c| c.git_ssh = ... }`) is used.
-- If `git_ssh: nil` is specified, SSH is disabled for that instance (no SSH key or
-  script will be used).
-- If `git_ssh` is a non-empty string, it is used for that instance (overriding the
-  global config).
+- If the API call does not specify `git_ssh`, the gem uses the global config
+  (`Git.configure { |c| c.git_ssh = ... }`).
+- If the call specifies `git_ssh: nil`, the gem disables SSH for that instance and
+  uses no SSH key or script.
+- If `git_ssh` is a non-empty string, the gem uses it for that instance instead of
+  the global config.
 
 You can also specify a custom SSH script on a per-repository basis:
 
@@ -167,8 +171,8 @@ git = Git.clone('git@github.com:user/repo.git', 'local-dir',
 git = Git.init('new-repo', git_ssh: 'ssh -i /path/to/private_key')
 ```
 
-This is especially useful in multi-threaded applications where different repositories
-require different SSH credentials.
+This matters in multi-threaded applications where different repositories need
+different SSH credentials.
 
 ### Git configuration
 
@@ -196,46 +200,15 @@ 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::BranchInfo`, and `Git::WorktreeInfo`), so you can follow the links from a method
+to the full API of its result.
 
 ## Errors raised by this gem
 
-Errors the git gem raises deliberately are either `ArgumentError` or a subclass of
-`Git::Error`, with one exception: with the `raise` behavior described under
-[Deprecations](#deprecations), a deprecated call raises
-`ActiveSupport::DeprecationException`, which is intentionally not a `Git::Error` so a
-broad rescue cannot hide a deprecation your code opted to treat as fatal. The errors
-described below come from Ruby's standard library and are not converted.
-
-The gem's own filesystem operations, such as reading a `.git` pointer file,
-creating a temporary file, or changing directory, do not convert operating system
-errors. These can be raised as a bare `SystemCallError` (for example `Errno::ENOENT`
-or `Errno::EACCES`) rather than `Git::Error`. Gzip compression in `archive` can
-likewise raise a `Zlib::Error`. Rescue `SystemCallError` and `Zlib::Error` alongside
-`Git::Error` if your code needs to handle them.
-
-The affected methods are `Git.open` when the `.git` file is a gitdir pointer or the
-path is relative, `Git.init`, `Git.bare`, and `Git.clone` when the path is relative,
-`Git.export`, and these `Git::Repository` methods: `#chdir`, `#with_index`,
-`#with_working`, `#with_temp_index`, `#with_temp_working`, `#set_index`,
-`#set_working`, `#cat_file_contents` in block form, `#each_conflict`, `#conflicts`,
-`#archive` (including the gzip step), `#repo_size`, and `#tag_sha` when it reads a
-loose ref.
-
-Any method that captures git output can also raise
-`Encoding::ConverterNotFoundError` when the output contains a line whose detected
-encoding, such as UTF-7, has no Ruby converter.
-
-Starting with v6.0.0, the filesystem and gzip errors are raised as `Git::Error`
-with the original error available through `cause`, except that `#tag_sha` falls
-back to `git show-ref` instead of raising. Lines with no Ruby converter are
-scrubbed instead of raising.
-
-Rescue `Git::Error` to catch the runtime errors this gem raises itself, and add
-`SystemCallError`, `Zlib::Error`, and `Encoding::ConverterNotFoundError` where the
-paragraphs above say they can escape. Rescue a more specific subclass when you need
-finer-grained handling.
+The git gem raises only `ArgumentError` or errors that subclass `Git::Error`.
+
+Rescue `Git::Error` to catch any runtime error raised by this gem, unless you need
+more specific error handling.
 
 ```ruby
 begin
@@ -245,6 +218,26 @@ rescue Git::Error => e
 end
 ```
 
+Operating system errors from the gem's own filesystem operations, such as reading
+a `.git` pointer file or creating a temporary file, are raised as `Git::Error`.
+The original `SystemCallError` is available through `cause`:
+
+```ruby
+begin
+  repo = Git.open('/path/to/repo')
+rescue Git::Error => e
+  puts e.cause.class if e.cause.is_a?(SystemCallError) #=> Errno::EACCES
+end
+```
+
+The promise covers errors the gem raises from its own operations. Two things pass
+through unchanged. An error raised by a block your code passes to a method such as
+`chdir` or `with_temp_working` is your error, and the gem does not relabel it. And
+with the `raise` behavior described under [Deprecation policy](#deprecation-policy), a
+deprecated call raises `ActiveSupport::DeprecationException`, which is intentionally
+not a `Git::Error` so a broad rescue cannot hide a deprecation your code opted to
+treat as fatal.
+
 See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
 
 ## Specifying and handling timeouts
@@ -252,13 +245,11 @@ See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information
 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 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, the gem kills it with the `SIGKILL` signal and raises a
-`Git::TimeoutError`. This error derives from `Git::SignaledError` and `Git::Error`.
+The timeout is the number of seconds a `git` command may run before the gem sends
+it `SIGKILL`. It must be a real, non-negative `Numeric`. When a command times out,
+the gem kills it and raises `Git::TimeoutError`, which derives from
+`Git::SignaledError` and `Git::Error`. The gem may hang if the `git` command does
+not terminate after receiving `SIGKILL`.
 
 If the timeout value is `0` or `nil`, no timeout is enforced.
 
@@ -292,7 +283,7 @@ begin
   Git.clone(repo_url, timeout: 10)
 rescue Git::TimeoutError => e
   e.result.tap do |r|
-    r.class #=> Git::CommandLineResult
+    r.class #=> Git::CommandLine::Result
     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
@@ -321,6 +312,17 @@ GIT_DEPRECATION_BEHAVIOR=silence
 Accepted environment variable values are the behavior names supported by your
 installed ActiveSupport version.
 
+A deprecated method warns on every call, so a call site inside a loop produces one
+warning per iteration. The gem does not deduplicate warnings. To quiet one call site
+without hiding other deprecations, wrap it in `Git::Deprecation.silence`:
+
+```ruby
+Git::Deprecation.silence { repo.set_index(index_file) }
+```
+
+Prefer this over setting the behavior to `silence` globally, which also hides the
+warnings for deprecations added in later releases.
+
 If `GIT_DEPRECATION_BEHAVIOR` is set to an unsupported value, loading the gem
 raises `ArgumentError` with the accepted behavior names.
 
@@ -329,7 +331,7 @@ documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.htm
 for more details.
 
 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
+in [UPGRADING.md](UPGRADING.md#upgrading-to-v6x). It turns the warnings into errors so
 that you cannot miss one.
 
 For the full list of deprecated methods and their replacements, see
@@ -361,7 +363,7 @@ gem sets. It is unaffected by the locale: the behavior is identical under `en_US
 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:
+Windows, so the methods that can reach a PCRE engine accept an opt-in selector:
 
 ```ruby
 repo.grep('^.PFEL', nil, perl_regexp: true)      # matches on every platform
@@ -426,8 +428,18 @@ This gem is expected to function correctly on:
 
 - All [non-EOL versions](https://www.ruby-lang.org/en/downloads/branches/) of the MRI
   Ruby on Mac, Linux, and Windows
-- The latest version of JRuby 9.4+ on Linux
-- The latest version of TruffleRuby 24+ on Linux
+- JRuby and TruffleRuby on Linux, starting from the earliest release whose Ruby
+  compatibility target is at or above the oldest supported MRI version, unless a
+  newer release is otherwise needed (for example, when a release does not
+  implement a feature the gem depends on)
+
+Consult the CI build matrix in
+[`.github/workflows/continuous_integration.yml`](.github/workflows/continuous_integration.yml)
+for the exact JRuby and TruffleRuby versions tested. Newer releases of each engine
+are expected to work but are not tested.
+
+Because the JRuby and TruffleRuby floors derive from the MRI floor, they move
+whenever the oldest supported MRI version changes.
 
 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
@@ -436,21 +448,17 @@ supports subprocess status reporting on JRuby for Windows (see
 
 ### 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 using modern git
-  capabilities
-- The practical limitations of testing across multiple git versions in CI
+This gem requires git 2.43.0 or later, as the gemspec declares. The floor weighs the
+git features the gem depends on, the systems users still run, and the git versions
+CI can test.
 
-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.
+Git 2.43.0 was released on November 20, 2023. The gem may work with an older git,
+but the project does not test or support versions before 2.43.0. Users on an older
+git should upgrade to at least 2.43.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 documented in the CHANGELOG and release notes.
+A later major or minor release may raise the floor when the gem adopts a newer git
+feature or when keeping compatibility with an old git becomes impractical. The
+CHANGELOG and release notes document each such change.
 
 ### Deprecation policy
 
@@ -467,12 +475,16 @@ The recommended way to upgrade across a major version:
    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.
+4. Work through the changes that a clean run does not catch, listed in that major's
+   section of [UPGRADING.md](UPGRADING.md).
+5. 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.
+steps 2 and 3 find every call to a deprecated API. A major release may also change a
+behavior that had no deprecation path, such as the return type of a method that
+keeps its name; step 4 covers those. The version-specific steps are in
+[UPGRADING.md](UPGRADING.md#upgrading-to-v6x). See [Deprecations](#deprecations)
+for how to configure the warnings.
 
 ### Release support policy
 
@@ -491,21 +503,47 @@ supported until v6.0.0 ships, and v5.x until v7.0.0.
 
 ## Project announcements
 
+### 2026-09-04: v5.x releases move to the `5.x` branch
+
+On September 4, 2026, we created the `5.x` branch from v5.4.1. Every further v5.x
+release is cut from that branch, and the next release from `main` is v6.0.0. Nothing
+changes for users of the gem: v5.x continues to receive bug fixes and security fixes
+per the [Release support policy](#release-support-policy), and v4.x is supported
+until v6.0.0 ships.
+
+For contributors, fixes still land on `main` first and are backported to `5.x`. A fix
+for a problem that exists only in v5.x targets `5.x` directly. See the
+[branch strategy](CONTRIBUTING.md#branch-strategy) and
+[issue #1717](https://github.com/ruby-git/ruby-git/issues/1717), the v6.0.0 roadmap.
+
+### 2026-09-04: Retired branches deleted
+
+On September 4, 2026, we deleted the `v1` and `master` branches. Neither had a
+purpose: support for v1.x ended when v3.0.0 shipped, per the
+[Release support policy](#release-support-policy), and `master` was the pre-rename
+default branch, frozen since the rename to `main` on 2025-06-06. Every v1.x release
+remains available as a tag, so nothing released was lost.
+
+The branches that remain are the ones the release support policy describes: `main`
+releases the next version, `4.x` maintains the v4.x series, and `5.x` maintains the
+v5.x series. See [issue #1786](https://github.com/ruby-git/ruby-git/issues/1786) for
+the details.
+
 ### 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
+The v6.0.0 plan is 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.
+deprecation has shipped that way. v6.0.0 also raises the version floors to git 2.43.0
+and Ruby 3.3.
 
-[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
+[Issue #1717](https://github.com/ruby-git/ruby-git/issues/1717) is the roadmap
+and tracks scope, order, 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
@@ -514,7 +552,7 @@ We have published [`git v5.0.0`](https://rubygems.org/gems/git/versions/5.0.0),
 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
+v5.0.0 is a major release with breaking changes. See
 [UPGRADING.md](UPGRADING.md) for the complete migration guide.
 
 To install:
@@ -534,22 +572,22 @@ while emitting deprecation warnings that tell you what to migrate before v6.0.0.
 
 ### 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 have adopted an [AI Policy](AI_POLICY.md) that sets expectations for
+AI-assisted contributions. Read it before opening a PR. It asks that you understand
+every change you submit, that the work meets the project's quality bar, and that it
+respects 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.
+The policy states principles rather than a checklist, so it is short to read and
+still sets clear expectations.
 
 ### 2025-07-09: Architectural 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.
+at the time was difficult to maintain and change. The redesign replaced it with a
+three-layer structure of commands, parsers, and a `Git::Repository` facade, which is
+easier to test because each layer can be exercised on its own.
 
-**The redesign shipped in v5.0.0 and is complete.** `Git::Base` and `Git::Lib` are
+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.
 
@@ -567,10 +605,10 @@ to new code live in [`.github/skills/`](.github/skills/).
 
 ### 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.
+The `ruby-git` project has adopted [RuboCop](https://rubocop.org/) as its static
+code analyzer and formatter so that contributions share one style. All new
+contributions must follow the style rules the project's RuboCop configuration
+enforces.
 
 Run RuboCop from the project's Rakefile: