git 5.0.0.beta.1 → 5.0.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f42d907159502c20d7ba5a2e9545f202be91fb64bf2efcf5663c418acc99a396
-  data.tar.gz: 42361a9dd11080081afddcd446131a4784acf1c7b38774a697026f00fbfb3dff
+  metadata.gz: 30866d1c683ae76cdb07eb526d9adecd45c8ec08bb53824c3a027984297ec256
+  data.tar.gz: a326ea01ed821d33c4edc60963cd2f6473ecaae2cad0daa82c06747456daa8dc
 SHA512:
-  metadata.gz: 264ac7e0a0f8236143c1e95f4bc304b35bca810b7e3d898e8d747ebb7bbec69921a4bc9286899ff3314d95ae02680f349cfcb0f07dcc5d72885e044ab3841b28
-  data.tar.gz: 3212f8816a84bb0be1131e3099e2b0e5fcf248217851b6bffd6176a442e84840e723cb8e5b12b20600d11f2277d4495b61a35bb3f45f3b0e54d5dda6bfc5958f
+  metadata.gz: a0f4cc725c36422a2afa046897d89bef4597fe8120215f83b22c9814d8c1817d4b795525c2aa4edd2c8d52bf617e36bba3b181d5a67af9067a5a6b859bbd6707
+  data.tar.gz: 15957da7f84ef75aa7ad78d6eb7eac4d96aab21b56c265749c5def8a7cb035b5fdce651a395a98ce30fccab3d62c5e66f479fae621d16227c1eb1468c4372f5c

data/.github/copilot-instructions.md

@@ -17,6 +17,12 @@ and compatibility requirements see the
 ## Terminology & Writing Style
 
 - Use American English always. Avoid British English spellings and idioms.
+- **Version strings** — use the most precise form appropriate to the context:
+  - `vN.x` (e.g. `v5.x`, `v4.x`) — the whole major series; use for compatibility
+    statements and upgrade guide scope ("v4.x code works on v5.x").
+  - `vN.0.0` (e.g. `v5.0.0`, `v6.0.0`) — a specific first release; use when
+    precision matters ("removed in v5.0.0", "the foundation delivered in v5.0.0").
+  - `vN.0` — avoid; ambiguous between "minor version 0" and "shorthand for vN.0.0".
 - **RuboCop** — correct capitalization when referring to the tool by name in prose,
   documentation, or comments.
 - **`rubocop`** — correct form when referring to the command-line executable or gem

data/.github/prompts/iteratively-address-copilot-reviews.prompt.md

@@ -0,0 +1,188 @@
+---
+agent: agent
+model: claude-sonnet-4.6
+description: Address all unresolved Copilot review threads on the active pull request until there are no remaining unresolved review threads
+---
+
+Address unresolved **Copilot** review threads on the active pull request. Ignore threads opened by human reviewers. Ask me for clarification or decisions as needed.
+
+If any terminal script command fails, stop immediately. Do not continue the loop, do not resolve additional threads, and do not request a new review. Report: the failed command, exit code, and the most relevant stderr output. **Exception**: the reply POST in Step 3 is intentionally non-fatal — a 404 after a force-push is expected and the resolve step must still run.
+
+## Terminology
+
+- **Review** — a top-level review submission by `copilot-pull-request-reviewer`, with a `submittedAt` timestamp and an optional summary body. A single review may contain zero or more Review Threads.
+- **Review Thread** — an inline comment thread attached to a specific code location. Key fields: `id` (GraphQL node ID, e.g. `PRRT_…`), `isResolved` (manually resolved by a maintainer), `isOutdated` (the underlying code changed since the thread was created). Each thread has one or more comments; the first comment is Copilot's suggestion.
+- **Check Run** — a standard CI status object on the HEAD commit. Note: Copilot Reviews do **not** create a Check Run; use the Reviews API to detect completion instead.
+
+## Before the Loop
+
+Run in terminal to establish `OWNER`, `REPO`, and `PR_NUMBER` for use throughout:
+
+```bash
+set -euo pipefail
+OWNER=$(gh repo view --json owner --jq '.owner.login')
+REPO=$(gh repo view --json name --jq '.name')
+PR_NUMBER=$(gh pr view --json number --jq '.number')
+: "${OWNER:?failed to resolve OWNER}"
+: "${REPO:?failed to resolve REPO}"
+: "${PR_NUMBER:?failed to resolve PR_NUMBER}"
+```
+
+Fetch unresolved, non-outdated Copilot Review Threads:
+
+```bash
+set -euo pipefail
+: "${OWNER:?missing OWNER}"
+: "${REPO:?missing REPO}"
+: "${PR_NUMBER:?missing PR_NUMBER}"
+threads_json=$(gh api graphql -f query='
+  query($owner:String!,$repo:String!,$pr:Int!){
+    repository(owner:$owner,name:$repo){
+      pullRequest(number:$pr){
+        reviewThreads(first:100){nodes{id isResolved isOutdated path
+          comments(first:1){nodes{databaseId author{login} createdAt body}}}}}}
+  }' -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" \
+  --jq '.data.repository.pullRequest.reviewThreads.nodes')
+if [[ $(echo "$threads_json" | jq 'length') -ge 100 ]]; then
+  echo "Error: the PR already has 100 threads or more. Aborting."
+  exit 1
+fi
+echo "$threads_json" | jq '[.[] |
+  select(.isResolved==false) |
+  select(.isOutdated==false) |
+  select(.comments.nodes[0].author.login=="copilot-pull-request-reviewer")]'
+```
+
+- **Results non-empty** → proceed directly to the iteration loop.
+- **Results empty** → record `REVIEW_REQUESTED_AT` (current UTC, `YYYY-MM-DDTHH:MM:SSZ`, e.g. `2026-06-16T12:00:00Z`), request a new Copilot Review using the `mcp_github_mcp_se_request_copilot_review` tool (owner, repo, pullNumber), then jump to the **Wait for Review** section below.
+
+## Iteration Loop
+
+Repeat up to **${input:maxIterations:5}** iterations:
+
+### 1. Address threads
+
+Re-fetch unresolved, non-outdated Copilot Review Threads using the same `gh api graphql` query from Before the Loop. Group by file. For each file, read it once and address all its threads in that single pass:
+- Validate each suggestion before accepting it.
+- If a suggestion is invalid or out of scope: reply explaining why, then resolve the thread without changing code.
+- Otherwise: implement the change using TDD where possible; ensure test coverage.
+
+Skip any thread where `isOutdated` is true — the code it references has already changed; Copilot will re-evaluate it in the next Review.
+
+After all threads are addressed, run `rake`. If it fails, capture `rake 2>&1 | tail -n 50` and fix the failure before continuing.
+
+### 2. Commit and push
+
+Amend each change into the most relevant existing commit on the branch based on file name. If a change spans multiple commits or doesn't map clearly to one, ask me which commit to amend into (or whether to create a new commit). Confirm the working tree is clean and `rake` passes, then force push.
+
+### 3. Reply and resolve
+
+For each addressed thread object from the unresolved-threads query, in the same `run_in_terminal` script block that performs reply/resolve, export:
+
+- `COMMENT_DBID=.comments.nodes[0].databaseId`
+- `THREAD_ID=.id`
+- `EXPLANATION` to your plain-language fix summary for that thread
+
+Set the per-thread variables (`COMMENT_DBID`, `THREAD_ID`, `EXPLANATION`) immediately before running the commands below — do not rely on them surviving from a prior terminal invocation.
+
+Then post a reply and resolve it:
+
+```bash
+set -euo pipefail
+: "${OWNER:?missing OWNER}"
+: "${REPO:?missing REPO}"
+: "${COMMENT_DBID:?missing COMMENT_DBID}"
+: "${EXPLANATION:?missing EXPLANATION}"
+
+# Reply (COMMENT_DBID = databaseId of the thread's first comment)
+# Build JSON via jq to safely handle quotes/newlines/special chars in EXPLANATION.
+# EXPLANATION should contain the full reply text (e.g. "Fixed: ..." or "Not addressing this because...").
+BODY_JSON=$(jq -n --arg body "$EXPLANATION" '{body:$body}')
+# Non-fatal: a force-push can mark threads as outdated, causing the REST reply to return 404.
+# Always continue to the GraphQL resolve step regardless.
+gh api "repos/$OWNER/$REPO/pulls/comments/$COMMENT_DBID/replies" \
+  -X POST --input - <<<"$BODY_JSON" \
+  || echo "Warning: reply POST failed (thread may be outdated after force-push) — skipping reply, will still resolve"
+
+: "${THREAD_ID:?missing THREAD_ID}"
+
+# Resolve (THREAD_ID = GraphQL node id, e.g. PRRT_...)
+gh api graphql \
+  -f query='mutation($id:ID!){resolveReviewThread(input:{threadId:$id}){thread{isResolved}}}' \
+  -f id="$THREAD_ID"
+```
+
+### 4. Request review
+
+**If this was the ${input:maxIterations:5}th iteration**, skip steps 4 and 6 entirely — go directly to step 5 (Report) and then produce the Final Report.
+
+Otherwise, capture `REVIEW_REQUESTED_AT` by running `date -u +%Y-%m-%dT%H:%M:%SZ` in the terminal immediately before requesting the review. Then request a new Copilot Review using the `mcp_github_mcp_se_request_copilot_review` tool (owner, repo, pullNumber).
+
+### 5. Report
+
+List what was addressed and how each issue was resolved.
+
+### 6. Wait
+
+Jump to the **Wait for Review** section below. Return here to begin the next iteration once the new Copilot Review has been submitted.
+
+## Wait for Review
+
+**[BLOCKING — do not proceed until complete]** Poll for a new Copilot Review submission using the Reviews API. A Review with `submittedAt >= REVIEW_REQUESTED_AT` is the authoritative completion signal — it fires even when Copilot produces zero Review Threads.
+
+Run the following script via `run_in_terminal` (sync mode, timeout 750000 ms). Set the four variables on the first line to their actual values. On success, capture the script's last output line; on failure, follow the global failure-reporting rule (failed command, exit code, relevant stderr):
+
+```bash
+set -euo pipefail
+# Replace with actual values. REVIEW_REQUESTED_AT = output of `date -u +%Y-%m-%dT%H:%M:%SZ` captured just before requesting the review.
+OWNER="ruby-git"; REPO="ruby-git"; PR_NUMBER="1439"; REVIEW_REQUESTED_AT="2026-06-16T12:00:00Z"
+: "${OWNER:?missing OWNER}"
+: "${REPO:?missing REPO}"
+: "${PR_NUMBER:?missing PR_NUMBER}"
+: "${REVIEW_REQUESTED_AT:?missing REVIEW_REQUESTED_AT}"
+START=$(date +%s)
+for i in $(seq 1 60); do
+  new_review=$(gh pr view "$PR_NUMBER" --repo "$OWNER/$REPO" --json reviews \
+    --jq "[.reviews[] | select(.author.login==\"copilot-pull-request-reviewer\") | select(.submittedAt != null) | select(.submittedAt | fromdateiso8601 >= (\"$REVIEW_REQUESTED_AT\" | fromdateiso8601))] | length") \
+    || { rc=$?; echo "Error: gh pr view failed (exit $rc)"; exit $rc; }
+  if [[ -n "$new_review" && "$new_review" -gt 0 ]]; then
+    raw_nodes=$(gh api graphql -f query='
+      query($owner:String!,$repo:String!,$pr:Int!){
+        repository(owner:$owner,name:$repo){
+          pullRequest(number:$pr){
+            reviewThreads(first:100){nodes{isResolved isOutdated comments(first:1){nodes{author{login}}}}}
+          }
+        }
+      }' -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" \
+      --jq '.data.repository.pullRequest.reviewThreads.nodes') \
+      || { rc=$?; echo "Error: gh api graphql failed (exit $rc)"; exit $rc; }
+    if [[ $(echo "$raw_nodes" | jq 'length') -ge 100 ]]; then
+      echo "Error: the PR already has 100 threads or more. Aborting."
+      exit 1
+    fi
+    count=$(echo "$raw_nodes" | jq "[.[] |
+      select(.isResolved==false) |
+      select(.isOutdated==false) |
+      select(.comments.nodes[0].author.login==\"copilot-pull-request-reviewer\")] | length")
+    echo "done: $count threads"  # count of all unresolved non-outdated Copilot Review Threads
+    exit 0
+  fi
+  elapsed=$(( $(date +%s) - START ))
+  echo "Waiting for Copilot Review to complete... (${elapsed}s elapsed)"
+  sleep 10
+done
+echo "timed out after 60 polls"
+exit 1
+```
+
+**If `timed out after 60 polls`**: stop immediately and ask me whether to re-request the review and retry, or abort.
+
+**If `done: 0 threads`**: the loop is complete — exit.
+
+**If `done: N threads`** (N > 0): begin the next iteration.
+
+## Final Report
+
+- Total iterations completed
+- Total threads addressed
+- Unresolved threads in the final Copilot review (should be 0 if the loop exited cleanly)

data/.github/skills/extract-facade-from-base-lib/KEYWORD_ARG_REMEDIATION.md

@@ -0,0 +1,22 @@
+# Keyword-arg remediation list
+
+The following facade methods are known to use `**opts`/`**` keyword-splat where
+the legacy `Git::Base` or `Git::Lib` predecessor used a positional options hash
+(`opts = {}`). Each is a candidate `legacy-contract` violation that must be
+resolved before `Git.open`/`.clone`/`.init`/`.bare` are changed to return
+`Git::Repository`: either fix the signature or
+record an explicit `5.x-native` justification.
+
+| Facade method | Current signature | Expected classification | Action needed |
+| --- | --- | --- | --- |
+| `Git::Repository::Staging#add` | `add(paths = '.', **)` | `legacy-contract` | Verify against 4.x `Git::Lib#add`; change to `opts = {}` if legacy |
+| `Git::Repository::Staging#reset` | `reset(commitish = nil, **)` | `legacy-contract` | Verify against 4.x `Git::Lib#reset`; change to `opts = {}` if legacy |
+| `Git::Repository::Committing#commit` | `commit(message = nil, **opts)` | `legacy-contract` | Verify against 4.x `Git::Base#commit`; change to `opts = {}` if legacy |
+| `Git::Repository::Committing#commit_all` | `commit_all(*, **)` | `legacy-contract` | Verify against 4.x `Git::Base#commit_all`; change to `opts = {}` if legacy |
+| `Git::Repository::Committing#commit_tree` | `commit_tree(tree, **opts)` | needs classification | Classify; if 5.x-native confirm; if legacy-contract fix signature |
+| `Git::Repository::Committing#write_and_commit_tree` | `write_and_commit_tree(**)` | needs classification | Classify; if 5.x-native confirm; if legacy-contract fix signature |
+| `Git::Repository::Branching#branch_delete` | `branch_delete(*branches, **options)` | needs classification | Verify against 4.x `Git::Base#branch_delete`; classify and fix or confirm |
+| `Git::Repository::Inspecting#fsck` | `fsck(*objects, **)` | needs classification | Verify against 4.x `Git::Lib#fsck`; classify and fix or confirm |
+
+This list is seeded from a static scan of `lib/git/repository/**/*.rb` and may be
+incomplete. A full public-method inventory is required before closing the sweep.

data/.github/skills/extract-facade-from-base-lib/SKILL.md

@@ -18,7 +18,6 @@ preserve backward compatibility within the migration window.
 
 ## Contents
 
-- [Contents](#contents)
 - [How to use this skill](#how-to-use-this-skill)
 - [Prerequisites](#prerequisites)
 - [Related skills](#related-skills)
@@ -28,6 +27,7 @@ preserve backward compatibility within the migration window.
   - [Pattern B — `Git::Lib`-only (public-by-exposure)](#pattern-b--gitlib-only-public-by-exposure)
   - [Pattern C — `Git::Base`-only (no `Git::Lib` method)](#pattern-c--gitbase-only-no-gitlib-method)
 - [Signature compatibility policy](#signature-compatibility-policy)
+- [Keyword-arg remediation list](#keyword-arg-remediation-list)
 - [Determining the option allowlist](#determining-the-option-allowlist)
 - [Workflow](#workflow)
   - [Branch setup](#branch-setup)
@@ -180,13 +180,29 @@ Use this policy in both extraction mode and review mode:
 
 Rules:
 
-1. Default classification is `legacy-contract` when a legacy predecessor exists.
-2. `5.x-native` requires explicit justification in the plan/review notes.
-3. For `legacy-contract` methods, preserve the exact 4.x signature (including
-  rare `**opts` signatures). For `5.x-native` methods, use `opts = {}` style
-  for consistency.
-4. For `legacy-contract` methods, tests must prove the expected call shape,
-   not only command delegation.
+1. `legacy-contract` methods preserve the exact 4.x call shape verbatim,
+   including rare `**opts` signatures; never alter the parameter list when a
+   legacy predecessor exists.
+2. `5.x-native` methods use `opts = {}` style for consistency; a broader kwargs
+   migration is deferred to v6.x so it can be applied uniformly across the
+   entire public API.
+3. Every extracted method must be explicitly classified as `legacy-contract` or
+   `5.x-native` before the PR is opened.
+4. The classification must appear in the PR description and in the extracted
+   method's YARD `@note`. Example:
+
+   ```ruby
+   # @note Signature compatibility: legacy-contract — preserves the exact Git::Base#foo 4.x call shape.
+   ```
+
+## Keyword-arg remediation list
+
+See [KEYWORD_ARG_REMEDIATION.md](KEYWORD_ARG_REMEDIATION.md) for the initial list
+of facade methods that use `**opts`/`**` keyword-splat where the legacy predecessor
+used `opts = {}`. Each method in this list must be resolved before
+`Git.open`/`.clone`/`.init`/`.bare` are changed to return `Git::Repository`:
+either fix the signature to match the `legacy-contract` classification, or
+record an explicit `5.x-native` justification.
 
 ## Determining the option allowlist
 
@@ -409,15 +425,13 @@ end
 
 ```ruby
 # lib/git/base.rb
-def add_remote(name, url, opts = {})
-  repository.add_remote(name, url, opts)
+def remote_add(name, url, opts = {})
+  facade_repository.remote_add(name, url, opts)
 end
 ```
 
-(The exact accessor — `repository`, `@repository`, `self.repository` — depends
-on how `Git::Base` and `Git::Lib` hold their reference to the new
-`Git::Repository` instance during the migration window. Match the existing
-pattern used by other migrated methods.)
+(Use `facade_repository` to access the `Git::Repository` facade instance — this
+is the accessor used by all migrated methods in `Git::Base`.)
 
 After delegation is in place, verify:
 

data/.github/skills/facade-implementation/SKILL.md

@@ -17,6 +17,7 @@ for the five facade responsibilities this layer is designed around.
 
 ## Contents
 
+- [How to use this skill](#how-to-use-this-skill)
 - [Related skills](#related-skills)
 - [Input](#input)
   - [Existing facade source](#existing-facade-source)
@@ -27,6 +28,19 @@ for the five facade responsibilities this layer is designed around.
 - [Workflow](#workflow)
 - [Output](#output)
 
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke with the facade method
+to scaffold, update, or review. Examples:
+
+```text
+Using the Facade Implementation skill, scaffold Git::Repository::Staging#add.
+```
+
+```text
+Facade Implementation review: Git::Repository::Committing#commit.
+```
+
 ## Related skills
 
 - [Facade Test Conventions](../facade-test-conventions/SKILL.md) — unit and

data/.github/skills/facade-test-conventions/SKILL.md

@@ -10,6 +10,7 @@ methods on `Git::Repository::*` modules.
 
 ## Contents
 
+- [How to use this skill](#how-to-use-this-skill)
 - [Related skills](#related-skills)
 - [Input](#input)
 - [Reference](#reference)
@@ -30,6 +31,19 @@ methods on `Git::Repository::*` modules.
   - [When writing new facade tests](#when-writing-new-facade-tests)
   - [When reviewing existing facade tests](#when-reviewing-existing-facade-tests)
 
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke with the spec file(s)
+to write or review. Include the corresponding facade module for context. Examples:
+
+```text
+Using the Facade Test Conventions skill, scaffold tests for Git::Repository::Staging.
+```
+
+```text
+Facade Test Conventions review: spec/unit/git/repository/committing_spec.rb.
+```
+
 ## Related skills
 
 - [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — baseline

data/.rubocop.yml

@@ -45,6 +45,11 @@ Metrics/BlockLength:
     - "*.gemspec"
     - "lib/git/commands/**/*.rb"
 
+# lib/git.rb is the gem's main entry-point module and is expected to be long
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/git.rb"
+
 # Don't force every test class to be described
 Style/Documentation:
   Exclude:

data/README.md

@@ -30,6 +30,7 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
   - [Ruby Version Support Policy](#ruby-version-support-policy)
   - [Git Version Support Policy](#git-version-support-policy)
 - [📢 Project Announcements 📢](#-project-announcements-)
+  - [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)
   - [2026-01-07: AI Policy Introduced](#2026-01-07-ai-policy-introduced)
   - [2025-07-09: Architectural Redesign](#2025-07-09-architectural-redesign)
@@ -52,7 +53,7 @@ Get started by obtaining a repository object by:
   [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
 
 Methods that can be called on a repository object are documented in
-[Git::Base](https://rubydoc.info/gems/git/Git/Base)
+[Git::Repository](https://rubydoc.info/gems/git/Git/Repository)
 
 ## Install
 
@@ -87,8 +88,8 @@ All functionality for this gem starts with the top-level
 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::Base`](https://rubydoc.info/gems/git/Git/Base) object. The
-`Git::Base` object is used to run repo-specific `git` commands such as `add`,
+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`,
 `commit`, `push`, and `log`.
 
 Clone, read status, and log:
@@ -416,8 +417,8 @@ repo.merge([branch1, branch2])
 
 repo.merge_base('branch1', 'branch2')
 
-r = repo.add_remote(name, uri)  # Git::Remote
-r = repo.add_remote(name, Git::Base)  # Git::Remote
+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
@@ -437,12 +438,12 @@ repo.fetch('origin', {:'update-head-ok' => true})
 repo.pull
 repo.pull(Git::Repo, Git::Branch) # fetch and a merge
 
-repo.add_tag('tag_name') # returns Git::Tag
-repo.add_tag('tag_name', 'object_reference')
-repo.add_tag('tag_name', 'object_reference', {:options => 'here'})
-repo.add_tag('tag_name', {:options => 'here'})
+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.delete_tag('tag_name')
+repo.tag_delete('tag_name')
 
 repo.repack
 
@@ -650,17 +651,56 @@ notes.
 
 ## 📢 Project Announcements 📢
 
+### 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`:
+
+```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-04: v5.0.0.beta.1 Released
 
 The architectural redesign is approximately **65% complete** and we have published
-[`git 5.0.0.beta.1`](https://rubygems.org/gems/git/versions/5.0.0.beta.1) as our
+[`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
+```
+
 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.
+
 ### 2026-01-07: AI Policy Introduced
 
 We have adopted a formal [AI Policy](AI_POLICY.md) to clarify expectations for

data/UPGRADING.md

@@ -0,0 +1,141 @@
+# 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).
+
+- [Upgrading from v4.x to v5.x](#upgrading-from-v4x-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)
+  - [Deprecated methods](#deprecated-methods)
+
+## Upgrading from v4.x 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.
+
+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 a future major release (most likely 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
+[Deprecations](README.md#deprecations) section of the README.
+
+---
+
+### `Git::Lib` removal
+
+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.
+
+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.
+
+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.
+
+#### Methods with a direct replacement
+
+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.
+
+| 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)` |
+| `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.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` |
+
+> **Note — `current_branch_state` return type change:** `g.lib.current_branch_state`
+> returned a `Git::Lib::HeadState` (a mutable `Struct`). `g.current_branch_state`
+> returns a `Git::Repository::Branching::HeadState` (an immutable `Data` object).
+> Both expose `.state` (`:active`, `:unborn`, or `:detached`) and `.name`. If your
+> code relies on the struct being mutable or uses positional construction
+> (`Git::Lib::HeadState.new(:active, 'main')`), update to keyword construction:
+> `Git::Repository::Branching::HeadState.new(state: :active, name: 'main')`.
+
+#### 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)
+
+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:
+
+- `assert_args_are_not_options`
+- `assert_valid_opts`
+- `cat_file_object_meta`
+- `command_capturing`
+- `command_streaming`
+- `each_cat_file_header`
+- `handle_deprecated_path_option`
+- `normalize_pathspecs`
+- `parse_cat_file_meta`
+- `parse_config_list`
+- `process_commit_data`
+- `validate_pathspec_types`
+
+---
+
+### Deprecated methods
+
+The following methods are available in v5.x with deprecation warnings and
+are removed in v6.0.0.
+
+| 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(...)` |
+
+---

data/git.gemspec

@@ -48,6 +48,11 @@ Gem::Specification.new do |spec|
   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
+    spec.add_development_dependency 'i18n', '< 1.15'
+  end
+
   unless RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby'
     spec.add_development_dependency 'irb', '~> 1.16'
     spec.add_development_dependency 'redcarpet', '~> 3.6'