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/CONTRIBUTING.md CHANGED
@@ -8,44 +8,60 @@
8
8
  - [Summary](#summary)
9
9
  - [How to contribute](#how-to-contribute)
10
10
  - [How to report an issue or request a feature](#how-to-report-an-issue-or-request-a-feature)
11
+ - [Local development setup](#local-development-setup)
12
+ - [Prerequisites](#prerequisites)
13
+ - [A note for Windows contributors](#a-note-for-windows-contributors)
14
+ - [Bootstrap the project](#bootstrap-the-project)
15
+ - [Verify the toolchain](#verify-the-toolchain)
16
+ - [Contributor validation policy](#contributor-validation-policy)
11
17
  - [How to submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
12
18
  - [Commit your changes to a fork of `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git)
13
19
  - [Create a pull request](#create-a-pull-request)
14
20
  - [Get your pull request reviewed](#get-your-pull-request-reviewed)
21
+ - [Before requesting review](#before-requesting-review)
15
22
  - [Branch strategy](#branch-strategy)
16
23
  - [AI-assisted contributions](#ai-assisted-contributions)
24
+ - [Agent configuration](#agent-configuration)
25
+ - [Agent skills](#agent-skills)
17
26
  - [Design philosophy](#design-philosophy)
18
- - [Direct mapping to git commands](#direct-mapping-to-git-commands)
19
- - [Parameter naming](#parameter-naming)
20
- - [Output processing](#output-processing)
27
+ - [Layered architecture](#layered-architecture)
28
+ - [Implementing a git command](#implementing-a-git-command)
29
+ - [API design](#api-design)
30
+ - [Method placement](#method-placement)
31
+ - [Method naming](#method-naming)
32
+ - [Result class naming](#result-class-naming)
33
+ - [Parameter naming](#parameter-naming)
34
+ - [Parameter values](#parameter-values)
35
+ - [Output processing](#output-processing)
36
+ - [Implementation](#implementation)
37
+ - [Example implementations](#example-implementations)
21
38
  - [Coding standards](#coding-standards)
22
39
  - [Commit message guidelines](#commit-message-guidelines)
23
40
  - [What does this mean for contributors?](#what-does-this-mean-for-contributors)
24
41
  - [What to know about Conventional Commits](#what-to-know-about-conventional-commits)
25
- - [Unit tests](#unit-tests)
26
- - [Continuous integration](#continuous-integration)
27
- - [Documentation](#documentation)
42
+ - [Issue and PR references](#issue-and-pr-references)
43
+ - [Testing guidelines](#testing-guidelines)
44
+ - [Test coverage policy](#test-coverage-policy)
45
+ - [Unit tests vs integration tests](#unit-tests-vs-integration-tests)
46
+ - [What ships in the gem](#what-ships-in-the-gem)
28
47
  - [Building a specific version of the Git command-line](#building-a-specific-version-of-the-git-command-line)
29
- - [Install pre-requisites](#install-pre-requisites)
48
+ - [Install prerequisites](#install-prerequisites)
30
49
  - [Obtain Git source code](#obtain-git-source-code)
31
50
  - [Build git](#build-git)
32
51
  - [Use the new Git version](#use-the-new-git-version)
33
- - [Licensing](#licensing)
34
52
 
35
53
  ## Summary
36
54
 
37
55
  Thank you for your interest in contributing to the `ruby-git` project.
38
56
 
39
- This document provides guidelines for contributing to the `ruby-git` project. While
40
- these guidelines may not cover every situation, we encourage you to use your best
41
- judgment when contributing.
57
+ This document provides guidelines for contributing to the `ruby-git` project. They
58
+ may not cover every situation, so use your best judgment.
42
59
 
43
60
  If you have suggestions for improving these guidelines, please propose changes via a
44
61
  pull request.
45
62
 
46
63
  Please also review and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) when
47
- participating in the project.
48
- Governance and maintainer expectations are described in
64
+ participating in the project. Governance and maintainer expectations are described in
49
65
  [GOVERNANCE.md](GOVERNANCE.md).
50
66
 
51
67
  ## How to contribute
@@ -59,7 +75,7 @@ You can contribute in the following ways:
59
75
 
60
76
  ## How to report an issue or request a feature
61
77
 
62
- `ruby-git` utilizes [GitHub
78
+ `ruby-git` uses [GitHub
63
79
  Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
64
80
  for issue tracking and feature requests.
65
81
 
@@ -67,9 +83,91 @@ To report an issue or request a feature, please [create a `ruby-git` GitHub
67
83
  issue](https://github.com/ruby-git/ruby-git/issues/new). Fill in the template as
68
84
  thoroughly as possible to describe the issue or feature request.
69
85
 
86
+ ## Local development setup
87
+
88
+ Before submitting a change, set up a working local development environment.
89
+ `bin/setup` automates the bootstrap and fails fast with a clear message when a
90
+ prerequisite is missing.
91
+
92
+ ### Prerequisites
93
+
94
+ | Tool | Required version | Notes |
95
+ | --- | --- | --- |
96
+ | Ruby | `>= 3.3.0` (matches `required_ruby_version` in [`git.gemspec`](git.gemspec)) | A version manager such as [rbenv](https://github.com/rbenv/rbenv), [asdf](https://asdf-vm.com/), [chruby](https://github.com/postmodern/chruby), or [rvm](https://rvm.io/) is recommended so you can match the project's CI matrix. |
97
+ | Bundler | Any 2.x or 4.x | Install with `gem install bundler`. |
98
+ | git | `>= 2.43.0` (matches `git.gemspec` `requirements`) | Older git versions are not supported and the test suite will not pass against them. |
99
+ | Node.js / npm | Optional | Required only to install the local Conventional Commit `commit-msg` hook (Husky + commitlint). If npm is missing, `bin/setup` will warn and continue. CI will still validate commit messages. |
100
+ | [lychee](https://lychee.cli.rs) | `>= 0.24.0` | Runs the markdown link check (`rake markdown:links`), which is part of the default task. The floor comes from [`.lychee.toml`](.lychee.toml): older releases cannot parse the enum form of `include_fragments`. Install with `brew install lychee` (macOS), `snap install lychee` (Ubuntu), `pacman -S lychee` (Arch), `winget install --id lycheeverse.lychee` (Windows), or see the [install docs](https://github.com/lycheeverse/lychee#installation). |
101
+
102
+ #### A note for Windows contributors
103
+
104
+ A few unit specs create real symlinks, which on Windows requires
105
+ `SeCreateSymbolicLinkPrivilege`. A non-elevated process only holds that privilege
106
+ when Developer Mode is enabled (Settings → System → For developers). Without it
107
+ those specs skip rather than fail, so `bundle exec rake` still passes, but the
108
+ behavior they cover goes unverified locally.
109
+
110
+ The same privilege decides whether Git for Windows materializes the committed
111
+ `.claude/skills` symlink, so enabling Developer Mode fixes both at once. See
112
+ [Agent configuration](#agent-configuration).
113
+
114
+ ### Bootstrap the project
115
+
116
+ From the project root, run:
117
+
118
+ ```shell
119
+ bin/setup
120
+ ```
121
+
122
+ `bin/setup` will:
123
+
124
+ 1. Verify the prerequisites above and exit with a non-zero status if any are
125
+ missing, or if Ruby, git, or lychee is out of date. (Bundler is only
126
+ checked for presence, not version.)
127
+ 2. Run `bundle install` to install Ruby gem dependencies.
128
+ 3. Run `npm install` (when npm is available) to install the Conventional Commit
129
+ `commit-msg` hook used by this project (Husky + commitlint). A separate
130
+ `pre-commit` hook is also installed that blocks direct commits to the
131
+ protected branches (`main`, `5.x`, `4.x`).
132
+ 4. Verify the toolchain by running `bundle exec rake --tasks`.
133
+
134
+ `bin/setup` checks for [lychee](https://lychee.cli.rs) alongside Ruby, git, and
135
+ Bundler, and exits non-zero when it is missing or too old. lychee is a Rust binary
136
+ rather than a gem, so `bundle install` cannot supply it and `bin/setup` cannot
137
+ install it for you. Every platform this project supports has a packaged build,
138
+ and the error message names the command for yours.
139
+
140
+ ### Verify the toolchain
141
+
142
+ Once `bin/setup` succeeds, confirm the full test and lint suite passes locally:
143
+
144
+ ```shell
145
+ bundle exec rake
146
+ ```
147
+
148
+ This runs everything CI checks: specs, RuboCop, the markdown link check, YARD,
149
+ and the gem build. It is the canonical way to validate a change before
150
+ requesting review.
151
+
152
+ One caveat on the `links` task: passing locally does not guarantee the CI job
153
+ passes, and the gap is the environment rather than the tool. A link whose
154
+ capitalization is wrong resolves on a case-insensitive filesystem such as macOS and
155
+ 404s on the Linux runner, so `](docs/README.MD)` against a file named `README.md`
156
+ looks fine locally and fails in CI. [`tasks/markdown.rake`](tasks/markdown.rake) lists
157
+ this and the other differences. CI remains the authoritative link check.
158
+
159
+ ### Contributor validation policy
160
+
161
+ Contributors are expected to run `bundle exec rake` locally and confirm it
162
+ passes before requesting review on a pull request. Trivial documentation-only
163
+ fixes (e.g., typo corrections in markdown files) are excepted. "CI passed" is
164
+ not a substitute for local validation; it is a backstop. This applies equally to
165
+ human-authored and AI-assisted contributions. See
166
+ [AI-assisted contributions](#ai-assisted-contributions).
167
+
70
168
  ## How to submit a code or documentation change
71
169
 
72
- There is a three-step process for submitting code or documentation changes:
170
+ Submitting a code or documentation change has three steps:
73
171
 
74
172
  1. [Commit your changes to a fork of
75
173
  `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git) using [Conventional
@@ -97,128 +195,679 @@ feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-re
97
195
  Once your pull request is ready for review, request a review from at least one
98
196
  [maintainer](MAINTAINERS.md) and any other contributors you deem necessary.
99
197
 
100
- During the review process, you may need to make additional commits, which should be
101
- squashed. Additionally, you will need to rebase your branch to the latest version of
102
- the target branch (e.g., `main` or `4.x`) before merging.
198
+ During the review process, you may need to make additional commits; squash them.
199
+ You will also need to rebase your branch onto the latest version of the target
200
+ branch (e.g., `main`, `5.x`, or `4.x`) before merging.
103
201
 
104
202
  At least one approval from a project maintainer is required before your pull request
105
203
  can be merged. The maintainer is responsible for ensuring that the pull request meets
106
204
  [the project's coding standards](#coding-standards).
107
205
 
206
+ ### Before requesting review
207
+
208
+ Before moving a pull request out of draft or requesting a review, confirm:
209
+
210
+ - [ ] `bundle exec rake` passes locally on your branch (see
211
+ [Local development setup](#local-development-setup)).
212
+ - [ ] New or changed code has accompanying tests under `spec/`
213
+ (see [Unit tests vs integration tests](#unit-tests-vs-integration-tests)).
214
+ - [ ] Every commit message follows [Conventional Commits](#commit-message-guidelines).
215
+ - [ ] User-facing changes are documented in `README.md` and/or YARD as appropriate.
216
+
217
+ These checks mirror what reviewers and CI will look for; running them locally
218
+ first keeps the review cycle short.
219
+
108
220
  ## Branch strategy
109
221
 
110
- This project maintains two active branches:
222
+ This project maintains `main` plus one maintenance branch for each supported previous
223
+ major series:
111
224
 
112
- - **`main`**: Active development for the next major version (v5.0.0+). This branch
113
- may contain breaking changes.
114
- - **`4.x`**: Maintenance branch for the v4.x release series. This branch receives
115
- bug fixes and backward-compatible improvements only.
225
+ - **`main`**: All development. It releases the next version of the gem, including
226
+ the next major version. Its next release is v6.0.0; every further v5.x release is
227
+ cut from `5.x`.
228
+ - **`5.x`** and **`4.x`**: The maintenance branches for the v5.x and v4.x series. Each
229
+ receives bug fixes and security fixes, and backward-compatible features at the
230
+ maintainers' discretion. A fix that changes the class of a raised exception is
231
+ backported only when it passes the rescue-compatibility test in
232
+ [Branch & PR Strategy](.github/copilot-instructions.md#branch--pr-strategy).
116
233
 
117
- **Important:** Never commit directly to `main` or `4.x`. All changes must be
118
- submitted via pull requests from feature branches. This ensures proper code review,
119
- CI validation, and maintains a clean commit history.
234
+ The README's [Release support policy](README.md#release-support-policy) says how long
235
+ each major series is supported.
120
236
 
121
237
  When submitting a pull request:
122
238
 
123
239
  - **New features and breaking changes**: Target the `main` branch
124
- - **Bug fixes**: Target `main`, and maintainers will backport to `4.x` if applicable
125
- - **Security fixes**: Target both branches or `4.x` if the issue only affects v4.x
240
+ - **Bug fixes**: Target `main`, and maintainers will backport to the maintenance
241
+ branches if applicable and the change passes the rescue-compatibility test above
242
+ - **Security fixes**: Target `main` and every affected maintenance branch, or only a
243
+ maintenance branch if the issue affects that series alone
244
+
245
+ Removing a deprecated API follows the
246
+ [deprecation policy](.github/skills/breaking-change-analysis/SKILL.md#step-4-deprecation-policy):
247
+
248
+ A removal PR merges to main only when its deprecation warning and `UPGRADING.md` entry
249
+ are contained in a previous normal release. Once any removal has merged to main, main
250
+ becomes the release line for the next major version. If another release of the
251
+ previous major is needed, it is cut from a branch created for that major (e.g. `4.x`
252
+ or `5.x`).
126
253
 
127
254
  ## AI-assisted contributions
128
255
 
129
- AI-assisted contributions are welcome. Please review and apply our [AI Policy](AI_POLICY.md)
130
- before submitting changes. You are responsible for understanding and verifying any
131
- AI-assisted work included in PRs and ensuring it meets our standards for quality,
132
- security, and licensing.
256
+ AI-assisted contributions are welcome. Please review and apply our [AI
257
+ Policy](AI_POLICY.md) before submitting changes. You are responsible for
258
+ understanding and verifying any AI-assisted work included in PRs and ensuring it
259
+ meets our standards for quality, security, and licensing.
260
+
261
+ The human submitter, not the AI agent, is responsible for ensuring that
262
+ `bundle exec rake` passes locally before requesting review. This is true even
263
+ when the change was authored end-to-end by an agent. "The agent ran the tests"
264
+ and "CI is green" are not substitutes for the submitter running
265
+ [the local validation step](#contributor-validation-policy) themselves; CI is a
266
+ backstop, not a primary validation surface.
267
+
268
+ ### Agent configuration
269
+
270
+ Agent configuration is shared: each piece of guidance is stored once and surfaced to
271
+ every supported agent.
272
+
273
+ | Content | Canonical location | Also read by |
274
+ | --- | --- | --- |
275
+ | Project instructions | [`.github/copilot-instructions.md`](.github/copilot-instructions.md) | Claude Code, via an import in [`CLAUDE.md`](CLAUDE.md) |
276
+ | Skills | [`.github/skills/`](.github/skills/) | Claude Code, via the `.claude/skills` symlink |
277
+ | Setup hook | [`.github/hooks/run-bin-setup-once.sh`](.github/hooks/run-bin-setup-once.sh) | Claude Code, via `.claude/settings.json` |
278
+
279
+ Always edit the canonical file. The Claude Code side is a pointer in every case, so
280
+ changes reach both agents without a sync step.
281
+
282
+ One caveat: `.claude/skills` is a committed symlink. Git for Windows only
283
+ materializes symlinks when `core.symlinks` is enabled (which requires Developer Mode
284
+ or an elevated shell). Without it, Windows contributors get a plain text file there
285
+ and Claude Code silently loads no skills; either enable symlinks or point your agent
286
+ at [`.github/skills/`](.github/skills/) directly. Copilot is unaffected.
287
+
288
+ The symlink stays out of the published gem, so it never reaches users. See
289
+ [What ships in the gem](#what-ships-in-the-gem).
290
+
291
+ ### Agent skills
292
+
293
+ If you use an AI coding agent that understands repository skills, the
294
+ [`.github/skills/`](.github/skills/) directory contains optional, project-specific
295
+ guidance that mirrors maintainer expectations:
296
+
297
+ - [`project-context`](.github/skills/project-context/SKILL.md): architecture, coding
298
+ standards, design philosophy, and compatibility requirements
299
+ - [`development-workflow`](.github/skills/development-workflow/SKILL.md): TDD workflow
300
+ for bug fixes, features, refactoring, and maintenance tasks
301
+ - [`command-implementation`](.github/skills/command-implementation/SKILL.md) and
302
+ [`facade-implementation`](.github/skills/facade-implementation/SKILL.md): guidance for
303
+ adding or updating command classes and `Git::Repository` facade methods
304
+ - [`review-arguments-dsl`](.github/skills/review-arguments-dsl/SKILL.md): audits
305
+ `arguments do ... end` blocks against the git CLI
306
+ - [`rspec-unit-testing-standards`](.github/skills/rspec-unit-testing-standards/SKILL.md),
307
+ [`rspec-integration-testing-standards`](.github/skills/rspec-integration-testing-standards/SKILL.md),
308
+ [`rspec-base-standards`](.github/skills/rspec-base-standards/SKILL.md),
309
+ [`command-test-conventions`](.github/skills/command-test-conventions/SKILL.md), and
310
+ [`facade-test-conventions`](.github/skills/facade-test-conventions/SKILL.md): testing
311
+ conventions for new and updated code
312
+ - [`testing-guide`](.github/skills/testing-guide/SKILL.md): the vocabulary those
313
+ conventions are written in, and how this project applies the shared testing guide
314
+ - [`yard-documentation`](.github/skills/yard-documentation/SKILL.md),
315
+ [`command-yard-documentation`](.github/skills/command-yard-documentation/SKILL.md), and
316
+ [`facade-yard-documentation`](.github/skills/facade-yard-documentation/SKILL.md):
317
+ documentation standards
318
+ - [`test-debugging`](.github/skills/test-debugging/SKILL.md) and
319
+ [`ci-cd-troubleshooting`](.github/skills/ci-cd-troubleshooting/SKILL.md): help for
320
+ failing or flaky tests and CI failures
321
+ - [`breaking-change-analysis`](.github/skills/breaking-change-analysis/SKILL.md): impact
322
+ analysis before removing methods, changing interfaces, or planning deprecations
323
+ - [`pr-readiness-review`](.github/skills/pr-readiness-review/SKILL.md): final checks
324
+ before requesting review
133
325
 
134
326
  ## Design philosophy
135
327
 
136
- *Note: As of v2.x of the `git` gem, this design philosophy is aspirational. Future
137
- versions may include interface changes to fully align with these principles.*
328
+ The `git` gem lets users apply what they already know about Git while working in
329
+ idiomatic Ruby.
138
330
 
139
- The `git` gem is designed as a lightweight wrapper around the `git` command-line
140
- tool, providing Ruby developers with a simple and intuitive interface for
141
- programmatically interacting with Git.
331
+ Its public API is a lightweight wrapper around the `git` command-line tool that
332
+ gives Ruby developers a direct way to run Git programmatically.
142
333
 
143
- This gem adheres to the "principle of least surprise," ensuring that it does not
144
- introduce unnecessary abstraction layers or modify Git's core functionality. Instead,
145
- the gem maintains a close alignment with the existing `git` command-line interface,
146
- avoiding extensions or alterations that could lead to unexpected behaviors.
334
+ This gem follows the principle of least surprise: it does not add unnecessary
335
+ abstraction layers or modify Git's core functionality. It stays close to the existing `git`
336
+ command-line interface and avoids extensions or alterations that could lead to
337
+ unexpected behavior.
147
338
 
148
- By following this philosophy, the `git` gem allows users to leverage their existing
149
- knowledge of Git while benefiting from the expressiveness and power of Ruby's syntax
150
- and paradigms.
339
+ `git` commands generally translate to `Git::Repository` methods of the same name.
340
+ Positional arguments map to the `git` CLI operands (such as paths and SHAs) in the
341
+ same order. Keyword arguments map to `git` CLI options by long OR short name.
151
342
 
152
- ### Direct mapping to git commands
343
+ Some examples:
153
344
 
154
- Git commands are implemented within the `Git::Base` class, with each method directly
155
- corresponding to a `git` command. When a `Git::Base` object is instantiated via
156
- `Git.open`, `Git.clone`, or `Git.init`, the user can invoke these methods to interact
157
- with the underlying Git repository.
345
+ - To execute `git clone <url> --depth=1`, call `Git.clone(url, depth: 1)`
346
+ - To execute `git add <path> --force`, call `Git::Repository#add(path, force: true)`
158
347
 
159
- For example, the `git add` command is implemented as `Git::Base#add`, and the `git
160
- ls-files` command is implemented as `Git::Base#ls_files`.
348
+ ## Layered architecture
161
349
 
162
- When a single Git command serves multiple distinct purposes, method names within the
163
- `Git::Base` class should use the `git` command name as a prefix, followed by a
164
- descriptive suffix to indicate the specific function.
350
+ The `git` gem is organized into three architectural layers:
165
351
 
166
- For instance, `#ls_files_untracked` and `#ls_files_staged` could be used to execute
167
- the `git ls-files` command and return untracked and staged files, respectively.
352
+ | Layer | Responsibility | Mechanism |
353
+ | --- | --- | --- |
354
+ | **Facade** (`Git::Repository` and `Git`) | Public API | Normalizes Ruby arguments, sets safe defaults, calls one or more `Git::Commands::*` classes, and may parse output into public Ruby objects |
355
+ | **Command** (`Git::Commands::*`) | Neutral git CLI interface | Declares CLI arguments via the [Arguments DSL](lib/git/commands/arguments.rb), builds the git argv and executes git via `#call`, and returns `Git::CommandLine::Result` |
356
+ | **Execution** (`Git::ExecutionContext::*`) | Execution context and subprocess defaults | Carries execution settings such as working directory, environment, timeout, binary path, and logging; runs the git CLI with default global options (such as `-c color.ui=false`) and subprocess environment variables (such as a platform-conditional `LC_ALL`, which is `en_US.UTF-8` on macOS and `C.UTF-8` elsewhere) |
168
357
 
169
- To enhance usability, aliases may be introduced to provide more user-friendly method
170
- names where appropriate.
358
+ Command classes (`Git::Commands::*`) are **faithful, neutral representations of the
359
+ git CLI**. Each command class does the following:
171
360
 
172
- ### Parameter naming
361
+ - Declares acceptable CLI arguments and options via the
362
+ [Arguments DSL](lib/git/commands/arguments.rb)
363
+ - Defines a `#call` method which:
364
+ - Maps its parameters to the git argv using the declared arguments
365
+ - Executes a git CLI command via `Git::ExecutionContext`
366
+ - Returns the unprocessed git CLI result as a `Git::CommandLine::Result` object
173
367
 
174
- Parameters within the `git` gem methods are named after their corresponding long
175
- command-line options, ensuring familiarity and ease of use for developers already
176
- accustomed to Git. Note that not all Git command options are supported.
368
+ Command classes should not embed choices such as output format flags, editor
369
+ suppression, progress output, or verbose mode. These decisions belong to the facade
370
+ layer which sets them as needed. The facade layer may give callers the choice to
371
+ override those decisions when appropriate (e.g., running in a TTY-attached
372
+ environment where an editor is desired).
373
+
374
+ For example:
375
+
376
+ - **Anti-pattern:** declaring non-overridable and non-default options in the Arguments
377
+ DSL to control output such as `literal '--no-edit'`, `literal '--verbose'`, or
378
+ `literal '--no-progress'` inside a command class. This embeds policy in the wrong
379
+ layer.
380
+ - **Correct pattern:** declaring options which allow the user of the command (often a
381
+ facade method) to set desired values such as: `flag_option :edit, negatable: true`.
382
+ This allows the facade to either accept the default or to hard code `edit: false`
383
+ if it is needed.
384
+
385
+ This separation keeps command classes reusable across facade methods with different
386
+ policy needs. For example, a facade method that parses command output may pass
387
+ options such as `no_color: true`, `z: true`, or a fixed `format:` value so git emits
388
+ a stable, parseable output shape. Those parser-contract options belong at the facade
389
+ call site, not as hard-coded literals in the command class. Other facade methods can
390
+ reuse the same command class with different options.
391
+
392
+ ## Implementing a git command
393
+
394
+ Start with the official git documentation page for the command (e.g., `man git-add`
395
+ or the [git-scm.com](https://git-scm.com/docs) reference page). Its SYNOPSIS line
396
+ identifies the positional operands, and its OPTIONS section identifies the flags and
397
+ value options the Ruby method must expose.
398
+
399
+ Implementing the command has two major tasks: [API design](#api-design) and
400
+ [Implementation](#implementation).
401
+
402
+ ### API design
403
+
404
+ This section covers where git command methods belong, how to name them, and how to
405
+ handle parameters and output. These describe the public interface that gem
406
+ users will see.
407
+
408
+ #### Method placement
409
+
410
+ The public API is `Git::Repository` (and the `Git` module). These facade methods must
411
+ be exposed there, even when their implementation lives in private mixin modules or
412
+ `Git::Commands::*` classes.
413
+
414
+ **Repository factory commands** are exposed via `Git` as module methods and
415
+ are usually implemented in the `Git::Factories` mixin. These methods return a
416
+ `Git::Repository` object for subsequent operations:
417
+
418
+ ```ruby
419
+ repo = Git.clone('https://github.com/user/repo.git', 'local_path')
420
+ repo = Git.init('new_repo', initial_branch: 'main')
421
+ repo = Git.open('.')
422
+ ```
423
+
424
+ **Repository-scoped commands** require a repository context. These methods are
425
+ exposed via `Git::Repository` instance methods and are usually implemented in a
426
+ `Git::Repository::*` mixin.
427
+
428
+ ```ruby
429
+ repo.add('file.txt')
430
+ repo.commit('Add file')
431
+ repo.log
432
+ ```
433
+
434
+ **Global commands** do not require a repository context. Expose these
435
+ as methods on the `Git` module:
436
+
437
+ ```ruby
438
+ Git.config_get('user.name', global: true)
439
+ Git.config_set('user.email', 'user@example.com', global: true)
440
+ ```
441
+
442
+ Some commands, like `git config` commands, can be called either in a global or
443
+ repository scope. Here is how that was solved for the config commands:
444
+
445
+ - When called via the `Git` module, a scope parameter such as `global: true`,
446
+ `system: true`, or `file: <filename>` MUST be given. `local` and `worktree`
447
+ scopes are not allowed.
448
+
449
+ - When called via a `Git::Repository` instance, `local: true` and `worktree: true`
450
+ scope parameters may be given, with `local` being the default if no scope is given.
451
+ `global`, `system`, and `file` scopes are also allowed.
452
+
453
+ #### Method naming
454
+
455
+ Each method corresponds directly to a `git` command. For example, the `git add`
456
+ command is implemented as `Git::Repository#add`, and the `git ls-files` command is
457
+ implemented as `Git::Repository#ls_files`.
458
+
459
+ When a single Git command serves multiple distinct purposes, method names should use
460
+ the git command name as a prefix, followed by a descriptive suffix indicating the
461
+ specific function. The suffix should correspond to the git option that distinguishes
462
+ the behavior.
463
+
464
+ For example, `git config` supports `--get`, `--set`, `--list`, `--unset`, and other
465
+ options. These are implemented as separate methods:
466
+
467
+ ```ruby
468
+ repo.config_get('user.name') # git config --get user.name
469
+ repo.config_set('user.name', 'Scott') # git config user.name Scott
470
+ repo.config_list # git config --list
471
+ repo.config_unset('user.name') # git config --unset user.name
472
+ repo.config_get_all('remote.origin.url') # git config --get-all remote.origin.url
473
+ ```
474
+
475
+ Aliases may be added to provide friendlier method names where appropriate.
476
+
477
+ See also [Output processing](#output-processing) for when different output formats
478
+ require separate methods.
177
479
 
178
- ### Output processing
480
+ #### Result class naming
179
481
 
180
- The `git` gem translates the output of many Git commands into Ruby objects, making it
482
+ Parsed result objects returned from facade methods follow a reserved suffix
483
+ convention:
484
+
485
+ - **`*Info`**: a parsed metadata struct returned from a query (e.g., `BranchInfo`,
486
+ `TagInfo`, `StashInfo`, `DiffInfo`). Always lives in the top-level `Git::`
487
+ namespace.
488
+ - **`*Result`**: the outcome of a mutating or destructive operation (e.g.,
489
+ `BranchDeleteResult`, `TagDeleteResult`). Also lives in `Git::`.
490
+
491
+ Do not use these suffixes on `Git::Commands::*` command classes. Those are
492
+ subprocess runners, not data objects. A reader seeing `Commands::Foo::BarInfo`
493
+ expects a parsed struct, not a class that shells out to git.
494
+
495
+ #### Parameter naming
496
+
497
+ Parameters within the `git` gem methods are named after their corresponding long
498
+ command-line options, so developers already accustomed to Git will recognize them.
499
+
500
+ For example, `git config --global` becomes `global: true`, and `git config --file`
501
+ becomes `file: '/path/to/config'`.
502
+
503
+ As a lightweight wrapper, the gem passes options directly to the git command-line.
504
+ This means git itself will validate option combinations and report errors. This
505
+ approach is preferred as long as the error messages returned by git are actionable
506
+ and understandable for users of the gem.
507
+
508
+ #### Parameter values
509
+
510
+ This section defines how git command-line options and positional arguments map to
511
+ Ruby method parameters. Contributors must follow these conventions:
512
+
513
+ ##### Options
514
+
515
+ Git command-line options are passed as keyword arguments in the Ruby API. Methods
516
+ accept these via an options splat parameter (e.g., `def replace(object, replacement,
517
+ **options)`). Each option is mapped to a keyword argument as described below.
518
+
519
+ - **Boolean flags**: Git options like `--global` or `--bare` are mapped to `global:
520
+ true` or `bare: true`. Omit the key or use `false` to leave the flag unset.
521
+ - `git config --global` → `global: true`
522
+
523
+ - **Negated boolean flags**: Options like `--no-reflogs` are mapped to `no_reflogs:
524
+ true`.
525
+ - `git branch --no-reflogs` → `no_reflogs: true`
526
+
527
+ - **Value options**: Options that take a value, such as `--file <path>` or `--author
528
+ <name>`, are mapped as `file: '/path'`, `author: 'Name'`.
529
+ - `git config --file /tmp/config` → `file: '/tmp/config'`
530
+
531
+ - **Options with optional values**: If a git option can be used as a flag or with a
532
+ value (e.g., `--color` or `--color=always`), use `color: true` for the flag form,
533
+ or `color: 'always'` for the value form.
534
+ - `git log --color` → `color: true`
535
+ - `git log --color=always` → `color: 'always'`
536
+
537
+ - **List/array options**: Options that can be repeated or take multiple values (e.g.,
538
+ `--exclude <pattern>`, `--pathspec-from-file <file>`) are mapped to arrays:
539
+ `exclude: ['foo', 'bar']`.
540
+ - `git ls-files --exclude=foo --exclude=bar` → `exclude: ['foo', 'bar']`
541
+
542
+ - **Key-value pair options**: Options like `-c key=value` are mapped as `c: { 'key'
543
+ => 'value' }` or as an array of pairs if multiple are allowed.
544
+ - `git -c user.name=Scott` → `c: { 'user.name' => 'Scott' }`
545
+
546
+ ##### Positional arguments
547
+
548
+ Arguments that are not options (e.g., file names, branch names) are passed as method
549
+ arguments, not as keyword arguments.
550
+
551
+ - **Only single-valued positional arguments**: If a command has one or more
552
+ single-valued positional arguments (e.g., `<arg1>` or `<arg1> <arg2>`), pass each
553
+ as a separate method argument, in the order they appear in the official git
554
+ documentation and CLI usage. Optional arguments (indicated by `[<arg>]`) should
555
+ default to `nil`.
556
+ - `git cmd <object>` → `def cmd(object)` (fictitious command)
557
+ - `git replace <object> <replacement>` → `def replace(object, replacement)`
558
+ - `git clone <repository> [<directory>]` → `def clone(repository, directory = nil)`
559
+
560
+ - **Single multi-valued positional argument**: If a command has a single multi-valued
561
+ positional argument (e.g., `<pathspec>...` or `[<pathspec>...]`), use a splat
562
+ parameter to accept zero or more values (optional) or one or more values
563
+ (required).
564
+ - `git add [<pathspec>...]` → `def add(*paths)`
565
+
566
+ - **Mixed single-valued and multi-valued positional arguments, `--` separated
567
+ (independently reachable groups)**: When a git command separates two optional
568
+ groups with `--` (e.g., `[<tree-ish>] [-- <pathspec>...]`), callers may want
569
+ to supply the post-`--` group *without* supplying the first group. Use the
570
+ single-valued argument as a regular optional parameter and the multi-valued
571
+ group as a keyword argument with an empty array default. The keyword argument
572
+ should accept a single value or an array; wrap a single value in an array
573
+ internally.
574
+ - `git checkout [<branch>] [-- <pathspec>...]` → `def checkout(branch = nil,
575
+ pathspecs: [])`
576
+ - `git diff [<tree-ish>] [-- <pathspec>...]` → `def diff(tree_ish = nil,
577
+ pathspec: [])`
578
+ - Callers can then do `checkout(pathspecs: ['file.rb'])` (no branch) or
579
+ `diff('HEAD~3', pathspec: ['file.rb'])` (both), with no ambiguity.
580
+
581
+ - **Multiple optional single-valued positional arguments, pure nesting
582
+ (second only meaningful with first)**: When the git SYNOPSIS shows nested
583
+ optional brackets and the inner operand is only useful in the presence of the
584
+ outer one, both arguments may be regular optional parameters in left-to-right
585
+ order. A caller would never supply the second without the first.
586
+ - `git diff [<commit1> [<commit2>]]` → `def diff(commit1 = nil, commit2 = nil)`
587
+ - Callers can do `diff` (no args), `diff('HEAD~3')`, or `diff('HEAD~3', 'HEAD')`.
588
+ There is no case where someone would pass `commit2` without `commit1`.
589
+
590
+ ##### Cross-argument constraints
591
+
592
+ Constraints that span arguments — mutually exclusive options, required groups,
593
+ forbidden value combinations — are not validated in Ruby. Command classes pass the
594
+ arguments through and leave the judgment to git. When git rejects a combination,
595
+ the rejection surfaces as a `Git::FailedError` carrying git's own message; a
596
+ combination git accepts, even one it silently ignores, raises nothing. The decision and its rationale are
597
+ recorded in
598
+ [ADR-0003](docs/adr/0003-validation-of-git-semantics-is-delegated-to-git.md).
599
+
600
+ The arguments DSL does provide constraint declarations (`conflicts`, `requires`,
601
+ `requires_one_of`, `requires_exactly_one_of`, `forbid_values`, `allowed_values`),
602
+ which raise `ArgumentError` at bind time. Declare one only when git cannot report
603
+ the error itself, under the two exception criteria defined in
604
+ [Validation Boundaries](.github/skills/project-context/SKILL.md#validation-boundaries):
605
+
606
+ - **The argv-invisible exception**: the argument never appears in git's argv
607
+ (`skip_cli: true` operands, `execution_option` entries), so git has no token to
608
+ object to. The two current uses are `Git::Commands::CatFile::Batch` (`conflicts`
609
+ and `requires_one_of` on its stdin-fed `:object` operand) and
610
+ `Git::Commands::Archive` (`conflicts :output, :out`, where `:out` is a Ruby IO
611
+ object).
612
+ - **The silent-wrong-result exception**: git accepts the combination but silently
613
+ discards data or produces a wrong answer. A declaration under this exception
614
+ needs a code comment explaining why, the git version(s) where the behavior was
615
+ verified, and a test.
616
+
617
+ These conventions ensure the API is predictable and closely aligned with the git CLI.
618
+ If a new option type is encountered, extend this section to document the mapping.
619
+
620
+ #### Output processing
621
+
622
+ The `git` gem translates the output of many Git commands into Ruby objects that are
181
623
  easier to work with programmatically.
182
624
 
183
- These Ruby objects often include methods that allow for further Git operations where
184
- useful, providing additional functionality while staying true to the underlying Git
185
- behavior.
625
+ These Ruby objects often include methods for further Git operations where useful,
626
+ while staying close to the underlying Git behavior.
627
+
628
+ When a single git command can produce distinctly different output types based on its
629
+ options, implement separate methods for each output type. Follow the same naming
630
+ convention used for commands with multiple purposes: use the git command name as a
631
+ prefix, followed by a suffix that describes the specific output type or
632
+ functionality.
633
+
634
+ For example, `git diff` can produce full diffs, statistical summaries, or path status
635
+ information depending on the options used. These are implemented as separate methods:
636
+
637
+ ```ruby
638
+ repo.diff_full('HEAD~1', 'HEAD') # Full diff output (git diff -p)
639
+ repo.diff_stats('HEAD~1', 'HEAD') # Statistical summary (git diff --numstat)
640
+ repo.diff_path_status('HEAD~1', 'HEAD') # File paths and status (git diff --name-status)
641
+ ```
642
+
643
+ This gives each method a clear, predictable return type and parsing logic targeted
644
+ to its output format.
645
+
646
+ ### Implementation
647
+
648
+ The gem uses the three-layer architecture described in
649
+ [Layered architecture](#layered-architecture). When wrapping a git command, keep the
650
+ layer responsibilities separate:
651
+
652
+ 1. **Design the public API** using the guidelines in this section (placement, naming,
653
+ parameters, output)
654
+
655
+ 2. **Create a command class** in `lib/git/commands/` that:
656
+ - Accepts a `Git::ExecutionContext` at initialization
657
+ - Defines arguments using the [Arguments DSL](lib/git/commands/arguments.rb)
658
+ - Returns a raw `Git::CommandLine::Result`
659
+
660
+ 3. **Add the facade method** to `Git::Repository` (or the `Git` module) that applies
661
+ facade policy, calls the command class, and parses the raw result when returning
662
+ structured Ruby objects.
663
+
664
+ Steps 2 and 3 correspond to the Command and Facade layers, respectively. The
665
+ Execution layer (`Git::ExecutionContext::*`) already exists. A command class only
666
+ consumes it via `@execution_context`; it is not authored per command.
667
+
668
+ Example structure for `git add`:
669
+
670
+ ```ruby
671
+ # lib/git/commands/add.rb (internal)
672
+ require 'git/commands/base'
673
+
674
+ module Git
675
+ module Commands
676
+ class Add < Git::Commands::Base
677
+ arguments do
678
+ literal 'add'
679
+ flag_option %i[verbose v]
680
+ flag_option %i[force f]
681
+ # ...additional flag and value options elided for brevity...
682
+ end_of_options
683
+ operand :pathspec, repeatable: true
684
+ end
685
+
686
+ # @overload call(*pathspec, **options)
687
+ #
688
+ # Execute the `git add` command
689
+ #
690
+ # @param pathspec [Array<String>] files to be added to the repository
691
+ # (relative to the worktree root)
692
+ #
693
+ # @param options [Hash] command options
694
+ #
695
+ # @option options [Boolean, nil] :verbose (nil) be verbose
696
+ #
697
+ # Alias: :v
698
+ #
699
+ # @option options [Boolean, nil] :force (nil) allow adding otherwise ignored
700
+ # files
701
+ #
702
+ # Alias: :f
703
+ #
704
+ # @return [Git::CommandLine::Result] the result of calling `git add`
705
+ #
706
+ # @raise [ArgumentError] if unsupported options are provided
707
+ #
708
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
709
+ #
710
+ # @api public
711
+ #
712
+ def call(*, **)
713
+ super
714
+ end
715
+ end
716
+ end
717
+ end
718
+ ```
719
+
720
+ Here is the corresponding facade method that calls it:
721
+
722
+ ```ruby
723
+ # lib/git/repository/staging.rb (facade, a topic module included into Git::Repository)
724
+ module Git
725
+ class Repository
726
+ module Staging
727
+ ADD_ALLOWED_OPTS = %i[all force].freeze
728
+ private_constant :ADD_ALLOWED_OPTS
729
+
730
+ def add(paths = '.', **)
731
+ SharedPrivate.assert_valid_opts!(ADD_ALLOWED_OPTS, **)
732
+ Git::Commands::Add.new(@execution_context).call(*Array(paths), **).stdout
733
+ end
734
+ end
735
+ end
736
+ end
737
+ ```
738
+
739
+ **How `Git::Commands::Base` works**: `Base` provides a default `#initialize` (accepts
740
+ an `execution_context`) and `#call(*, **)` (binds arguments via the DSL, dispatches to
741
+ `@execution_context.command_capturing` or `@execution_context.command_streaming`
742
+ depending on whether an `out:` execution option is present, and validates the exit
743
+ status). Simple commands need only declare `arguments do … end` and inherit
744
+ `Base#call(*, **)` unchanged. To attach command-specific YARD documentation to the
745
+ inherited `call`, use either a `# @!method call(*, **)` directive (when there is no
746
+ `def call` in the class) or place the YARD tags directly above an explicit
747
+ `def call(*, **); super; end`. Both patterns produce identical runtime behavior.
748
+ Only add real logic to `def call` when the command needs custom behavior beyond what
749
+ `Base` provides.
750
+
751
+ Override `call` explicitly in three situations:
752
+
753
+ 1. **Input validation**: guard `ArgumentError` for invalid option combinations that
754
+ the DSL cannot express (e.g., empty operands without a compensating flag).
755
+ 2. **Stdin via IO pipe**: commands using the `--batch` / `--batch-check` protocol
756
+ must feed object names to the subprocess's stdin. Use the inherited
757
+ `Base#with_stdin(content)`, which opens an `IO.pipe`, writes the string content,
758
+ and yields the read end as `in:`. Do not open a pipe manually. `StringIO` is
759
+ not accepted by `Process.spawn` because it has no file descriptor.
760
+ 3. **Non-trivial option routing**: when multiple call shapes require different
761
+ argument sets built separately before dispatching.
762
+
763
+ When overriding, work with `args_definition.bind(...)` directly and delegate
764
+ exit-status handling to the inherited `validate_exit_status!`. Extract bulk logic
765
+ into private helpers to satisfy RuboCop `Metrics` thresholds:
766
+
767
+ ```ruby
768
+ def call(*objects, **options)
769
+ raise ArgumentError, '...' if objects.empty? && !options[:batch_all_objects]
770
+
771
+ bound = args_definition.bind(*objects, **options)
772
+ with_stdin(objects.map { |o| "#{o}\n" }.join) { |reader| run_batch(bound, reader) }
773
+ end
774
+
775
+ private
776
+
777
+ def run_batch(bound, reader)
778
+ result = @execution_context.command_capturing(*bound, in: reader, **bound.execution_options, raise_on_failure: false)
779
+ validate_exit_status!(result)
780
+ result
781
+ end
782
+ ```
783
+
784
+ Option validation happens at two layers: the `Git::Repository` facade method calls
785
+ `SharedPrivate.assert_valid_opts!` against its own documented public option list first,
786
+ then the [`Arguments` DSL](lib/git/commands/arguments.rb) raises `ArgumentError` for
787
+ any keyword the command class does not recognize during argument binding. The facade
788
+ also handles translation from single values or arrays to the splat format.
789
+
790
+ > **YARD documentation note:** Because `call` uses anonymous argument forwarding
791
+ > (`*, **`), YARD cannot infer its signature. Document it with an `@overload` that names
792
+ > the operands and an `**options` hash (e.g., `@overload call(*pathspec, **options)`),
793
+ > add a `@param options [Hash]` tag, and document each supported keyword with its own
794
+ > `@option` tag. When the class defines no `def call`, place these tags under a
795
+ > `# @!method call(*, **)` directive (as shown above); when it defines an explicit
796
+ > `def call` override, place them directly above that method instead.
797
+ >
798
+ > **Testing requirement:** When defining arguments with the DSL, you must write RSpec
799
+ > tests that verify each argument handles valid values correctly (booleans, strings,
800
+ > arrays) and handles invalid values appropriately. Use a separate `context` block for
801
+ > testing each option to ensure clarity and isolation. See
802
+ > `spec/unit/git/commands/add_spec.rb` for examples of comprehensive argument testing.
803
+
804
+ For factory methods and module-level commands, the pattern is the same but
805
+ `Git::ExecutionContext::Global` is used instead of the repository's
806
+ `@execution_context`:
807
+
808
+ ```ruby
809
+ # Factory method (Git.clone): creates a global context, runs the command, returns a repository
810
+ module Git
811
+ def self.clone(repository_url, directory = nil, options = {})
812
+ context = Git::ExecutionContext::Global.new
813
+ Git::Commands::Clone.new(context).call(repository_url, directory, **options)
814
+ # ... then build and return a Git::Repository for the cloned working tree
815
+ end
816
+ end
817
+ ```
818
+
819
+ > **Note:** `Git::Repository` facade methods pass `@execution_context` (a
820
+ > `Git::ExecutionContext::Repository`) to each command class they invoke.
821
+ > Module-level methods such as `Git.clone` construct a
822
+ > `Git::ExecutionContext::Global` instead.
823
+
824
+ ### Example implementations
825
+
826
+ The following command classes demonstrate implementation patterns.
827
+ See `lib/git/commands/` and `spec/unit/git/commands/` for the full implementations:
828
+
829
+ - **Simple command**: `Git::Commands::Add`, straightforward argument building with
830
+ the [Arguments DSL](lib/git/commands/arguments.rb)
831
+ - **Command with parser-backed facade result**: `Git::Commands::Fsck` with
832
+ `Git::Parsers::Fsck`, which returns raw command output that the facade parses into
833
+ structured Ruby objects
834
+ - **Factory command**: `Git::Commands::Clone`, used by `Git.clone`; returns a
835
+ `Git::CommandLine::Result` like all command classes (the factory method then builds
836
+ and returns a `Git::Repository` from the cloned working tree)
837
+ - **Multiple output modes**: `Git::Commands::Diff`, which declares output-mode options that
838
+ facade methods choose from when building different Ruby-facing results
839
+ - **Multi-context command family**: `Git::Commands::ConfigOptionSyntax::*`, command
840
+ classes shared by module-level and repository-scoped config methods
186
841
 
187
842
  ## Coding standards
188
843
 
189
- To ensure high-quality contributions, all pull requests must meet the following
190
- requirements:
844
+ All pull requests must meet the following requirements:
191
845
 
192
846
  ### Commit message guidelines
193
847
 
194
- To enhance our development workflow, enable automated changelog generation, and pave
195
- the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional
196
- Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit
197
- messages.
198
-
199
- This structured approach to commit messages allows us to:
848
+ The `ruby-git` project has adopted the [Conventional Commits
849
+ standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages.
200
850
 
201
- - **Automate versioning and releases:** Tools can now automatically determine the
202
- semantic version bump (patch, minor, major) based on the types of commits merged.
203
- - **Generate accurate changelogs:** We can automatically create and update a
204
- `CHANGELOG.md` file, providing a clear history of changes for users and
205
- contributors.
206
- - **Improve commit history readability:** A standardized format makes it easier for
207
- everyone to understand the nature of changes at a glance.
851
+ Structured commit messages let tools determine the semantic version bump (patch,
852
+ minor, major) from the commits merged and generate an accurate `CHANGELOG.md`
853
+ automatically. A standardized format also makes the history easier to read at a
854
+ glance.
208
855
 
209
856
  #### What does this mean for contributors?
210
857
 
211
- Going forward, all commits to this repository **MUST** adhere to the [Conventional
212
- Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). Commits not
213
- adhering to this standard will cause the CI build to fail. PRs will not be merged if
214
- they include non-conventional commits.
858
+ All commits to this repository must follow the [Conventional Commits
859
+ standard](https://www.conventionalcommits.org/en/v1.0.0/). Commits that do not
860
+ follow it will fail the CI build, and PRs that include them will not be merged.
215
861
 
216
- A git pre-commit hook may be installed to validate your conventional commit messages
217
- before pushing them to GitHub by running `bin/setup` in the project root.
862
+ A git `commit-msg` hook (Husky + commitlint) that validates your Conventional
863
+ Commit messages locally is installed automatically as part of the project
864
+ bootstrap. See [Local development setup](#local-development-setup). The hook
865
+ depends on Node.js and npm; if those are not installed, `bin/setup` will warn
866
+ and skip the hook, and commit-message validation will only run in CI.
218
867
 
219
868
  #### What to know about Conventional Commits
220
869
 
221
- The simplist conventional commit is in the form `type: description` where `type`
870
+ The simplest conventional commit is in the form `type: description` where `type`
222
871
  indicates the type of change and `description` is your usual commit message (with
223
872
  some limitations).
224
873
 
@@ -229,21 +878,20 @@ some limitations).
229
878
 
230
879
  Examples of valid commits:
231
880
 
232
- - `feat: add the --merges option to Git::Lib.log`
233
- - `fix: exception thrown by Git::Lib.log when repo has no commits`
881
+ - `feat: add the --merges option to Git::Repository#log`
882
+ - `fix: exception thrown by Git::Repository#log when repo has no commits`
234
883
  - `docs: add conventional commit announcement to README.md`
235
884
 
236
- Commits that include breaking changes must include an exclaimation mark before the
885
+ Commits that include breaking changes must include an exclamation mark before the
237
886
  colon:
238
887
 
239
- - `feat!: removed Git::Base.commit_force`
888
+ - `feat!: removed Git::Repository#commit_force`
240
889
 
241
- The commit messages will drive how the version is incremented for each release:
890
+ The commit messages drive how the version is incremented for each release:
242
891
 
243
- - a release containing a **breaking change** will do a **major** version increment
244
- - a release containing a **new feature** will do a **minor** increment
245
- - a release containing **neither a breaking change nor a new feature** will do a
246
- **patch** version increment
892
+ - a release containing a breaking change gets a major version increment
893
+ - a release containing a new feature gets a minor increment
894
+ - a release containing neither gets a patch increment
247
895
 
248
896
  The full conventional commit format is:
249
897
 
@@ -260,67 +908,297 @@ The full conventional commit format is:
260
908
  - `optional footers` only uses `BREAKING CHANGE: <description>` where description
261
909
  should describe the nature of the backward incompatibility.
262
910
 
263
- Use of the `BREAKING CHANGE:` footer flags a backward incompatible change even if it
264
- is not flagged with an exclaimation mark after the `type`. Other footers are allowed
265
- by not acted upon.
911
+ The `BREAKING CHANGE:` footer flags a backward incompatible change even if the
912
+ type is not marked with an exclamation mark. Other footers are allowed
913
+ but not acted upon.
914
+
915
+ A `BREAKING CHANGE:` footer must come out of release-please's stricter parser as you
916
+ wrote it. The `release-please/breaking-change-intact` rule checks this, and its error
917
+ names the line, says why release-please cuts it short, and says how to rewrap. The
918
+ rule comes from the commitlint plugin in
919
+ [commitlint/release-please](commitlint/release-please), installed as a `file:`
920
+ dependency; `npm test` runs its tests. The plugin arrives through `npm install`, and
921
+ the commit-msg hook refuses every commit until a clone that predates it reruns
922
+ `npm install`.
266
923
 
267
924
  See [the Conventional Commits
268
925
  specification](https://www.conventionalcommits.org/en/v1.0.0/) for more details.
269
926
 
270
- ### Unit tests
927
+ #### Issue and PR references
928
+
929
+ Due to a parser limitation in commitlint, using `#<number>` anywhere in the commit
930
+ **body** causes everything from that line onward to be treated as a footer, which
931
+ triggers a `footer-leading-blank` error.
932
+
933
+ To avoid this:
934
+
935
+ - **In the body**, omit the `#` when mentioning an issue or PR: write `issue 1000`,
936
+ not `issue #1000`.
937
+ - **In the footer**, always include `#` for closing references:
938
+ `Closes #1000`, `Fixes #1000`, or `Resolves #1000`.
939
+ - If you only want to mention an issue for context (not close it), omit the `#` in
940
+ the body. No footer line is needed.
941
+
942
+ To validate a commit message before committing:
943
+
944
+ ```bash
945
+ npx commitlint --format @commitlint/format < commit_msg.txt
946
+ ```
947
+
948
+ To see how commitlint has parsed a commit message:
949
+
950
+ ```bash
951
+ cat commit_msg.txt | node -e "
952
+ const parse = require('@commitlint/parse');
953
+ let msg = '';
954
+ process.stdin.on('data', d => msg += d);
955
+ process.stdin.on('end', () =>
956
+ parse.default(msg.trim()).then(r => console.log(JSON.stringify(r, null, 2)))
957
+ );
958
+ " | jq
959
+ ```
960
+
961
+ ### Testing guidelines
962
+
963
+ - All changes must be accompanied by new or modified unit and integration tests as
964
+ appropriate.
965
+ - The entire test suite must pass when `bundle exec rake` is run from the project's
966
+ local working copy.
967
+ - Test runs are covered by SimpleCov by default. Set `COVERAGE=false` (or `0`/`no`/
968
+ `off`) to skip coverage, e.g. `COVERAGE=false bundle exec rake spec`.
969
+ `rake spec:integration` always disables coverage, regardless of `COVERAGE`:
970
+ integration tests aren't meant to be exhaustive, so tracking their coverage would
971
+ misleadingly suggest that low integration coverage is a problem to fix.
972
+ - `rake spec:integration` runs in parallel (via `parallel_tests`) on MRI. Set
973
+ `PARALLEL_TESTS=false` (or `0`/`no`/`off`) to force serial execution, e.g.
974
+ `PARALLEL_TESTS=false bundle exec rake spec:integration`. A run narrowed by `SPEC`
975
+ to a single spec file always runs serially. There is nothing to divide across
976
+ workers, and serial execution gives per-example (documentation) output.
977
+ - Set `SPEC=<glob>` to run specific files instead of a task's whole directory, e.g.
978
+ `SPEC=spec/unit/git/version_spec.rb bundle exec rake spec:unit`.
979
+ - Each task runs only the matches that live under its own directory, so one glob
980
+ spanning `spec/unit/` and `spec/integration/` can drive `bundle exec rake spec` and
981
+ exercise both layers of an area in a single command:
982
+
983
+ ```bash
984
+ # Unit and integration specs for the add command
985
+ SPEC=spec/**/git/commands/add_spec.rb bundle exec rake spec
986
+
987
+ # Unit and integration specs for every command class
988
+ SPEC=spec/**/git/commands bundle exec rake spec
989
+ ```
990
+
991
+ The glob is expanded by Rake, not the shell, so `**` works the same in any shell.
992
+ A task whose directory contains none of the matches is skipped with a message:
993
+ `SPEC=spec/unit/...` on `rake spec` runs the unit specs and skips
994
+ `spec:integration`. A glob matching nothing anywhere fails the task outright.
995
+
996
+ This project uses RSpec (`spec/`) as its sole test framework. Structure, naming,
997
+ setup, stubbing, and coverage rules for specs are defined in the `jcouball-testing`
998
+ plugin's unit, integration, and base standards, with this project's changes in the
999
+ [`rspec-unit-testing-standards`](.github/skills/rspec-unit-testing-standards/SKILL.md),
1000
+ [`rspec-integration-testing-standards`](.github/skills/rspec-integration-testing-standards/SKILL.md),
1001
+ and [`rspec-base-standards`](.github/skills/rspec-base-standards/SKILL.md) skills.
1002
+ Follow the unit standards for specs under `spec/unit/` and the integration standards
1003
+ for specs under `spec/integration/`. The terms those rules use, and the reasoning
1004
+ behind them, are in the
1005
+ [testing guide](https://github.com/jcouball/agent-plugins/blob/main/plugins/testing/docs/testing-guide.md);
1006
+ the [`testing-guide`](.github/skills/testing-guide/SKILL.md) skill says how this
1007
+ project applies it.
1008
+
1009
+ #### Test coverage policy
1010
+
1011
+ **Every pull request to `main` or `5.x` must keep `bundle exec rake spec:unit` at
1012
+ 100% line coverage and 100% branch coverage of `lib/`.** CI fails the build when it
1013
+ drops below either threshold.
1014
+
1015
+ This is enforceable without being onerous because unit coverage in this project is
1016
+ deterministic: `lib/` has no Ruby-version, Ruby-engine, or platform conditionals, and
1017
+ the handful of unit specs that are conditionally skipped are redundant for coverage:
1018
+ every `lib/` line and branch they reach is also reached by a spec that always runs.
1019
+ Every supported MRI runtime therefore measures exactly the same lines and branches, so
1020
+ a coverage failure is always something the pull request introduced.
1021
+
1022
+ A new conditional skip in `spec/unit/` must preserve that property. Verify it on a
1023
+ host where the guard actually skips: run the full unit suite there and confirm it
1024
+ still reports 100% line and branch coverage. A conditionally skipped unit spec that
1025
+ is the only thing covering a line would turn this gate into a platform-dependent
1026
+ failure, which is exactly what the policy exists to prevent.
1027
+
1028
+ Write the guard the same way the rest of the suite does: a reusable predicate in
1029
+ `spec/spec_helper.rb` (`unless_git`, `unless_command`, `unless_pcre`,
1030
+ `unless_ci_build`) used as `skip:` metadata, or, for a one-off capability that the
1031
+ `before` block is already exercising, a `rescue` in that block that calls `skip`.
1032
+
1033
+ What the policy does and does not cover:
1034
+
1035
+ - **Scope is the unit suite on MRI.** Integration specs are deliberately not
1036
+ exhaustive and are not measured (`rake spec:integration` always disables coverage).
1037
+ JRuby and TruffleRuby do not produce reliable coverage data and are not measured.
1038
+ - **Enforcement applies to full-suite runs.** A focused run
1039
+ (`SPEC=<glob> bundle exec rake spec:unit`, or `bundle exec rspec <file>`) still
1040
+ reports coverage but will not fail on it, so the usual edit-test loop is unaffected.
1041
+ Set `FAIL_ON_LOW_COVERAGE=true` to force enforcement on for a focused run.
1042
+ - **A focused run lists gaps only in the code it is about.** The reported percentage is
1043
+ always for the whole of `lib/`, but the list of uncovered lines and branches is scoped
1044
+ to the files the run tests: the classes it describes, plus the `lib/` file each spec
1045
+ file mirrors. So a focused run answers "is what I just changed fully covered?" without
1046
+ waiting for CI:
1047
+
1048
+ ```text
1049
+ Reporting uncovered lines and branches for 1 of 225 files.
1050
+
1051
+ No uncovered lines and branches in this file.
1052
+ ```
1053
+
1054
+ Ignore the percentage on a focused run; it is low because `spec_helper` loads all of
1055
+ `lib/`, not because anything is wrong. Set `LIST_UNCOVERED_FILES=all` to list gaps for
1056
+ every file instead.
1057
+ - **The thresholds do not move.** Do not lower `minimum_coverage` and do not add a
1058
+ SimpleCov filter to exclude a file. The only sanctioned escape hatch is a
1059
+ `# simplecov:disable` directive.
1060
+ - **Every file under `lib/` is measured.** SimpleCov only tracks files loaded after it
1061
+ starts, so a file loaded earlier is silently absent from the report rather than
1062
+ counted as uncovered. This is why `git.gemspec` reads the version string out of
1063
+ `lib/git/version.rb` instead of `require`ing it: the `Gemfile` uses `gemspec`, so
1064
+ requiring it there would load it on every `bundle exec`, before SimpleCov starts.
1065
+ Keep new code out of the load path that runs ahead of `spec_helper`.
1066
+
1067
+ When a branch is hard to cover, apply these in order:
1068
+
1069
+ 1. **Reach it through the public interface.** If a branch is reachable, test it.
1070
+ 2. **Delete it.** A branch that cannot be reached through the public interface is
1071
+ usually dead code, and removing it is preferable to excluding it. See commit
1072
+ `74e919a4` ("fix: remove unreachable nil check in `Git::Parsers::Grep.parse`") for
1073
+ the pattern.
1074
+ 3. **Exclude it with `# simplecov:disable`.** Reserved for defensive guards that could
1075
+ only be reached by breaking an OS-level invariant. Cover the smallest possible span,
1076
+ state why the code is unreachable, and expect a reviewer to question it. `lib/`
1077
+ currently contains no coverage directives.
1078
+
1079
+ Use the inline form wherever the exclusion is a single line. It applies only to the
1080
+ line it sits on and needs no matching `enable`, which makes it impossible to leave a
1081
+ region accidentally open:
1082
+
1083
+ ```ruby
1084
+ raise 'unreachable' # simplecov:disable defensive guard; only reachable on OOM
1085
+ ```
1086
+
1087
+ The block form covers a span and stays in effect until the matching
1088
+ `# simplecov:enable` (or end of file, if you forget it):
1089
+
1090
+ ```ruby
1091
+ # simplecov:disable branch platform-specific fallback; not reachable on MRI
1092
+ ...
1093
+ # simplecov:enable branch
1094
+ ```
1095
+
1096
+ Name the narrowest criterion that solves the problem and spell it exactly:
1097
+ `line`, `branch`, `method`, or a comma-separated combination. A word SimpleCov
1098
+ does not recognize is treated as free-form reason text, which silently widens the
1099
+ directive to all three criteria instead of failing. Write the reason after the
1100
+ criteria, so the required justification lives in the directive itself.
1101
+
1102
+ **Coverage is a floor on evidence, not a proof of correctness.** A test written only
1103
+ to execute a line, without asserting a meaningful outcome, violates the rule on
1104
+ asserting observable behavior in the
1105
+ [`rspec-base-standards`](.github/skills/rspec-base-standards/SKILL.md) skill and will
1106
+ be rejected in review even though it turns the report green. The threshold exists to
1107
+ surface untested behavior, not to be satisfied.
1108
+
1109
+ To see exactly what is uncovered:
1110
+
1111
+ ```bash
1112
+ # Names every uncovered line and branch (printed automatically when a full run fails)
1113
+ $ LIST_UNCOVERED_DETAIL=true bundle exec rake spec:unit
1114
+
1115
+ # Browsable HTML report, also uploaded as a CI artifact when a build fails
1116
+ $ open coverage/index.html
1117
+ ```
1118
+
1119
+ This policy applies to `main` and `5.x`. The `4.x` maintenance branch predates it and
1120
+ is not held to these thresholds.
271
1121
 
272
- - All changes must be accompanied by new or modified unit tests.
273
- - The entire test suite must pass when `bundle exec rake default` is run from the
274
- project's local working copy.
1122
+ #### Unit tests vs integration tests
275
1123
 
276
- While working on specific features, you can run individual test files or a group of
277
- tests using `bin/test`:
1124
+ This project uses two types of RSpec tests, organized by directory:
1125
+
1126
+ - **Unit tests** (`spec/unit/`): test individual classes and methods with mocked
1127
+ execution context. These verify that the gem builds correct git command arguments
1128
+ and properly handles git output. Unit tests should mock `@execution_context` to
1129
+ avoid calling real git commands.
1130
+
1131
+ - **Integration tests** (`spec/integration/`): test the gem's behavior against real
1132
+ git repositories. These verify that mocked assumptions in unit tests match actual
1133
+ git behavior. Integration tests create temporary repositories using `Dir.mktmpdir`
1134
+ and run real git commands through the gem's public API.
1135
+
1136
+ Integration tests check what the unit tests stub out: that the arguments the gem
1137
+ builds work with real git, and that git writes the output its parsers expect. They
1138
+ test the gem's interaction with git, not git itself. The rules for writing them,
1139
+ including how to build and pin temporary repositories, how to start git, and how to
1140
+ assert on results and errors, are in the
1141
+ [RSpec integration testing standards](.github/skills/rspec-integration-testing-standards/SKILL.md)
1142
+ skill, which applies ruby-git's changes on top of the `jcouball-testing` plugin's
1143
+ rules.
1144
+
1145
+ While working on specific features, you can run tests using:
278
1146
 
279
1147
  ```bash
280
- # run a single file (from tests/units):
281
- $ bin/test test_object
1148
+ # Run all RSpec tests (unit + integration):
1149
+ $ bundle exec rake spec
282
1150
 
283
- # run multiple files:
284
- $ bin/test test_object test_archive
1151
+ # Run only RSpec unit tests:
1152
+ $ bundle exec rake spec:unit
285
1153
 
286
- # run all unit tests:
287
- $ bin/test
1154
+ # Run only RSpec integration tests:
1155
+ $ bundle exec rake spec:integration
288
1156
 
289
- # run unit tests with a different version of the git command line:
290
- $ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
1157
+ # Run a specific RSpec file:
1158
+ $ bundle exec rspec spec/unit/git/commands/add_spec.rb
1159
+
1160
+ # Run tests with a different version of the git command line:
1161
+ $ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bundle exec rake spec
291
1162
  ```
292
1163
 
293
- ### Continuous integration
1164
+ ### What ships in the gem
294
1165
 
295
- All tests must pass in the project's [GitHub Continuous Integration
296
- build](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) before the
297
- pull request will be merged.
1166
+ `spec.files` in [`git.gemspec`](git.gemspec) is an **allowlist**: the released gem
1167
+ contains `lib/`, the documents [`.yardopts`](.yardopts) names as extra files, plus
1168
+ `UPGRADING.md` and the gemspec itself. Nothing else in the repository is published.
298
1169
 
299
- The [Continuous Integration
300
- workflow](https://github.com/ruby-git/ruby-git/blob/master/.github/workflows/continuous_integration.yml)
301
- runs both `bundle exec rake default` and `bundle exec rake test:gem` from the
302
- project's [Rakefile](https://github.com/ruby-git/ruby-git/blob/master/Rakefile).
1170
+ It used to be a denylist, which meant every new path was published by default. That
1171
+ shipped `.github/`, `tasks/`, the Husky hooks, and the `.claude/skills` symlink to
1172
+ users. The symlink is what forced the change: extracting a symlink requires a
1173
+ privilege Windows grants only under Developer Mode or an elevated shell, so
1174
+ `gem install git` either failed there or, on RubyGems new enough to fall back to a
1175
+ copy, quietly duplicated the whole skills tree into the installed gem.
303
1176
 
304
- ### Documentation
1177
+ What this means when you add a file:
305
1178
 
306
- New and updated public methods must include [YARD](https://yardoc.org/)
307
- documentation.
1179
+ - **Under `lib/`**: nothing to do; it ships automatically.
1180
+ - **A new top-level document**: add it to `doc_files` in the gemspec if users should
1181
+ get it, and to `.yardopts` if rubydoc.info should render it. The two lists are
1182
+ checked against each other, so a file in `.yardopts` but not the gem fails the
1183
+ suite rather than becoming a broken documentation link.
1184
+ - **Anything else**: it stays out of the gem, which is almost always what you want.
308
1185
 
309
- New and updated public-facing features should be documented in the project's
310
- [README.md](README.md).
1186
+ [`spec/unit/gemspec_spec.rb`](spec/unit/gemspec_spec.rb) enforces all of this: every
1187
+ tracked file under `lib/` is present, no symlink is, and nothing outside `lib/` and
1188
+ the project root is.
311
1189
 
312
1190
  ## Building a specific version of the Git command-line
313
1191
 
314
1192
  To test with a specific version of the Git command-line, you may need to build that
315
- version from source code. The following instructions are adapted from Atlassian’s
1193
+ version from source code. The following instructions are adapted from Atlassian's
316
1194
  [How to install Git](https://www.atlassian.com/git/tutorials/install-git) page for
317
1195
  building Git on macOS.
318
1196
 
319
- ### Install pre-requisites
1197
+ ### Install prerequisites
320
1198
 
321
- Prerequisites only need to be installed if they are not already present.
1199
+ Install prerequisites only if they are not already present.
322
1200
 
323
- From your terminal, install Xcode’s Command Line Tools:
1201
+ From your terminal, install Xcode's Command Line Tools:
324
1202
 
325
1203
  ```shell
326
1204
  xcode-select --install
@@ -343,7 +1221,7 @@ code mirror](https://mirrors.edge.kernel.org/pub/software/scm/git/).
343
1221
  ### Build git
344
1222
 
345
1223
  From your terminal, change to the root directory of the extracted source code and run
346
- the build with following command:
1224
+ the build with the following command:
347
1225
 
348
1226
  ```shell
349
1227
  NO_GETTEXT=1 make CFLAGS="-I/usr/local/opt/openssl/include" LDFLAGS="-L/usr/local/opt/openssl/lib"
@@ -354,7 +1232,7 @@ directory (e.g., `bin-wrappers/git`).
354
1232
 
355
1233
  ### Use the new Git version
356
1234
 
357
- To configure programs that use the Git gem to utilize the newly built version, do the
1235
+ To configure programs that use the Git gem to run the newly built version, do the
358
1236
  following:
359
1237
 
360
1238
  ```ruby
@@ -364,21 +1242,13 @@ require 'git'
364
1242
  Git.configure { |c| c.binary_path = '/Users/james/Downloads/git-2.30.2/bin-wrappers/git' }
365
1243
 
366
1244
  # Validate the version (if desired)
367
- assert_equal([2, 30, 2], Git.binary_version)
1245
+ assert_equal(Git::Version.new(2, 30, 2), Git.git_version)
368
1246
  ```
369
1247
 
370
1248
  Tests can be run using the newly built Git version as follows:
371
1249
 
372
1250
  ```shell
373
- GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
1251
+ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bundle exec rake spec
374
1252
  ```
375
1253
 
376
1254
  Note: `GIT_PATH` refers to the directory containing the `git` executable.
377
-
378
- ## Licensing
379
-
380
- `ruby-git` uses [the MIT license](https://choosealicense.com/licenses/mit/) as
381
- declared in the [LICENSE](LICENSE) file.
382
-
383
- Licensing is critical to open-source projects as it ensures the software remains
384
- available under the terms desired by the author.