git 4.4.6 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (275) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +1 -0
  3. data/CHANGELOG.md +348 -39
  4. data/CONTRIBUTING.md +1014 -144
  5. data/README.md +386 -504
  6. data/UPGRADING.md +1822 -0
  7. data/git.gemspec +102 -22
  8. data/lib/git/author_info.rb +65 -0
  9. data/lib/git/branch_delete_failure.rb +34 -0
  10. data/lib/git/branch_delete_result.rb +66 -0
  11. data/lib/git/branch_info.rb +237 -0
  12. data/lib/git/command_line/base.rb +247 -0
  13. data/lib/git/command_line/capturing.rb +308 -0
  14. data/lib/git/command_line/result.rb +88 -0
  15. data/lib/git/command_line/streaming.rb +236 -0
  16. data/lib/git/command_line.rb +45 -323
  17. data/lib/git/commands/add.rb +139 -0
  18. data/lib/git/commands/am/abort.rb +43 -0
  19. data/lib/git/commands/am/apply.rb +263 -0
  20. data/lib/git/commands/am/continue.rb +43 -0
  21. data/lib/git/commands/am/quit.rb +43 -0
  22. data/lib/git/commands/am/retry.rb +49 -0
  23. data/lib/git/commands/am/show_current_patch.rb +64 -0
  24. data/lib/git/commands/am/skip.rb +42 -0
  25. data/lib/git/commands/am.rb +33 -0
  26. data/lib/git/commands/apply.rb +242 -0
  27. data/lib/git/commands/archive/list_formats.rb +46 -0
  28. data/lib/git/commands/archive.rb +145 -0
  29. data/lib/git/commands/arguments.rb +4521 -0
  30. data/lib/git/commands/base.rb +522 -0
  31. data/lib/git/commands/branch/copy.rb +102 -0
  32. data/lib/git/commands/branch/create.rb +177 -0
  33. data/lib/git/commands/branch/delete.rb +88 -0
  34. data/lib/git/commands/branch/list.rb +178 -0
  35. data/lib/git/commands/branch/move.rb +102 -0
  36. data/lib/git/commands/branch/set_upstream.rb +86 -0
  37. data/lib/git/commands/branch/show_current.rb +49 -0
  38. data/lib/git/commands/branch/unset_upstream.rb +53 -0
  39. data/lib/git/commands/branch.rb +34 -0
  40. data/lib/git/commands/cat_file/batch.rb +385 -0
  41. data/lib/git/commands/cat_file/filtered.rb +105 -0
  42. data/lib/git/commands/cat_file/raw.rb +203 -0
  43. data/lib/git/commands/cat_file.rb +49 -0
  44. data/lib/git/commands/checkout/branch.rb +153 -0
  45. data/lib/git/commands/checkout/files.rb +116 -0
  46. data/lib/git/commands/checkout.rb +38 -0
  47. data/lib/git/commands/checkout_index.rb +106 -0
  48. data/lib/git/commands/clean.rb +102 -0
  49. data/lib/git/commands/clone.rb +241 -0
  50. data/lib/git/commands/commit.rb +273 -0
  51. data/lib/git/commands/commit_tree.rb +101 -0
  52. data/lib/git/commands/config_option_syntax/add.rb +86 -0
  53. data/lib/git/commands/config_option_syntax/get.rb +121 -0
  54. data/lib/git/commands/config_option_syntax/get_all.rb +118 -0
  55. data/lib/git/commands/config_option_syntax/get_color.rb +95 -0
  56. data/lib/git/commands/config_option_syntax/get_color_bool.rb +96 -0
  57. data/lib/git/commands/config_option_syntax/get_regexp.rb +119 -0
  58. data/lib/git/commands/config_option_syntax/get_urlmatch.rb +111 -0
  59. data/lib/git/commands/config_option_syntax/list.rb +111 -0
  60. data/lib/git/commands/config_option_syntax/remove_section.rb +79 -0
  61. data/lib/git/commands/config_option_syntax/rename_section.rb +83 -0
  62. data/lib/git/commands/config_option_syntax/replace_all.rb +109 -0
  63. data/lib/git/commands/config_option_syntax/set.rb +119 -0
  64. data/lib/git/commands/config_option_syntax/unset.rb +92 -0
  65. data/lib/git/commands/config_option_syntax/unset_all.rb +94 -0
  66. data/lib/git/commands/config_option_syntax.rb +56 -0
  67. data/lib/git/commands/describe.rb +156 -0
  68. data/lib/git/commands/diff.rb +657 -0
  69. data/lib/git/commands/diff_files.rb +519 -0
  70. data/lib/git/commands/diff_index.rb +499 -0
  71. data/lib/git/commands/fetch.rb +354 -0
  72. data/lib/git/commands/fsck.rb +138 -0
  73. data/lib/git/commands/gc.rb +134 -0
  74. data/lib/git/commands/grep.rb +339 -0
  75. data/lib/git/commands/init.rb +101 -0
  76. data/lib/git/commands/log.rb +634 -0
  77. data/lib/git/commands/ls_files.rb +195 -0
  78. data/lib/git/commands/ls_remote.rb +161 -0
  79. data/lib/git/commands/ls_tree.rb +135 -0
  80. data/lib/git/commands/maintenance/register.rb +73 -0
  81. data/lib/git/commands/maintenance/run.rb +105 -0
  82. data/lib/git/commands/maintenance/start.rb +67 -0
  83. data/lib/git/commands/maintenance/stop.rb +56 -0
  84. data/lib/git/commands/maintenance/unregister.rb +80 -0
  85. data/lib/git/commands/maintenance.rb +29 -0
  86. data/lib/git/commands/merge/abort.rb +44 -0
  87. data/lib/git/commands/merge/continue.rb +44 -0
  88. data/lib/git/commands/merge/quit.rb +46 -0
  89. data/lib/git/commands/merge/start.rb +250 -0
  90. data/lib/git/commands/merge.rb +28 -0
  91. data/lib/git/commands/merge_base.rb +91 -0
  92. data/lib/git/commands/mv.rb +82 -0
  93. data/lib/git/commands/name_rev.rb +119 -0
  94. data/lib/git/commands/pull.rb +382 -0
  95. data/lib/git/commands/push.rb +251 -0
  96. data/lib/git/commands/read_tree.rb +154 -0
  97. data/lib/git/commands/remote/add.rb +96 -0
  98. data/lib/git/commands/remote/get_url.rb +68 -0
  99. data/lib/git/commands/remote/list.rb +56 -0
  100. data/lib/git/commands/remote/prune.rb +63 -0
  101. data/lib/git/commands/remote/remove.rb +52 -0
  102. data/lib/git/commands/remote/rename.rb +76 -0
  103. data/lib/git/commands/remote/set_branches.rb +70 -0
  104. data/lib/git/commands/remote/set_head.rb +89 -0
  105. data/lib/git/commands/remote/set_url.rb +78 -0
  106. data/lib/git/commands/remote/set_url_add.rb +70 -0
  107. data/lib/git/commands/remote/set_url_delete.rb +71 -0
  108. data/lib/git/commands/remote/show.rb +77 -0
  109. data/lib/git/commands/remote/update.rb +79 -0
  110. data/lib/git/commands/remote.rb +42 -0
  111. data/lib/git/commands/repack.rb +281 -0
  112. data/lib/git/commands/reset.rb +154 -0
  113. data/lib/git/commands/rev_parse.rb +304 -0
  114. data/lib/git/commands/revert/abort.rb +45 -0
  115. data/lib/git/commands/revert/continue.rb +62 -0
  116. data/lib/git/commands/revert/quit.rb +47 -0
  117. data/lib/git/commands/revert/skip.rb +44 -0
  118. data/lib/git/commands/revert/start.rb +158 -0
  119. data/lib/git/commands/revert.rb +29 -0
  120. data/lib/git/commands/rm.rb +113 -0
  121. data/lib/git/commands/show.rb +632 -0
  122. data/lib/git/commands/show_ref/exclude_existing.rb +119 -0
  123. data/lib/git/commands/show_ref/exists.rb +75 -0
  124. data/lib/git/commands/show_ref/list.rb +149 -0
  125. data/lib/git/commands/show_ref/verify.rb +122 -0
  126. data/lib/git/commands/show_ref.rb +42 -0
  127. data/lib/git/commands/stash/apply.rb +81 -0
  128. data/lib/git/commands/stash/branch.rb +67 -0
  129. data/lib/git/commands/stash/clear.rb +43 -0
  130. data/lib/git/commands/stash/create.rb +60 -0
  131. data/lib/git/commands/stash/drop.rb +73 -0
  132. data/lib/git/commands/stash/list.rb +43 -0
  133. data/lib/git/commands/stash/pop.rb +87 -0
  134. data/lib/git/commands/stash/push.rb +112 -0
  135. data/lib/git/commands/stash/show.rb +158 -0
  136. data/lib/git/commands/stash/store.rb +72 -0
  137. data/lib/git/commands/stash.rb +38 -0
  138. data/lib/git/commands/status.rb +174 -0
  139. data/lib/git/commands/symbolic_ref/delete.rb +72 -0
  140. data/lib/git/commands/symbolic_ref/read.rb +99 -0
  141. data/lib/git/commands/symbolic_ref/update.rb +79 -0
  142. data/lib/git/commands/symbolic_ref.rb +38 -0
  143. data/lib/git/commands/tag/create.rb +142 -0
  144. data/lib/git/commands/tag/delete.rb +57 -0
  145. data/lib/git/commands/tag/list.rb +146 -0
  146. data/lib/git/commands/tag/verify.rb +71 -0
  147. data/lib/git/commands/tag.rb +26 -0
  148. data/lib/git/commands/update_ref/batch.rb +145 -0
  149. data/lib/git/commands/update_ref/delete.rb +90 -0
  150. data/lib/git/commands/update_ref/update.rb +103 -0
  151. data/lib/git/commands/update_ref.rb +42 -0
  152. data/lib/git/commands/version.rb +60 -0
  153. data/lib/git/commands/worktree/add.rb +139 -0
  154. data/lib/git/commands/worktree/list.rb +64 -0
  155. data/lib/git/commands/worktree/lock.rb +58 -0
  156. data/lib/git/commands/worktree/management_base.rb +51 -0
  157. data/lib/git/commands/worktree/move.rb +66 -0
  158. data/lib/git/commands/worktree/prune.rb +67 -0
  159. data/lib/git/commands/worktree/remove.rb +63 -0
  160. data/lib/git/commands/worktree/repair.rb +71 -0
  161. data/lib/git/commands/worktree/unlock.rb +47 -0
  162. data/lib/git/commands/worktree.rb +43 -0
  163. data/lib/git/commands/write_tree.rb +68 -0
  164. data/lib/git/commands.rb +88 -0
  165. data/lib/git/config.rb +64 -1
  166. data/lib/git/config_entry_info.rb +106 -0
  167. data/lib/git/configuring.rb +795 -0
  168. data/lib/git/detached_head_info.rb +57 -0
  169. data/lib/git/diff.rb +295 -12
  170. data/lib/git/diff_file_numstat_info.rb +31 -0
  171. data/lib/git/diff_file_patch_info.rb +136 -0
  172. data/lib/git/diff_file_raw_info.rb +129 -0
  173. data/lib/git/diff_info.rb +162 -0
  174. data/lib/git/diff_path_status.rb +80 -19
  175. data/lib/git/diff_result.rb +34 -0
  176. data/lib/git/diff_stats.rb +66 -14
  177. data/lib/git/dirstat_info.rb +102 -0
  178. data/lib/git/encoding_utils.rb +57 -1
  179. data/lib/git/errors.rb +107 -26
  180. data/lib/git/escaped_path.rb +55 -3
  181. data/lib/git/execution_context/global.rb +31 -0
  182. data/lib/git/execution_context/repository.rb +151 -0
  183. data/lib/git/execution_context.rb +559 -0
  184. data/lib/git/factories.rb +1049 -0
  185. data/lib/git/file_ref.rb +77 -0
  186. data/lib/git/fsck_object.rb +17 -9
  187. data/lib/git/fsck_result.rb +27 -16
  188. data/lib/git/log.rb +172 -65
  189. data/lib/git/object.rb +323 -108
  190. data/lib/git/parsers/branch.rb +240 -0
  191. data/lib/git/parsers/cat_file.rb +111 -0
  192. data/lib/git/parsers/config_entry.rb +110 -0
  193. data/lib/git/parsers/diff.rb +792 -0
  194. data/lib/git/parsers/fsck.rb +144 -0
  195. data/lib/git/parsers/grep.rb +42 -0
  196. data/lib/git/parsers/ls_remote.rb +79 -0
  197. data/lib/git/parsers/ls_tree.rb +58 -0
  198. data/lib/git/parsers/remote.rb +162 -0
  199. data/lib/git/parsers/stash.rb +292 -0
  200. data/lib/git/parsers/status.rb +251 -0
  201. data/lib/git/parsers/tag.rb +341 -0
  202. data/lib/git/parsers/worktree.rb +185 -0
  203. data/lib/git/path_resolver.rb +274 -0
  204. data/lib/git/remote_info.rb +203 -0
  205. data/lib/git/repository/branching.rb +796 -0
  206. data/lib/git/repository/committing.rb +221 -0
  207. data/lib/git/repository/context_helpers.rb +454 -0
  208. data/lib/git/repository/diffing.rb +743 -0
  209. data/lib/git/repository/inspecting.rb +252 -0
  210. data/lib/git/repository/logging.rb +410 -0
  211. data/lib/git/repository/maintenance.rb +65 -0
  212. data/lib/git/repository/merging.rb +429 -0
  213. data/lib/git/repository/object_operations.rb +1334 -0
  214. data/lib/git/repository/remote_operations.rb +772 -0
  215. data/lib/git/repository/shared_private.rb +120 -0
  216. data/lib/git/repository/staging.rb +409 -0
  217. data/lib/git/repository/stashing.rb +619 -0
  218. data/lib/git/repository/status_operations.rb +196 -0
  219. data/lib/git/repository/worktree_operations.rb +252 -0
  220. data/lib/git/repository.rb +204 -1
  221. data/lib/git/stash_info.rb +102 -0
  222. data/lib/git/status_file_info.rb +258 -0
  223. data/lib/git/status_info.rb +189 -0
  224. data/lib/git/system_call_guard.rb +95 -0
  225. data/lib/git/tag_delete_failure.rb +34 -0
  226. data/lib/git/tag_delete_result.rb +66 -0
  227. data/lib/git/tag_info.rb +99 -0
  228. data/lib/git/url.rb +12 -5
  229. data/lib/git/version.rb +111 -2
  230. data/lib/git/version_constraint.rb +85 -0
  231. data/lib/git/worktree_info.rb +128 -0
  232. data/lib/git.rb +319 -332
  233. metadata +318 -74
  234. data/.commitlintrc.yml +0 -38
  235. data/.github/copilot-instructions.md +0 -2733
  236. data/.github/issue_template.md +0 -15
  237. data/.github/pull_request_template.md +0 -17
  238. data/.github/workflows/continuous_integration.yml +0 -120
  239. data/.github/workflows/enforce_conventional_commits.yml +0 -29
  240. data/.github/workflows/experimental_continuous_integration.yml +0 -59
  241. data/.github/workflows/release.yml +0 -53
  242. data/.gitignore +0 -15
  243. data/.husky/commit-msg +0 -1
  244. data/.release-please-manifest.json +0 -3
  245. data/.rubocop.yml +0 -55
  246. data/.rubocop_todo.yml +0 -12
  247. data/Gemfile +0 -5
  248. data/Rakefile +0 -18
  249. data/lib/git/args_builder.rb +0 -111
  250. data/lib/git/author.rb +0 -16
  251. data/lib/git/base.rb +0 -1140
  252. data/lib/git/branch.rb +0 -423
  253. data/lib/git/branches.rb +0 -68
  254. data/lib/git/command_line_result.rb +0 -92
  255. data/lib/git/index.rb +0 -6
  256. data/lib/git/lib.rb +0 -2333
  257. data/lib/git/path.rb +0 -38
  258. data/lib/git/remote.rb +0 -39
  259. data/lib/git/stash.rb +0 -26
  260. data/lib/git/stashes.rb +0 -56
  261. data/lib/git/status.rb +0 -159
  262. data/lib/git/working_directory.rb +0 -6
  263. data/lib/git/worktree.rb +0 -39
  264. data/lib/git/worktrees.rb +0 -47
  265. data/package.json +0 -10
  266. data/redesign/1_architecture_existing.md +0 -66
  267. data/redesign/2_architecture_redesign.md +0 -130
  268. data/redesign/3_architecture_implementation.md +0 -138
  269. data/redesign/index.md +0 -34
  270. data/release-please-config.json +0 -36
  271. data/tasks/gem_tasks.rake +0 -10
  272. data/tasks/rubocop.rake +0 -12
  273. data/tasks/test.rake +0 -13
  274. data/tasks/test_gem.rake +0 -12
  275. data/tasks/yard.rake +0 -23
data/README.md CHANGED
@@ -3,45 +3,59 @@
3
3
  # @title README
4
4
  -->
5
5
 
6
- # The Git Gem
6
+ # The git gem
7
7
 
8
8
  [![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git)
9
+ [![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)
9
10
  [![Documentation](https://img.shields.io/badge/Documentation-Latest-green)](https://rubydoc.info/gems/git/)
10
11
  [![Change
11
12
  Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md)
12
- [![Build
13
- Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=main)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
14
13
  [![Conventional
15
14
  Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
16
- [![AI Policy](https://img.shields.io/badge/AI%20Policy-Required-blue)](AI_POLICY.md)
15
+ [![AI Policy](https://img.shields.io/badge/AI%20Policy-Doc-blue)](AI_POLICY.md)
16
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
17
+
18
+ > **v6.0.0 is released.** It is a major release that removes the APIs deprecated
19
+ > during v5.x, raises the minimum Ruby version to 3.3 and the minimum git version
20
+ > to 2.43.0, and changes a few behaviors that had no deprecation path. See
21
+ > [Upgrading to v6.x](UPGRADING.md#upgrading-to-v6x) for the migration guide and
22
+ > [CHANGELOG.md](CHANGELOG.md) for full release notes. v5.x continues to receive
23
+ > fixes from the `5.x` branch.
17
24
 
18
25
  - [Summary](#summary)
19
26
  - [Install](#install)
20
- - [Quick Start](#quick-start)
27
+ - [Quick start](#quick-start)
21
28
  - [Examples](#examples)
22
- - [Configuration](#configuration)
23
- - [Read Operations](#read-operations)
24
- - [Write Operations](#write-operations)
25
- - [Index and Tree Operations](#index-and-tree-operations)
26
- - [Errors Raised By This Gem](#errors-raised-by-this-gem)
27
- - [Specifying And Handling Timeouts](#specifying-and-handling-timeouts)
29
+ - [Gem configuration](#gem-configuration)
30
+ - [Git configuration](#git-configuration)
31
+ - [Full API](#full-api)
32
+ - [Errors raised by this gem](#errors-raised-by-this-gem)
33
+ - [Specifying and handling timeouts](#specifying-and-handling-timeouts)
28
34
  - [Deprecations](#deprecations)
29
- - [Project Policies](#project-policies)
30
- - [Ruby Version Support Policy](#ruby-version-support-policy)
31
- - [Git Version Support Policy](#git-version-support-policy)
32
- - [📢 Project Announcements 📢](#-project-announcements-)
33
- - [2026-01-07: AI Policy Introduced](#2026-01-07-ai-policy-introduced)
34
- - [2025-07-09: Architectural Redesign](#2025-07-09-architectural-redesign)
35
- - [2025-07-07: We Now Use RuboCop](#2025-07-07-we-now-use-rubocop)
36
- - [2025-06-06: Default Branch Rename](#2025-06-06-default-branch-rename)
37
- - [2025-05-15: We've Switched to Conventional Commits](#2025-05-15-weve-switched-to-conventional-commits)
35
+ - [Platform limitations](#platform-limitations)
36
+ - [Regex metacharacters on Git for Windows](#regex-metacharacters-on-git-for-windows)
37
+ - [Project policies](#project-policies)
38
+ - [Ruby version support policy](#ruby-version-support-policy)
39
+ - [Git version support policy](#git-version-support-policy)
40
+ - [Deprecation policy](#deprecation-policy)
41
+ - [Release support policy](#release-support-policy)
42
+ - [Project announcements](#project-announcements)
43
+ - [2026-09-04: v5.x releases move to the 5.x branch](#2026-09-04-v5x-releases-move-to-the-5x-branch)
44
+ - [2026-09-04: Retired branches deleted](#2026-09-04-retired-branches-deleted)
45
+ - [2026-08-23: v5.x deprecations and the v6.0.0 roadmap](#2026-08-23-v5x-deprecations-and-the-v600-roadmap)
46
+ - [2026-07-28: v5.0.0 released](#2026-07-28-v500-released)
47
+ - [2026-01-07: AI policy introduced](#2026-01-07-ai-policy-introduced)
48
+ - [2025-07-09: Architectural redesign](#2025-07-09-architectural-redesign)
49
+ - [2025-07-07: We now use RuboCop](#2025-07-07-we-now-use-rubocop)
50
+ - [2025-06-06: Default branch rename](#2025-06-06-default-branch-rename)
51
+ - [2025-05-15: We've switched to Conventional Commits](#2025-05-15-weve-switched-to-conventional-commits)
38
52
 
39
53
  ## Summary
40
54
 
41
55
  The [git gem](https://rubygems.org/gems/git) provides a Ruby interface to the `git`
42
56
  command line.
43
57
 
44
- Get started by obtaining a repository object by:
58
+ Get a repository object by:
45
59
 
46
60
  - opening an existing working copy with
47
61
  [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
@@ -50,44 +64,36 @@ Get started by obtaining a repository object by:
50
64
  - cloning a repository with
51
65
  [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
52
66
 
53
- Methods that can be called on a repository object are documented in
54
- [Git::Base](https://rubydoc.info/gems/git/Git/Base)
67
+ [Git::Repository](https://rubydoc.info/gems/git/Git/Repository) documents the
68
+ methods you can call on a repository object.
55
69
 
56
70
  ## Install
57
71
 
72
+ This gem is a wrapper around the `git` command line, so a `git` executable (version
73
+ 2.43.0 or greater) must be installed and on your `PATH`. See the [Git version support
74
+ policy](#git-version-support-policy) for details.
75
+
58
76
  Install the gem and add to the application's Gemfile by executing:
59
77
 
60
78
  ```shell
61
79
  bundle add git
62
80
  ```
63
81
 
64
- to install version 1.x:
65
-
66
- ```shell
67
- bundle add git --version "~> 1.19"
68
- ```
69
-
70
- If bundler is not being used to manage dependencies, install the gem by executing:
82
+ If you are not using bundler to manage dependencies, install the gem by executing:
71
83
 
72
84
  ```shell
73
85
  gem install git
74
86
  ```
75
87
 
76
- to install version 1.x:
77
-
78
- ```shell
79
- gem install git --version "~> 1.19"
80
- ```
81
-
82
- ## Quick Start
88
+ ## Quick start
83
89
 
84
90
  All functionality for this gem starts with the top-level
85
- [`Git`](https://rubydoc.info/gems/git/Git) module. This module can be used to run
86
- non-repo scoped `git` commands such as `config`.
91
+ [`Git`](https://rubydoc.info/gems/git/Git) module. Use this module to run non-repo
92
+ scoped `git` commands such as `config`.
87
93
 
88
94
  The `Git` module also has factory methods such as `open`, `clone`, and `init` which
89
- return a [`Git::Base`](https://rubydoc.info/gems/git/Git/Base) object. The
90
- `Git::Base` object is used to run repo-specific `git` commands such as `add`,
95
+ return a [`Git::Repository`](https://rubydoc.info/gems/git/Git/Repository) object. Use
96
+ the `Git::Repository` object to run repo-specific `git` commands such as `add`,
91
97
  `commit`, `push`, and `log`.
92
98
 
93
99
  Clone, read status, and log:
@@ -96,8 +102,8 @@ Clone, read status, and log:
96
102
  require 'git'
97
103
 
98
104
  repo = Git.clone('https://github.com/ruby-git/ruby-git.git', 'ruby-git')
99
- repo.status.changed.each { |f| puts "changed: #{f.path}" }
100
- repo.log(5).each { |c| puts c.message }
105
+ repo.status_info.changed.each_key { |path| puts "changed: #{path}" }
106
+ repo.log(5).execute.each { |c| puts c.message }
101
107
  ```
102
108
 
103
109
  Open an existing repo and commit:
@@ -123,25 +129,10 @@ repo.commit('initial commit')
123
129
 
124
130
  ## Examples
125
131
 
126
- Beyond the basics covered in Quick Start, these examples show the full range of
127
- options and variations for each operation.
128
-
129
- ### Configuration
130
-
131
- Configure the `git` command line:
132
+ These examples cover configuring the gem and git itself. For the full set of
133
+ repository operations, see [Full API](#full-api) below.
132
134
 
133
- ```ruby
134
- # Global config (in ~/.gitconfig)
135
- settings = Git.global_config # returns a Hash
136
- username = Git.global_config('user.email')
137
- Git.global_config('user.email', 'user@example.com')
138
-
139
- # Repository config
140
- repo = Git.open('path/to/repo')
141
- settings = repo.config # returns a Hash
142
- username = repo.config('user.email')
143
- repo.config('user.email', 'anotheruser@example.com')
144
- ```
135
+ ### Gem configuration
145
136
 
146
137
  Configure the git gem:
147
138
 
@@ -157,14 +148,14 @@ Git.config.binary_path = '/usr/local/bin/git'
157
148
  Git.config.git_ssh = 'ssh -i ~/.ssh/id_rsa'
158
149
  ```
159
150
 
160
- **How SSH configuration is determined:**
151
+ How SSH configuration is determined:
161
152
 
162
- - If `git_ssh` is not specified in the API call, the global config (`Git.configure {
163
- |c| c.git_ssh = ... }`) is used.
164
- - If `git_ssh: nil` is specified, SSH is disabled for that instance (no SSH key or
165
- script will be used).
166
- - If `git_ssh` is a non-empty string, it is used for that instance (overriding the
167
- global config).
153
+ - If the API call does not specify `git_ssh`, the gem uses the global config
154
+ (`Git.configure { |c| c.git_ssh = ... }`).
155
+ - If the call specifies `git_ssh: nil`, the gem disables SSH for that instance and
156
+ uses no SSH key or script.
157
+ - If `git_ssh` is a non-empty string, the gem uses it for that instance instead of
158
+ the global config.
168
159
 
169
160
  You can also specify a custom SSH script on a per-repository basis:
170
161
 
@@ -180,382 +171,92 @@ git = Git.clone('git@github.com:user/repo.git', 'local-dir',
180
171
  git = Git.init('new-repo', git_ssh: 'ssh -i /path/to/private_key')
181
172
  ```
182
173
 
183
- This is especially useful in multi-threaded applications where different repositories
184
- require different SSH credentials.
174
+ This matters in multi-threaded applications where different repositories need
175
+ different SSH credentials.
185
176
 
186
- ### Read Operations
177
+ ### Git configuration
187
178
 
188
- Here are the operations that need read permission only:
179
+ Read and set `git` configuration values (via `git config`):
189
180
 
190
181
  ```ruby
191
- repo = Git.open(working_dir, :log => Logger.new(STDOUT))
192
-
193
- repo.index
194
- repo.index.readable?
195
- repo.index.writable?
196
- repo.repo
197
- repo.dir
198
-
199
- # ls-tree with recursion into subtrees (list files)
200
- repo.ls_tree("HEAD", recursive: true)
201
-
202
- # log - returns a Git::Log object, which is an Enumerator of Git::Commit objects
203
- # default configuration returns a max of 30 commits
204
- repo.log
205
- repo.log(200) # 200 most recent commits
206
- repo.log.since('2 weeks ago') # default count of commits since 2 weeks ago.
207
- repo.log(200).since('2 weeks ago') # commits since 2 weeks ago, limited to 200.
208
- repo.log.between('v2.5', 'v2.6')
209
- repo.log.each {|l| puts l.sha }
210
- repo.gblob('v2.5:Makefile').log.since('2 weeks ago')
211
-
212
- repo.object('HEAD^').to_s # git show / git rev-parse
213
- repo.object('HEAD^').contents
214
- repo.object('v2.5:Makefile').size
215
- repo.object('v2.5:Makefile').sha
216
-
217
- repo.gtree(treeish)
218
- repo.gblob(treeish)
219
- repo.gcommit(treeish)
220
-
221
-
222
- commit = repo.gcommit('1cc8667014381')
223
-
224
- commit.gtree
225
- commit.parent.sha
226
- commit.parents.size
227
- commit.author.name
228
- commit.author.email
229
- commit.author.date.strftime("%m-%d-%y")
230
- commit.committer.name
231
- commit.date.strftime("%m-%d-%y")
232
- commit.message
233
-
234
- tree = repo.gtree("HEAD^{tree}")
235
-
236
- tree.blobs
237
- tree.subtrees
238
- tree.children # blobs and subtrees
239
-
240
- repo.rev_parse('v2.0.0:README.md')
241
-
242
- repo.branches # returns Git::Branch objects
243
- repo.branches.local
244
- repo.current_branch
245
- repo.branches.remote
246
- repo.branches[:main].gcommit
247
- repo.branches['origin/main'].gcommit
248
-
249
- repo.grep('hello') # implies HEAD
250
- repo.blob('v2.5:Makefile').grep('hello')
251
- repo.tag('v2.5').grep('hello', 'docs/')
252
- repo.describe()
253
- repo.describe('0djf2aa')
254
- repo.describe('HEAD', {:all => true, :tags => true})
255
-
256
- repo.diff(commit1, commit2).size
257
- repo.diff(commit1, commit2).stats
258
- repo.diff(commit1, commit2).name_status
259
- repo.gtree('v2.5').diff('v2.6').insertions
260
- repo.diff('gitsearch1', 'v2.5').path('lib/')
261
- repo.diff('gitsearch1', 'v2.5').path('lib/', 'docs/', 'README.md') # multiple paths
262
- repo.diff('gitsearch1', repo.gtree('v2.5'))
263
- repo.diff('gitsearch1', 'v2.5').path('docs/').patch
264
- repo.gtree('v2.5').diff('v2.6').patch
265
-
266
- repo.gtree('v2.5').diff('v2.6').each do |file_diff|
267
- puts file_diff.path
268
- puts file_diff.patch
269
- puts file_diff.blob(:src).contents
270
- end
271
-
272
- repo.worktrees # returns Git::Worktree objects
273
- repo.worktrees.count
274
- repo.worktrees.each do |worktree|
275
- worktree.dir
276
- worktree.gcommit
277
- worktree.to_s
278
- end
279
-
280
- # Check repository integrity with fsck
281
- result = repo.fsck
282
- result.dangling.each { |obj| puts "dangling #{obj.type}: #{obj.sha}" }
283
- result.missing.each { |obj| puts "missing #{obj.type}: #{obj.sha}" }
284
-
285
- # Check if repository has any issues
286
- puts "Repository is clean" if result.empty?
287
-
288
- # fsck with options
289
- result = repo.fsck(unreachable: true, strict: true)
290
-
291
- # Suppress dangling object output
292
- result = repo.fsck(dangling: false)
293
-
294
- repo.config('user.name') # returns 'Scott Chacon'
295
- repo.config # returns whole config hash
296
-
297
- # Configuration can be set when cloning using the :config option.
298
- # This option can be an single configuration String or an Array
299
- # if multiple config items need to be set.
300
- #
301
- repo = Git.clone(
302
- git_uri, destination_path,
303
- :config => [
304
- 'core.sshCommand=ssh -i /home/user/.ssh/id_rsa',
305
- 'submodule.recurse=true'
306
- ]
307
- )
308
-
309
- repo.tags # returns array of Git::Tag objects
310
-
311
- repo.show()
312
- repo.show('HEAD')
313
- repo.show('v2.8', 'README.md')
314
-
315
- Git.ls_remote('https://github.com/ruby-git/ruby-git.git') # returns a hash containing the available references of the repo.
316
- Git.ls_remote('/path/to/local/repo')
317
- Git.ls_remote() # same as Git.ls_remote('.')
182
+ # Global config (in ~/.gitconfig)
183
+ entries = Git.config_list(global: true) # returns Array<Git::ConfigEntryInfo>
184
+ entry = Git.config_get('user.email', global: true) # returns Git::ConfigEntryInfo or nil
185
+ email = entry&.value # => "user@example.com" or nil
186
+ Git.config_set('user.email', 'user@example.com', global: true)
318
187
 
319
- Git.default_branch('https://github.com/ruby-git/ruby-git') #=> 'main'
188
+ # Repository config
189
+ repo = Git.open('path/to/repo')
190
+ entries = repo.config_list # returns Array<Git::ConfigEntryInfo>
191
+ entry = repo.config_get('user.email') # returns Git::ConfigEntryInfo or nil
192
+ email = entry&.value # => "anotheruser@example.com" or nil
193
+ repo.config_set('user.email', 'anotheruser@example.com')
320
194
  ```
321
195
 
322
- ### Write Operations
323
-
324
- And here are the operations that will need to write to your git repository.
325
-
326
- ```ruby
327
- repo = Git.init # default is the current directory
328
- repo = Git.init('project')
329
- repo = Git.init(
330
- '/home/schacon/proj',
331
- { :repository => '/opt/git/proj.git', :index => '/tmp/index'}
332
- )
333
-
334
- # Clone from a git url
335
- git_url = 'https://github.com/ruby-git/ruby-git.git'
336
- repo = Git.clone(git_url)
337
-
338
- # Clone into /tmp/clone/ruby-git-clean
339
- name = 'ruby-git-clean'
340
- path = '/tmp/clone'
341
- repo = Git.clone(git_url, name, :path => path)
342
- repo.dir #=> /tmp/clone/ruby-git-clean
343
-
344
- repo.config('user.name', 'Scott Chacon')
345
- repo.config('user.email', 'email@email.com')
346
-
347
- # Clone can take a filter to tell the serve to send a partial clone
348
- repo = Git.clone(git_url, name, :path => path, :filter => 'tree:0')
349
-
350
- # Clone can control single-branch behavior (nil default keeps current git behavior)
351
- repo = Git.clone(git_url, name, :path => path, :depth => 1, :single_branch => false)
352
-
353
- # Clone can take an optional logger
354
- logger = Logger.new(STDOUT)
355
- repo = Git.clone(git_url, 'my-repo', :log => logger)
356
-
357
- repo.add # git add -- "."
358
- repo.add(:all=>true) # git add --all -- "."
359
- repo.add('file_path') # git add -- "file_path"
360
- repo.add(['file_path_1', 'file_path_2']) # git add -- "file_path_1" "file_path_2"
361
-
362
- repo.remove() # git rm -f -- "."
363
- repo.remove('file.txt') # git rm -f -- "file.txt"
364
- repo.remove(['file.txt', 'file2.txt']) # git rm -f -- "file.txt" "file2.txt"
365
- repo.remove('file.txt', :recursive => true) # git rm -f -r -- "file.txt"
366
- repo.remove('file.txt', :cached => true) # git rm -f --cached -- "file.txt"
367
-
368
- repo.commit('message')
369
- repo.commit_all('message')
370
-
371
- # Sign a commit using the gpg key configured in the user.signingkey config setting
372
- repo.config('user.signingkey', '0A46826A')
373
- repo.commit('message', gpg_sign: true)
374
-
375
- # Sign a commit using a specified gpg key
376
- key_id = '0A46826A'
377
- repo.commit('message', gpg_sign: key_id)
378
-
379
- # Skip signing a commit (overriding any global gpgsign setting)
380
- repo.commit('message', no_gpg_sign: true)
381
-
382
- repo = Git.clone(git_url, 'myrepo')
383
- repo.chdir do
384
- File.write('test-file', 'blahblahblah')
385
- repo.status.changed.each do |file|
386
- puts file.blob(:index).contents
387
- end
388
- end
389
-
390
- repo.reset # defaults to HEAD
391
- repo.reset_hard(Git::Commit)
392
-
393
- repo.branch('new_branch') # creates new or fetches existing
394
- repo.branch('new_branch').checkout
395
- repo.branch('new_branch').delete
396
- repo.branch('existing_branch').checkout
397
- repo.branch('main').contains?('existing_branch')
398
-
399
- # delete remote branch
400
- repo.push('origin', 'remote_branch_name', force: true, delete: true)
401
-
402
- repo.checkout('new_branch')
403
- repo.checkout('new_branch', new_branch: true, start_point: 'main')
404
- repo.checkout(repo.branch('new_branch'))
405
-
406
- repo.branch(name).merge(branch2)
407
- repo.branch(branch2).merge # merges HEAD with branch2
408
-
409
- repo.branch(name).in_branch(message) { # add files } # auto-commits
410
- repo.merge('new_branch')
411
- repo.merge('new_branch', 'merge commit message', no_ff: true)
412
- repo.merge('origin/remote_branch')
413
- repo.merge(repo.branch('main'))
414
- repo.merge([branch1, branch2])
196
+ ### Full API
415
197
 
416
- repo.merge_base('branch1', 'branch2')
198
+ The quick start and the configuration sections above cover the most common setup.
199
+ The [`Git::Repository`](https://rubydoc.info/gems/git/Git/Repository) reference
200
+ covers everything else: reading history, diffs, branches, remotes, worktrees,
201
+ staging, and low-level index and tree work. It documents every method and the object
202
+ type each one returns (such as `Git::Log`, `Git::Object::Commit`, `Git::Diff`,
203
+ `Git::BranchInfo`, and `Git::WorktreeInfo`), so you can follow the links from a method
204
+ to the full API of its result.
417
205
 
418
- r = repo.add_remote(name, uri) # Git::Remote
419
- r = repo.add_remote(name, Git::Base) # Git::Remote
420
-
421
- repo.remotes # array of Git::Remotes
422
- repo.remote(name).fetch
423
- repo.remote(name).remove
424
- repo.remote(name).merge
425
- repo.remote(name).merge(branch)
426
-
427
- repo.remote_set_branches('origin', '*', add: true) # append additional fetch refspecs
428
- repo.remote_set_branches('origin', 'feature', 'release/*') # replace fetch refspecs
429
-
430
- repo.fetch
431
- repo.fetch(repo.remotes.first)
432
- repo.fetch('origin', {:ref => 'some/ref/head'} )
433
- repo.fetch(all: true, force: true, depth: 2)
434
- repo.fetch('origin', {:'update-head-ok' => true})
435
-
436
- repo.pull
437
- repo.pull(Git::Repo, Git::Branch) # fetch and a merge
438
-
439
- repo.add_tag('tag_name') # returns Git::Tag
440
- repo.add_tag('tag_name', 'object_reference')
441
- repo.add_tag('tag_name', 'object_reference', {:options => 'here'})
442
- repo.add_tag('tag_name', {:options => 'here'})
443
-
444
- repo.delete_tag('tag_name')
445
-
446
- repo.repack
447
-
448
- repo.push
449
- repo.push(repo.remote('name'))
206
+ ## Errors raised by this gem
450
207
 
451
- # delete remote branch
452
- repo.push('origin', 'remote_branch_name', force: true, delete: true)
208
+ The git gem raises only `ArgumentError` or errors that subclass `Git::Error`.
453
209
 
454
- # push all branches to remote at one time
455
- repo.push('origin', all: true)
456
-
457
- repo.worktree('/tmp/new_worktree').add
458
- repo.worktree('/tmp/new_worktree', 'branch1').add
459
- repo.worktree('/tmp/new_worktree').remove
460
- repo.worktrees.prune
461
- ```
462
-
463
- ### Index and Tree Operations
464
-
465
- Some examples of more low-level index and tree operations
210
+ Rescue `Git::Error` to catch any runtime error raised by this gem, unless you need
211
+ more specific error handling.
466
212
 
467
213
  ```ruby
468
- repo.with_temp_index do
469
-
470
- repo.read_tree(tree3) # calls self.index.read_tree
471
- repo.read_tree(tree1, :prefix => 'hi/')
472
-
473
- c = repo.commit_tree('message')
474
- # or #
475
- t = repo.write_tree
476
- c = repo.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
477
-
478
- repo.branch('branch_name').update_ref(c)
479
- repo.update_ref(branch, c)
480
-
481
- repo.with_temp_working do # new blank working directory
482
- repo.checkout
483
- repo.checkout(another_index)
484
- repo.commit # commits to temp_index
485
- end
486
- end
487
-
488
- repo.set_index('/path/to/index')
489
-
490
- repo.with_index(path) do
491
- # calls set_index, then switches back after
492
- end
493
-
494
- repo.with_working(dir) do
495
- # calls set_working, then switches back after
496
- end
497
-
498
- repo.with_temp_working(dir) do
499
- repo.checkout_index(:prefix => dir, :path_limiter => path)
500
- # do file work
501
- repo.commit # commits to index
214
+ begin
215
+ # some git operation
216
+ rescue Git::Error => e
217
+ puts "An error occurred: #{e.message}"
502
218
  end
503
219
  ```
504
220
 
505
- ## Errors Raised By This Gem
506
-
507
- The git gem will only raise an `ArgumentError` or an error that is a subclass of
508
- `Git::Error`. It does not explicitly raise any other types of errors.
509
-
510
- The gem's own filesystem operations, such as reading a `.git` pointer file,
511
- creating a temporary file, or changing directory, do not convert operating system
512
- errors. These can be raised as a bare `SystemCallError` (for example `Errno::ENOENT`
513
- or `Errno::EACCES`) rather than `Git::Error`. Gzip compression in `archive` can
514
- likewise raise a `Zlib::Error`. Rescue `SystemCallError` and `Zlib::Error` alongside
515
- `Git::Error` if your code needs to handle them. Any method that captures git
516
- output can also raise `Encoding::ConverterNotFoundError` when the output contains
517
- a line whose detected encoding, such as UTF-7, has no Ruby converter.
518
-
519
- Starting with v6.0.0, the filesystem and gzip errors are raised as `Git::Error`
520
- with the original error available through `cause`, and lines with no Ruby
521
- converter are scrubbed instead of raising.
522
-
523
- It is recommended to rescue `Git::Error` to catch any runtime error raised by this
524
- gem unless you need more specific error handling.
221
+ Operating system errors from the gem's own filesystem operations, such as reading
222
+ a `.git` pointer file or creating a temporary file, are raised as `Git::Error`.
223
+ The original `SystemCallError` is available through `cause`:
525
224
 
526
225
  ```ruby
527
226
  begin
528
- # some git operation
227
+ repo = Git.open('/path/to/repo')
529
228
  rescue Git::Error => e
530
- puts "An error occurred: #{e.message}"
229
+ puts e.cause.class if e.cause.is_a?(SystemCallError) #=> Errno::EACCES
531
230
  end
532
231
  ```
533
232
 
534
- See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
535
-
536
- ## Specifying And Handling Timeouts
233
+ The promise covers errors the gem raises from its own operations. Two things pass
234
+ through unchanged. An error raised by a block your code passes to a method such as
235
+ `chdir` or `with_temp_working` is your error, and the gem does not relabel it. And
236
+ with the `raise` behavior described under [Deprecation policy](#deprecation-policy), a
237
+ deprecated call raises `ActiveSupport::DeprecationException`, which is intentionally
238
+ not a `Git::Error` so a broad rescue cannot hide a deprecation your code opted to
239
+ treat as fatal.
537
240
 
538
- The timeout feature was added in git gem version `2.0.0`.
241
+ See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
539
242
 
540
- A timeout for git command line operations can be set either globally or for specific
541
- method calls that accept a `:timeout` parameter.
243
+ ## Specifying and handling timeouts
542
244
 
543
- The timeout value must be a real, non-negative `Numeric` value that specifies a
544
- number of seconds a `git` command will be given to complete before being sent a KILL
545
- signal. This library may hang if the `git` command does not terminate after receiving
546
- the KILL signal.
245
+ Set a timeout for git command line operations either globally or per method call for
246
+ methods that accept a `:timeout` parameter.
547
247
 
548
- When a command times out, it is killed by sending it the `SIGKILL` signal and a
549
- `Git::TimeoutError` is raised. This error derives from the `Git::SignaledError` and
550
- `Git::Error`.
248
+ The timeout is the number of seconds a `git` command may run before the gem sends
249
+ it `SIGKILL`. It must be a real, non-negative `Numeric`. When a command times out,
250
+ the gem kills it and raises `Git::TimeoutError`, which derives from
251
+ `Git::SignaledError` and `Git::Error`. The gem may hang if the `git` command does
252
+ not terminate after receiving `SIGKILL`.
551
253
 
552
- If the timeout value is `0` or `nil`, no timeout will be enforced.
254
+ If the timeout value is `0` or `nil`, no timeout is enforced.
553
255
 
554
- If a method accepts a `:timeout` parameter and a receives a non-nil value, the value
555
- of this parameter will override the global timeout value. In this context, a value of
556
- `nil` (which is usually the default) will use the global timeout value and a value of
557
- `0` will turn off timeout enforcement for that method call no matter what the global
558
- value is.
256
+ If a method accepts a `:timeout` parameter and receives a non-nil value, that value
257
+ overrides the global timeout. In this context, a value of `nil`, which is usually
258
+ the default, uses the global timeout value, and a value of `0` turns off timeout
259
+ enforcement for that method call no matter what the global value is.
559
260
 
560
261
  To set a global timeout, use the `Git.config` object:
561
262
 
@@ -572,17 +273,17 @@ repo_url = 'https://github.com/ruby-git/ruby-git.git'
572
273
  Git.clone(repo_url) # Use the global timeout value
573
274
  Git.clone(repo_url, timeout: nil) # Also uses the global timeout value
574
275
  Git.clone(repo_url, timeout: 0) # Do not enforce a timeout
575
- Git.clone(repo_url, timeout: 10.5) # Timeout after 10.5 seconds raising Git::SignaledError
276
+ Git.clone(repo_url, timeout: 10.5) # Timeout after 10.5 seconds raising Git::TimeoutError
576
277
  ```
577
278
 
578
- If the command takes too long, a `Git::TimeoutError` will be raised:
279
+ If the command takes too long, the gem raises `Git::TimeoutError`:
579
280
 
580
281
  ```ruby
581
282
  begin
582
283
  Git.clone(repo_url, timeout: 10)
583
284
  rescue Git::TimeoutError => e
584
285
  e.result.tap do |r|
585
- r.class #=> Git::CommandLineResult
286
+ r.class #=> Git::CommandLine::Result
586
287
  r.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
587
288
  r.status.timeout? #=> true
588
289
  r.git_cmd # The git command ran as an array of strings
@@ -611,6 +312,17 @@ GIT_DEPRECATION_BEHAVIOR=silence
611
312
  Accepted environment variable values are the behavior names supported by your
612
313
  installed ActiveSupport version.
613
314
 
315
+ A deprecated method warns on every call, so a call site inside a loop produces one
316
+ warning per iteration. The gem does not deduplicate warnings. To quiet one call site
317
+ without hiding other deprecations, wrap it in `Git::Deprecation.silence`:
318
+
319
+ ```ruby
320
+ Git::Deprecation.silence { repo.set_index(index_file) }
321
+ ```
322
+
323
+ Prefer this over setting the behavior to `silence` globally, which also hides the
324
+ warnings for deprecations added in later releases.
325
+
614
326
  If `GIT_DEPRECATION_BEHAVIOR` is set to an unsupported value, loading the gem
615
327
  raises `ArgumentError` with the accepted behavior names.
616
328
 
@@ -618,11 +330,80 @@ See [the Active Support Deprecation
618
330
  documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
619
331
  for more details.
620
332
 
621
- If deprecation warnings are silenced, you should reenable them before upgrading the
622
- git gem to the next major version. This will make it easier to identify changes
623
- needed for the upgrade.
333
+ Before upgrading the git gem to the next major version, follow the upgrade procedure
334
+ in [UPGRADING.md](UPGRADING.md#upgrading-to-v6x). It turns the warnings into errors so
335
+ that you cannot miss one.
336
+
337
+ For the full list of deprecated methods and their replacements, see
338
+ [UPGRADING.md](UPGRADING.md).
339
+
340
+ ## Platform limitations
341
+
342
+ ### Regex metacharacters on Git for Windows
343
+
344
+ On Git for Windows, git's regex engine matches **bytes** rather than characters. A
345
+ metacharacter such as `.`, or a POSIX character class such as `[[:alpha:]]`, therefore
346
+ never matches a whole multi-byte character. The same call matches on Linux and macOS.
347
+
348
+ The failure is silent. Nothing raises, and the result is indistinguishable from a
349
+ pattern that genuinely does not occur:
350
+
351
+ ```ruby
352
+ # File content, commit message, and config value are all 'ÄPFEL sind gut'.
353
+ # 'Ä' is two bytes in UTF-8 (C3 84), so '.' has to match both to match the character.
354
+
355
+ repo.grep('^.PFEL') # => {} on Windows, matches elsewhere
356
+ repo.log.grep('^.PFEL').execute.size # => 0 on Windows, 1 elsewhere
357
+ repo.config_get_all('test.desc', '^.PFEL') # => [] on Windows, matches elsewhere
358
+ ```
359
+
360
+ This is a property of the regex engine git bundles on that platform, not something the
361
+ gem sets. It is unaffected by the locale: the behavior is identical under `en_US.UTF-8`,
362
+ `C.UTF-8`, `C`, and with no `LC_ALL` set at all. Literal (metacharacter-free) patterns
363
+ and case-insensitive matching are unaffected on every platform.
364
+
365
+ **Workaround.** Perl-compatible regular expressions do match characters on Git for
366
+ Windows, so the methods that can reach a PCRE engine accept an opt-in selector:
367
+
368
+ ```ruby
369
+ repo.grep('^.PFEL', nil, perl_regexp: true) # matches on every platform
370
+ repo.log.perl_regexp.grep('^.PFEL').execute # matches on every platform
371
+ repo.full_log_commits(grep: '^.PFEL', perl_regexp: true)
372
+ ```
373
+
374
+ Two caveats:
375
+
376
+ - **PCRE is a different dialect.** Git's other modes are POSIX basic regular
377
+ expressions (the default) and POSIX extended regular expressions (selected
378
+ explicitly). Selecting PCRE is a deliberate choice by the caller, so the gem does
379
+ not substitute it automatically based on the host.
380
+ - **PCRE must be compiled in.** Git for Windows and the mainstream Linux and macOS
381
+ packages ship it, but git built without `USE_LIBPCRE` fails with `cannot use
382
+ Perl-compatible regexes...`.
383
+
384
+ **There is no workaround for `git config` value patterns.** They are POSIX extended
385
+ regular expressions with no PCRE mode, so `config_get`, `config_get_all`,
386
+ `config_get_regexp`, `config_replace_all`, `config_unset`, and `config_unset_all` cannot
387
+ match a metacharacter against a non-ASCII character on Git for Windows. Match on ASCII
388
+ text or an exact value instead.
389
+
390
+ `config_replace_all` deserves particular care, because there the failure is worse than
391
+ an empty result. When the value pattern selects nothing, `git config --replace-all`
392
+ *adds* the new value as an additional entry rather than replacing one, and exits zero:
624
393
 
625
- ## Project Policies
394
+ ```ruby
395
+ # Existing value of test.desc is 'ÄPFEL sind gut'
396
+ repo.config_replace_all('test.desc', 'NEW', '^.PFEL')
397
+
398
+ repo.config_get_all('test.desc').map(&:value)
399
+ # => ["NEW"] elsewhere, replaced as intended
400
+ # => ["ÄPFEL sind gut", "NEW"] on Windows, original kept and duplicate added
401
+ ```
402
+
403
+ So a replace can silently leave the original value in place and add a second entry beside
404
+ it. Confirm with `config_get_all` when the key must end up single-valued.
405
+
406
+ ## Project policies
626
407
 
627
408
  These documents set expectations for behavior, contribution workflows, AI-assisted
628
409
  changes, decision making, maintainer roles, and licensing. Please review them before
@@ -635,135 +416,236 @@ opening issues or pull requests.
635
416
  | [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. |
636
417
  | [Ruby version support policy](#ruby-version-support-policy) | Supported Ruby runtimes and platforms; bump decisions and CI coverage expectations. |
637
418
  | [Git version support policy](#git-version-support-policy) | Minimum supported git version and how version bumps are communicated and enforced. |
419
+ | [Deprecation policy](#deprecation-policy) | When an API may be removed, what a deprecation warning says, and how to upgrade across a major version. |
420
+ | [Release support policy](#release-support-policy) | Which branch releases what, and how long each major series is supported. |
638
421
  | [GOVERNANCE](GOVERNANCE.md) | Principles-first governance defining maintainer/project lead roles, least-privilege access, consensus/majority decisions, and nomination/emeritus steps. |
639
422
  | [MAINTAINERS](MAINTAINERS.md) | Lists active maintainers (Project Lead noted) and emeritus alumni with links; see governance for role scope. |
640
423
  | [LICENSE](LICENSE) | MIT License terms for using, modifying, and redistributing this project. |
641
424
 
642
- ### Ruby Version Support Policy
425
+ ### Ruby version support policy
643
426
 
644
427
  This gem is expected to function correctly on:
645
428
 
646
429
  - All [non-EOL versions](https://www.ruby-lang.org/en/downloads/branches/) of the MRI
647
430
  Ruby on Mac, Linux, and Windows
648
- - The latest version of JRuby 9.4+ on Linux
649
- - The latest version of TruffleRuby 24+ on Linux
431
+ - JRuby and TruffleRuby on Linux, starting from the earliest release whose Ruby
432
+ compatibility target is at or above the oldest supported MRI version, unless a
433
+ newer release is otherwise needed (for example, when a release does not
434
+ implement a feature the gem depends on)
650
435
 
651
- It is this project's intent to support the latest version of JRuby on Windows once
436
+ Consult the CI build matrix in
437
+ [`.github/workflows/continuous_integration.yml`](.github/workflows/continuous_integration.yml)
438
+ for the exact JRuby and TruffleRuby versions tested. Newer releases of each engine
439
+ are expected to work but are not tested.
440
+
441
+ Because the JRuby and TruffleRuby floors derive from the MRI floor, they move
442
+ whenever the oldest supported MRI version changes.
443
+
444
+ This project intends to support the latest version of JRuby on Windows once
652
445
  the [process_executer](https://github.com/main-branch/process_executer) gem properly
653
446
  supports subprocess status reporting on JRuby for Windows (see
654
447
  [main-branch/process_executer#156](https://github.com/main-branch/process_executer/issues/156)).
655
448
 
656
- ### Git Version Support Policy
449
+ ### Git version support policy
450
+
451
+ This gem requires git 2.43.0 or later, as the gemspec declares. The floor weighs the
452
+ git features the gem depends on, the systems users still run, and the git versions
453
+ CI can test.
454
+
455
+ Git 2.43.0 was released on November 20, 2023. The gem may work with an older git,
456
+ but the project does not test or support versions before 2.43.0. Users on an older
457
+ git should upgrade to at least 2.43.0.
458
+
459
+ A later major or minor release may raise the floor when the gem adopts a newer git
460
+ feature or when keeping compatibility with an old git becomes impractical. The
461
+ CHANGELOG and release notes document each such change.
462
+
463
+ ### Deprecation policy
464
+
465
+ This gem removes an API only in a major release, and only after a normal release
466
+ deprecated it with a runtime warning and documented its replacement in
467
+ [UPGRADING.md](UPGRADING.md). A normal release is one that is not a pre-release. The
468
+ warning names the major release that removes the API once that is decided. Until then
469
+ it says the API will be removed in a future major release.
470
+
471
+ The recommended way to upgrade across a major version:
472
+
473
+ 1. Upgrade to the latest release of the major series you are on.
474
+ 2. Set `GIT_DEPRECATION_BEHAVIOR=raise` (or `Git::Deprecation.behavior = :raise`) in
475
+ your test suite and, if possible, staging.
476
+ 3. Fix each deprecation using the entries in [UPGRADING.md](UPGRADING.md) until the
477
+ suite is clean.
478
+ 4. Work through the changes that a clean run does not catch, listed in that major's
479
+ section of [UPGRADING.md](UPGRADING.md).
480
+ 5. Upgrade to the next major release.
481
+
482
+ Because every deprecation warning is present in the last release of a major series,
483
+ steps 2 and 3 find every call to a deprecated API. A major release may also change a
484
+ behavior that had no deprecation path, such as the return type of a method that
485
+ keeps its name; step 4 covers those. The version-specific steps are in
486
+ [UPGRADING.md](UPGRADING.md#upgrading-to-v6x). See [Deprecations](#deprecations)
487
+ for how to configure the warnings.
488
+
489
+ ### Release support policy
490
+
491
+ All development happens on `main`, which releases the next version of the gem,
492
+ including the next major version. The next release from `main` is v6.0.0. Every
493
+ further v5.x release is cut from `5.x`.
494
+
495
+ Each supported previous major series is maintained on a branch named for that
496
+ series, currently `5.x` and `4.x`. These branches receive bug fixes and security
497
+ fixes, and backward-compatible features at the maintainers' discretion. Fixes land on
498
+ `main` first and are backported, except a fix for a problem that exists only in a
499
+ maintenance branch, which targets that branch directly.
657
500
 
658
- This gem requires git version 2.28.0 or greater as specified in the gemspec. This
659
- requirement reflects:
501
+ Support for a major series ends when the second major after it is released. v4.x is
502
+ supported until v6.0.0 ships, and v5.x until v7.0.0.
660
503
 
661
- - The minimum git version necessary to support all features provided by this gem
662
- - A reasonable balance between supporting older systems and leveraging modern git
663
- capabilities
664
- - The practical limitations of testing across multiple git versions in CI
504
+ ## Project announcements
665
505
 
666
- Git 2.28.0 was released on July 27, 2020. While this gem may work with earlier
667
- versions of git, compatibility with versions prior to 2.28.0 is not tested or
668
- guaranteed. Users on older git versions should upgrade to at least 2.28.0.
506
+ ### 2026-09-04: v5.x releases move to the `5.x` branch
669
507
 
670
- The supported git version may be increased in future major or minor releases of this
671
- gem as new git features are adopted or as maintaining backward compatibility becomes
672
- impractical. Such changes will be clearly documented in the CHANGELOG and release
673
- notes.
508
+ On September 4, 2026, we created the `5.x` branch from v5.4.1. Every further v5.x
509
+ release is cut from that branch, and the next release from `main` is v6.0.0. Nothing
510
+ changes for users of the gem: v5.x continues to receive bug fixes and security fixes
511
+ per the [Release support policy](#release-support-policy), and v4.x is supported
512
+ until v6.0.0 ships.
674
513
 
675
- ## 📢 Project Announcements 📢
514
+ For contributors, fixes still land on `main` first and are backported to `5.x`. A fix
515
+ for a problem that exists only in v5.x targets `5.x` directly. See the
516
+ [branch strategy](CONTRIBUTING.md#branch-strategy) and
517
+ [issue #1717](https://github.com/ruby-git/ruby-git/issues/1717), the v6.0.0 roadmap.
676
518
 
677
- ### 2026-01-07: AI Policy Introduced
519
+ ### 2026-09-04: Retired branches deleted
520
+
521
+ On September 4, 2026, we deleted the `v1` and `master` branches. Neither had a
522
+ purpose: support for v1.x ended when v3.0.0 shipped, per the
523
+ [Release support policy](#release-support-policy), and `master` was the pre-rename
524
+ default branch, frozen since the rename to `main` on 2025-06-06. Every v1.x release
525
+ remains available as a tag, so nothing released was lost.
526
+
527
+ The branches that remain are the ones the release support policy describes: `main`
528
+ releases the next version, `4.x` maintains the v4.x series, and `5.x` maintains the
529
+ v5.x series. See [issue #1786](https://github.com/ruby-git/ruby-git/issues/1786) for
530
+ the details.
531
+
532
+ ### 2026-08-23: v5.x deprecations and the v6.0.0 roadmap
533
+
534
+ The v6.0.0 plan is public. The remaining ActiveRecord-style
535
+ classes (`Git::Branch`, `Git::Remote`, `Git::Stash`, `Git::Worktree`,
536
+ `Git::Object::Tag`, `Git::Status`, `Git::Author`, and their collections) will be
537
+ deprecated during the v5.x series in favor of the immutable `*Info` value-object
538
+ APIs. v6.0.0 will remove each deprecated class once a normal v5.x release has carried
539
+ its deprecation warning and UPGRADING.md entry, per the
540
+ [Deprecation policy](#deprecation-policy). v6.0.0 will not ship until every planned
541
+ deprecation has shipped that way. v6.0.0 also raises the version floors to git 2.43.0
542
+ and Ruby 3.3.
543
+
544
+ [Issue #1717](https://github.com/ruby-git/ruby-git/issues/1717) is the roadmap
545
+ and tracks scope, order, and status. If your code uses the classes above, you can
546
+ start migrating now. Each deprecation names its replacement, and
547
+ [UPGRADING.md](UPGRADING.md) carries the migration guide as releases ship.
548
+
549
+ ### 2026-07-28: v5.0.0 released
550
+
551
+ We have published [`git v5.0.0`](https://rubygems.org/gems/git/versions/5.0.0), the
552
+ first stable release of the v5.x series, after five public beta releases in June and
553
+ July 2026.
554
+
555
+ v5.0.0 is a major release with breaking changes. See
556
+ [UPGRADING.md](UPGRADING.md) for the complete migration guide.
557
+
558
+ To install:
559
+
560
+ ```ruby
561
+ gem 'git', '~> 5.0'
562
+ ```
563
+
564
+ Or:
565
+
566
+ ```sh
567
+ gem install git
568
+ ```
678
569
 
679
- We have adopted a formal [AI Policy](AI_POLICY.md) to clarify expectations for
680
- AI-assisted contributions. Please review it before opening a PR to ensure your
681
- changes are fully understood, meet our quality bar, and respect licensing
682
- requirements.
570
+ Most v4.x code requires no changes. Compatibility shims keep the old API working
571
+ while emitting deprecation warnings that tell you what to migrate before v6.0.0.
683
572
 
684
- We chose a principles-based policy to respect contributors’ time and expertise. It’s
685
- quick to read, easy to remember, and avoids unnecessary policy overhead while still
686
- setting clear expectations.
573
+ ### 2026-01-07: AI policy introduced
687
574
 
688
- ### 2025-07-09: Architectural Redesign
575
+ We have adopted an [AI Policy](AI_POLICY.md) that sets expectations for
576
+ AI-assisted contributions. Read it before opening a PR. It asks that you understand
577
+ every change you submit, that the work meets the project's quality bar, and that it
578
+ respects licensing requirements.
689
579
 
690
- The git gem is undergoing a significant architectural redesign for the upcoming
691
- v5.0.0 release. The current architecture has several design challenges that make it
692
- difficult to maintain and evolve. This redesign aims to address these issues by
693
- introducing a clearer, more robust, and more testable structure.
580
+ The policy states principles rather than a checklist, so it is short to read and
581
+ still sets clear expectations.
694
582
 
695
- We have prepared detailed documents outlining the analysis of the current
696
- architecture and the proposed changes. We encourage our community and contributors to
697
- review them:
583
+ ### 2025-07-09: Architectural redesign
698
584
 
699
- 1. [Analysis of the Current Architecture](redesign/1_architecture_existing.md): A
700
- breakdown of the existing design and its challenges.
701
- 2. [The Proposed Redesign](redesign/2_architecture_redesign.md): An overview of the
702
- new three-layered architecture.
703
- 3. [Implementation Plan](redesign/3_architecture_implementation.md): The step-by-step
704
- plan for implementing the redesign.
585
+ On this date we announced an architectural redesign of the git gem. The architecture
586
+ at the time was difficult to maintain and change. The redesign replaced it with a
587
+ three-layer structure of commands, parsers, and a `Git::Repository` facade, which is
588
+ easier to test because each layer can be exercised on its own.
705
589
 
706
- Your feedback is welcome! Please feel free to open an issue to discuss the proposed
707
- changes.
590
+ The redesign shipped in v5.0.0 and is complete. `Git::Base` and `Git::Lib` are
591
+ gone, along with the `g.lib` accessor. See [UPGRADING.md](UPGRADING.md) for what
592
+ changed and how to migrate.
708
593
 
709
- > **DON'T PANIC!**
710
- >
711
- > While this is a major internal refactoring, our goal is to keep the primary public
712
- API on the main repository object as stable as possible. Most users who rely on
713
- documented methods like `g.commit`, `g.add`, and `g.status` should find the
714
- transition to v5.0.0 straightforward.
715
- >
716
- > The breaking changes will primarily affect users who have been relying on the
717
- internal g.lib accessor, which will be removed as part of this cleanup. For more
718
- details, please see the "Impact on Users" section in [the redesign
719
- document](redesign/2_architecture_redesign.md).
594
+ The three documents written to plan it are kept as a historical record in
595
+ [`archive/v5-redesign/`](archive/v5-redesign/). They describe the state of the code
596
+ before and during the migration and are not current policy. The standards that apply
597
+ to new code live in [`.github/skills/`](.github/skills/).
720
598
 
721
- ### 2025-07-07: We Now Use RuboCop
599
+ 1. [Analysis of the Current Architecture](archive/v5-redesign/1_architecture_existing.md):
600
+ a breakdown of the v4.x design and its challenges.
601
+ 2. [The Proposed Redesign](archive/v5-redesign/2_architecture_redesign.md): an overview
602
+ of the three-layer architecture.
603
+ 3. [Implementation Plan](archive/v5-redesign/3_architecture_implementation.md): the
604
+ step-by-step plan that was followed.
722
605
 
723
- To improve code consistency and maintainability, the `ruby-git` project has now
724
- adopted [RuboCop](https://rubocop.org/) as our static code analyzer and formatter.
606
+ ### 2025-07-07: We now use RuboCop
725
607
 
726
- This integration is a key part of our ongoing commitment to making `ruby-git` a
727
- high-quality, stable, and easy-to-contribute-to project. All new contributions will
728
- be expected to adhere to the style guidelines enforced by our RuboCop configuration.
608
+ The `ruby-git` project has adopted [RuboCop](https://rubocop.org/) as its static
609
+ code analyzer and formatter so that contributions share one style. All new
610
+ contributions must follow the style rules the project's RuboCop configuration
611
+ enforces.
729
612
 
730
- RuboCop can be run from the project's Rakefile:
613
+ Run RuboCop from the project's Rakefile:
731
614
 
732
615
  ```shell
733
616
  rake rubocop
734
617
  ```
735
618
 
736
- RuboCop is also run as part of the default rake task (by running `rake`) that is run
737
- in our Continuous Integration workflow.
619
+ RuboCop also runs as part of the default rake task, which our continuous integration
620
+ workflow runs.
738
621
 
739
- Going forward, any PRs that have any Robocop offenses will not be merged. In certain
740
- rare cases, it might be acceptable to disable a RuboCop check for the most limited
741
- scope possible.
622
+ PRs with RuboCop offenses will not be merged. In rare cases, it might be acceptable
623
+ to disable a RuboCop check for the most limited scope possible.
742
624
 
743
- If you have a problem fixing a RuboCop offense, don't be afraid to ask a
625
+ If you have a problem fixing a RuboCop offense, don't be afraid to ask a
744
626
  contributor.
745
627
 
746
- ### 2025-06-06: Default Branch Rename
628
+ ### 2025-06-06: Default branch rename
747
629
 
748
- On June 6th, 2025, the default branch was renamed from 'master' to 'main'.
630
+ On June 6, 2025, we renamed the default branch from `master` to `main`.
749
631
 
750
- Instructions for renaming your local or forked branch to match can be found in the
751
- gist [Default Branch Name
632
+ Instructions for renaming your local or forked branch to match are in the gist
633
+ [Default Branch Name
752
634
  Change](https://gist.github.com/jcouball/580a10e395f7fdfaaa4297bbe816cc7d).
753
635
 
754
- ### 2025-05-15: We've Switched to Conventional Commits
636
+ ### 2025-05-15: We've switched to Conventional Commits
755
637
 
756
- To enhance our development workflow, enable automated changelog generation, and pave
757
- the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional
758
- Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit
759
- messages.
638
+ The `ruby-git` project has adopted the [Conventional Commits
639
+ standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages.
640
+ This enables automated changelog generation and is a step toward continuous
641
+ delivery.
760
642
 
761
- Going forward, all commits to this repository **MUST** adhere to the Conventional
762
- Commits standard. Commits not adhering to this standard will cause the CI build to
763
- fail. PRs will not be merged if they include non-conventional commits.
643
+ All commits to this repository must follow the Conventional Commits standard.
644
+ Commits that do not follow it will fail the CI build, and PRs that include them will
645
+ not be merged.
764
646
 
765
- A git pre-commit hook may be installed to validate your conventional commit messages
766
- before pushing them to GitHub by running `bin/setup` in the project root.
647
+ To validate your commit messages locally before pushing them to GitHub, install the
648
+ git `commit-msg` hook by running `bin/setup` in the project root.
767
649
 
768
650
  Read more about this change in the [Commit Message Guidelines section of
769
- CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines)
651
+ CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines).