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/git.gemspec CHANGED
@@ -1,7 +1,19 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- $LOAD_PATH.unshift File.expand_path('lib', __dir__)
4
- require 'git/version'
3
+ # Read the version out of lib/git/version.rb rather than requiring it.
4
+ #
5
+ # The Gemfile uses `gemspec`, so Bundler evaluates this file on every `bundle exec`.
6
+ # `require`ing lib/git/version.rb here would therefore load it before SimpleCov
7
+ # starts in spec_helper, leaving it invisible to the coverage report -- an
8
+ # unmeasured hole in the 100% coverage gate. See the "Test coverage policy" section
9
+ # of CONTRIBUTING.md.
10
+ #
11
+ # release-please rewrites the `VERSION = '...'` assignment in place (see
12
+ # `version-file` in .release-please-config.json), so matching on it stays correct
13
+ # across releases. If the match ever fails, the raise below stops the build
14
+ # immediately rather than letting a nil version reach the specification.
15
+ version = File.read(File.expand_path('lib/git/version.rb', __dir__))[/^\s*VERSION\s*=\s*['"]([^'"]+)['"]/, 1]
16
+ raise 'Could not determine Git::VERSION from lib/git/version.rb' if version.nil?
5
17
 
6
18
  Gem::Specification.new do |spec|
7
19
  spec.author = 'Scott Chacon and others'
@@ -17,7 +29,7 @@ Gem::Specification.new do |spec|
17
29
  including branching and merging, object inspection and manipulation, history, patch
18
30
  generation and more.
19
31
  DESCRIPTION
20
- spec.version = Git::VERSION
32
+ spec.version = version
21
33
 
22
34
  spec.metadata['homepage_uri'] = spec.homepage
23
35
  spec.metadata['source_code_uri'] = spec.homepage
@@ -26,33 +38,101 @@ Gem::Specification.new do |spec|
26
38
  spec.metadata['rubygems_mfa_required'] = 'true'
27
39
 
28
40
  spec.require_paths = ['lib']
29
- spec.required_ruby_version = '>= 3.2.0'
30
- spec.requirements = ['git 2.28.0 or greater']
41
+ spec.required_ruby_version = '>= 3.3.0'
42
+ spec.requirements = ['git 2.43.0 or greater']
31
43
 
32
- spec.add_dependency 'activesupport', '>= 5.0'
33
- spec.add_dependency 'addressable', '~> 2.8'
44
+ spec.add_dependency 'activesupport', '>= 7.0.9'
45
+ spec.add_dependency 'addressable', '~> 2.9'
46
+ spec.add_dependency 'logger', '~> 1.6'
34
47
  spec.add_dependency 'process_executer', '~> 4.1'
35
48
  spec.add_dependency 'rchardet', '~> 1.9'
36
49
 
50
+ # Not every development dependency is installed on every runtime. Each predicate
51
+ # below names one reason for holding a gem back, which keeps the dependency list
52
+ # itself a flat, readable list. Deriving one predicate from another also keeps
53
+ # coupled gems from drifting apart when a condition changes.
54
+ #
55
+ # These are local variables rather than methods deliberately. The Gemfile uses
56
+ # `gemspec`, so Bundler evaluates this file on every `bundle exec`, and a top-level
57
+ # `def` -- including one written inside this block, since a block is not a definition
58
+ # scope -- would define a private method on Object in every one of those processes.
59
+
60
+ # JRuby (which reports RUBY_PLATFORM as 'java') and TruffleRuby build no C extensions
61
+ # and do not run the docs build.
62
+ mri = !(RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby')
63
+
64
+ # irb stopped being a default gem in Ruby 3.4. JRuby and TruffleRuby ship their own.
65
+ install_irb = mri
66
+
67
+ # Ruby 4.0.0 dropped fiddle from the default gems. On Windows, irb loads
68
+ # reline/io/windows.rb, which requires fiddle/import for the Win32 console API, so
69
+ # bin/console cannot start without it; every other platform takes reline's ANSI IO
70
+ # gate and never loads that file. Derived from install_irb because fiddle exists only
71
+ # to serve irb and, being a C extension, could not install where irb is not.
72
+ install_fiddle = install_irb && Gem.win_platform?
73
+
74
+ # The docs toolchain is supported on MRI only. redcarpet, YARD's Markdown renderer,
75
+ # is also a C extension and so could not install on JRuby regardless.
76
+ install_docs = mri
77
+
78
+ # i18n 1.15+ uses Fiber.[] (Ruby 3.2 Fiber storage), which TruffleRuby < 34.0.0 does
79
+ # not implement, so those runtimes hold at the last release that works there.
80
+ pin_old_i18n = RUBY_ENGINE == 'truffleruby' &&
81
+ Gem::Version.new(RUBY_ENGINE_VERSION) < Gem::Version.new('34.0.0')
82
+
37
83
  spec.add_development_dependency 'create_github_release', '~> 2.1'
84
+ spec.add_development_dependency 'fiddle', '~> 1.1' if install_fiddle
85
+ spec.add_development_dependency 'fuubar', '~> 2.5'
86
+ spec.add_development_dependency 'i18n', '< 1.15' if pin_old_i18n
87
+ spec.add_development_dependency 'irb', '~> 1.16' if install_irb
38
88
  spec.add_development_dependency 'main_branch_shared_rubocop_config', '~> 0.1'
39
- spec.add_development_dependency 'minitar', '~> 1.0'
40
- spec.add_development_dependency 'mocha', '~> 2.7'
41
- spec.add_development_dependency 'rake', '~> 13.2'
42
- spec.add_development_dependency 'rubocop', '~> 1.77'
43
-
44
- spec.add_development_dependency 'test-unit', '~> 3.6'
45
-
46
- unless RUBY_PLATFORM == 'java'
47
- spec.add_development_dependency 'irb', '~> 1.6'
48
- spec.add_development_dependency 'redcarpet', '~> 3.6'
49
- spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
50
- spec.add_development_dependency 'yardstick', '~> 0.9'
51
- end
89
+ spec.add_development_dependency 'parallel_tests', '~> 5.6'
90
+ spec.add_development_dependency 'rake', '~> 13.3'
91
+ spec.add_development_dependency 'redcarpet', '~> 3.6' if install_docs
92
+ spec.add_development_dependency 'rspec', '~> 3.13'
93
+ spec.add_development_dependency 'rubocop', '~> 1.82'
94
+ spec.add_development_dependency 'simplecov', '~> 1.0'
95
+ spec.add_development_dependency 'simplecov-lcov', '~> 0.9'
96
+ spec.add_development_dependency 'simplecov-rspec', '~> 1.1'
97
+ spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28' if install_docs
98
+ spec.add_development_dependency 'yard_example_test', '~> 0.2', '>= 0.2.1' if install_docs
99
+ spec.add_development_dependency 'yard-lint', '~> 1.8' if install_docs
52
100
 
53
101
  # Specify which files should be added to the gem when it is released.
54
- # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
102
+ #
103
+ # This is an allowlist rather than a denylist. A denylist admitted every new
104
+ # development-only path by default, so the gem shipped `.github/`, `tasks/`, the
105
+ # husky hooks, and -- the reason this became an allowlist -- the `.claude/skills`
106
+ # symlink. Extracting a symlink needs a privilege that Windows grants only under
107
+ # Developer Mode or an elevated shell, so installing the gem there either failed
108
+ # outright or, on RubyGems new enough to fall back to a copy, silently duplicated
109
+ # the whole skills tree into the installed gem.
110
+ #
111
+ # spec/unit/gemspec_spec.rb guards both directions: nothing in the list may be a
112
+ # symlink, and every tracked file under lib/ must be present, so the allowlist
113
+ # cannot quietly drop runtime code.
114
+ #
115
+ # doc_files must stay in sync with the extra files named in .yardopts -- those are
116
+ # what rubydoc.info renders for the published documentation, so a file listed there
117
+ # but absent from the gem becomes a broken link.
118
+ doc_files = %w[
119
+ AI_POLICY.md
120
+ CHANGELOG.md
121
+ CODE_OF_CONDUCT.md
122
+ CONTRIBUTING.md
123
+ GOVERNANCE.md
124
+ LICENSE
125
+ MAINTAINERS.md
126
+ README.md
127
+ UPGRADING.md
128
+ ]
129
+
130
+ # .yardopts drives the rubydoc.info build; the gemspec is included by convention.
131
+ build_files = %w[.yardopts git.gemspec]
132
+
55
133
  spec.files = Dir.chdir(File.expand_path(__dir__)) do
56
- `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(tests|spec|features|bin)/}) }
134
+ `git ls-files -z`.split("\x0").select do |f|
135
+ f.start_with?('lib/') || doc_files.include?(f) || build_files.include?(f)
136
+ end
57
137
  end
58
138
  end
@@ -0,0 +1,65 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Git
4
+ # Immutable value object representing an author or committer identity
5
+ #
6
+ # This is a lightweight, immutable data structure holding the identity data
7
+ # git records for commit authors, committers, and taggers.
8
+ #
9
+ # @example Construct from individual values
10
+ # info = Git::AuthorInfo.new(
11
+ # name: 'John Doe',
12
+ # email: 'john.doe@example.com',
13
+ # date: Time.at(1627849923)
14
+ # )
15
+ # info.name #=> 'John Doe'
16
+ #
17
+ # @example Parse from a raw git author string
18
+ # info = Git::AuthorInfo.parse('John Doe <john.doe@example.com> 1627849923 +0200')
19
+ # info.email #=> 'john.doe@example.com'
20
+ # info.date.to_i #=> 1627849923
21
+ #
22
+ # @see Git::Object::Commit#author
23
+ #
24
+ # @see Git::Object::Commit#committer
25
+ #
26
+ # @api public
27
+ #
28
+ # @!attribute [r] name
29
+ # @return [String, nil] the person's name, or `nil` if not available
30
+ #
31
+ # @!attribute [r] email
32
+ # @return [String, nil] the person's email address, or `nil` if not available
33
+ #
34
+ # @!attribute [r] date
35
+ # @return [Time, nil] the timestamp of the change, or `nil` if not available
36
+ #
37
+ AuthorInfo = Data.define(:name, :email, :date) do
38
+ # Parses a raw git identity string into a Git::AuthorInfo
39
+ #
40
+ # The expected format is `"Name <email> timestamp offset"` as emitted by
41
+ # `git cat-file` for the `author`, `committer`, and `tagger` headers. The
42
+ # timestamp is interpreted as seconds since the Unix epoch; the timezone
43
+ # offset is not preserved in the resulting `date`.
44
+ #
45
+ # @example Parse a well-formed identity string
46
+ # Git::AuthorInfo.parse('John Doe <john.doe@example.com> 1627849923 +0200')
47
+ # #=> #<data Git::AuthorInfo name="John Doe", email="john.doe@example.com", ...>
48
+ #
49
+ # @example A string that does not match the expected format
50
+ # Git::AuthorInfo.parse('garbage')
51
+ # #=> #<data Git::AuthorInfo name=nil, email=nil, date=nil>
52
+ #
53
+ # @param author_string [String] the raw identity string to parse
54
+ #
55
+ # @return [Git::AuthorInfo] the parsed identity; all attributes are `nil`
56
+ # when the string does not match the expected format
57
+ #
58
+ def self.parse(author_string)
59
+ match = /(.*?) <(.*?)> (\d+) (.*)/.match(author_string)
60
+ return new(name: nil, email: nil, date: nil) unless match
61
+
62
+ new(name: match[1], email: match[2], date: Time.at(match[3].to_i))
63
+ end
64
+ end
65
+ end
@@ -0,0 +1,34 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Git
4
+ # Represents a branch that failed to be deleted
5
+ #
6
+ # This is an immutable data object returned as part of {Git::BranchDeleteResult}
7
+ # when one or more branches could not be deleted.
8
+ #
9
+ # @example
10
+ # failure = Git::BranchDeleteFailure.new(
11
+ # name: 'nonexistent',
12
+ # error_message: "branch 'nonexistent' not found."
13
+ # )
14
+ # failure.name #=> 'nonexistent'
15
+ # failure.error_message #=> "branch 'nonexistent' not found."
16
+ #
17
+ # @see Git::BranchDeleteResult
18
+ #
19
+ # @see Git::Commands::Branch::Delete
20
+ #
21
+ # @api public
22
+ #
23
+ # @!attribute [r] name
24
+ # The name of the branch that failed to be deleted
25
+ #
26
+ # @return [String]
27
+ #
28
+ # @!attribute [r] error_message
29
+ # The error message from git explaining why the branch could not be deleted
30
+ #
31
+ # @return [String]
32
+ #
33
+ BranchDeleteFailure = Data.define(:name, :error_message)
34
+ end
@@ -0,0 +1,66 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/branch_info'
4
+ require 'git/branch_delete_failure'
5
+
6
+ module Git
7
+ # Represents the result of a branch delete operation
8
+ #
9
+ # This is an immutable data object returned by {Git::Commands::Branch::Delete#call}.
10
+ # It contains information about which branches were successfully deleted and which
11
+ # failed to be deleted, along with the reason for each failure.
12
+ #
13
+ # Git's `git branch -d` command uses "best effort" semantics - it deletes as many
14
+ # branches as possible and reports errors for those that couldn't be deleted. This
15
+ # result object reflects that behavior, allowing callers to inspect both
16
+ # successes and failures.
17
+ #
18
+ # @example Successful deletion of all branches
19
+ # result = branch_delete.call('feature-1', 'feature-2')
20
+ # result.success? #=> true
21
+ # result.deleted.map(&:name) #=> ['feature-1', 'feature-2']
22
+ # result.not_deleted #=> []
23
+ #
24
+ # @example Partial failure (some branches deleted, some not found)
25
+ # result = branch_delete.call('feature-1', 'nonexistent', 'feature-2')
26
+ # result.success? #=> false
27
+ # result.deleted.map(&:name) #=> ['feature-1', 'feature-2']
28
+ # result.not_deleted.first.name #=> 'nonexistent'
29
+ # result.not_deleted.first.error_message #=> "branch 'nonexistent' not found."
30
+ #
31
+ # @see Git::BranchInfo
32
+ #
33
+ # @see Git::BranchDeleteFailure
34
+ #
35
+ # @see Git::Commands::Branch::Delete
36
+ #
37
+ # @api public
38
+ #
39
+ # @!attribute [r] deleted
40
+ # Branches that were successfully deleted
41
+ #
42
+ # @return [Array<Git::BranchInfo>]
43
+ #
44
+ # @!attribute [r] not_deleted
45
+ # Branches that could not be deleted, with the reason for each failure
46
+ #
47
+ # @return [Array<Git::BranchDeleteFailure>]
48
+ #
49
+ BranchDeleteResult = Data.define(:deleted, :not_deleted) do
50
+ # Returns true if all requested branches were successfully deleted
51
+ #
52
+ # @example Check if the delete operation succeeded
53
+ # result = branch_delete.call('feature-branch')
54
+ # if result.success?
55
+ # puts "All branches deleted successfully"
56
+ # else
57
+ # puts "Some branches could not be deleted:"
58
+ # result.not_deleted.each { |f| puts " #{f.name}: #{f.error_message}" }
59
+ # end
60
+ #
61
+ # @return [Boolean] true if no branches failed to delete, false otherwise
62
+ def success?
63
+ not_deleted.empty?
64
+ end
65
+ end
66
+ end
@@ -0,0 +1,237 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Git
4
+ # Regular expression for parsing branch refnames
5
+ #
6
+ # Captures:
7
+ # - remote_name: the remote name (e.g., 'origin') for remote branches, nil for local
8
+ # - branch_name: the branch name without the remote prefix
9
+ #
10
+ # @example Parse branch refnames
11
+ # 'main' => { remote_name: nil, branch_name: 'main' }
12
+ # 'refs/heads/main' => { remote_name: nil, branch_name: 'main' }
13
+ # 'remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
14
+ # 'refs/remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
15
+ # 'feature/foo' => { remote_name: nil, branch_name: 'feature/foo' }
16
+ # 'remotes/origin/feature/bar' => { remote_name: 'origin', branch_name: 'feature/bar' }
17
+ #
18
+ # @note This regex handles both raw full refs (e.g., `refs/heads/main`) as stored in
19
+ # {Git::BranchInfo#refname} and normalized short-form refs (e.g., `main`,
20
+ # `remotes/origin/main`) used elsewhere.
21
+ #
22
+ # @note This regex is a fallback for branch refnames parsed without configured
23
+ # remote context. Remote names containing '/' can only be resolved reliably
24
+ # when the parser is given the configured remote names. See:
25
+ # https://github.com/ruby-git/ruby-git/issues/919
26
+ #
27
+ # @api private
28
+ BRANCH_REFNAME_REGEXP = %r{
29
+ \A # start of string
30
+ (?:refs/heads/)? # optional refs/heads/ prefix (stripped)
31
+ (?:(?:refs/)?remotes/(?<remote_name>[^/]+)/)? # optional refs?/remotes/<remote_name>/
32
+ (?<branch_name>.+) # branch name (everything else)
33
+ \z # end of string
34
+ }x
35
+
36
+ # Sentinel for distinguishing omitted BranchInfo remote_name from explicit nil
37
+ REMOTE_NAME_NOT_GIVEN = Object.new.freeze
38
+ private_constant :REMOTE_NAME_NOT_GIVEN
39
+
40
+ # Value object representing branch metadata from git branch output
41
+ #
42
+ # This is a lightweight, immutable data structure returned by branch listing
43
+ # commands. It contains only the data parsed from git output without any
44
+ # repository context or operations.
45
+ #
46
+ # @example Local branch with upstream tracking
47
+ # info = Git::BranchInfo.new(
48
+ # refname: 'refs/heads/main',
49
+ # target_oid: 'abc123def456789012345678901234567890abcd',
50
+ # current: true,
51
+ # worktree_path: nil,
52
+ # symref: nil,
53
+ # upstream: 'refs/remotes/origin/main'
54
+ # )
55
+ # info.current? #=> true
56
+ # info.remote? #=> false
57
+ # info.short_name #=> 'main'
58
+ # info.upstream #=> 'refs/remotes/origin/main'
59
+ #
60
+ # @example Remote-tracking branch
61
+ # info = Git::BranchInfo.new(
62
+ # refname: 'refs/remotes/origin/main',
63
+ # target_oid: 'abc123def456789012345678901234567890abcd',
64
+ # current: false,
65
+ # worktree_path: nil,
66
+ # symref: nil,
67
+ # upstream: nil
68
+ # )
69
+ # info.remote? #=> true
70
+ # info.remote_name #=> 'origin'
71
+ # info.short_name #=> 'main'
72
+ #
73
+ # @see Git::Repository::Branching#branch_list for the repository method that returns these
74
+ #
75
+ # @see Git::Commands::Branch::List for the command that produces these
76
+ #
77
+ # @api public
78
+ #
79
+ # @!attribute [r] refname
80
+ #
81
+ # The full reference name of the branch
82
+ #
83
+ # Must be the full refname as returned by git (e.g., 'refs/heads/main',
84
+ # 'refs/remotes/origin/main') because the short name alone is not guaranteed to
85
+ # be unique (e.g., 'main' could exist as both a local and remote branch).
86
+ #
87
+ # @return [String] the branch refname (e.g., 'refs/heads/main',
88
+ # 'refs/remotes/origin/main')
89
+ #
90
+ # @!attribute [r] remote_name
91
+ #
92
+ # @return [String, nil] the resolved or fallback-derived remote name, or nil
93
+ # for local branches
94
+ #
95
+ # @!attribute [r] target_oid
96
+ #
97
+ # The commit object ID (SHA) that this branch points to (aka HEAD)
98
+ #
99
+ # @return [String, nil] the full 40-character object ID, or nil if branch is
100
+ # unborn (no commits yet)
101
+ #
102
+ # @!attribute [r] current
103
+ #
104
+ # Whether this branch is currently checked out in the current worktree
105
+ #
106
+ # @return [Boolean] true if this is the current branch
107
+ #
108
+ # @note A branch can be current ({#current?} true) or in another worktree
109
+ # ({#other_worktree?} true), but never both. A branch not checked out
110
+ # anywhere has both false.
111
+ #
112
+ # @!attribute [r] worktree_path
113
+ #
114
+ # The absolute path of the *other* linked worktree this branch is checked
115
+ # out in, or nil.
116
+ #
117
+ # This is nil in two distinct cases:
118
+ # - The branch is the current branch in this worktree (use {#current?} to
119
+ # distinguish that case)
120
+ # - The branch is not checked out in any worktree
121
+ #
122
+ # This path is suppressed for the current branch even though git reports it
123
+ # via `%(worktreepath)`, because the current worktree's path is already
124
+ # known from the repository object and storing it here would make
125
+ # {#other_worktree?} incorrect.
126
+ #
127
+ # @return [String, nil] the absolute path of the linked worktree root
128
+ # directory (e.g., `'/home/user/projects/my-repo-hotfix'`), or nil if
129
+ # the branch is not checked out in a different linked worktree
130
+ #
131
+ # @!attribute [r] symref
132
+ #
133
+ # The target reference if this is a symbolic reference
134
+ #
135
+ # @return [String, nil] the target ref (e.g., 'refs/heads/main'), or nil if not a symref
136
+ #
137
+ # @!attribute [r] upstream
138
+ #
139
+ # The configured upstream/tracking branch refname as reported by git
140
+ #
141
+ # @return [String, nil] the raw upstream refname from `%(upstream)`
142
+ # (e.g., `'refs/remotes/origin/main'`), or nil if no upstream is configured
143
+ #
144
+ # @note Remote-tracking branches (e.g., `'refs/remotes/origin/main'`) have upstream: nil
145
+ #
146
+ # @note This is the raw refname snapshot from when the branch list was read.
147
+ # It does not reflect live git state after the snapshot was taken.
148
+ #
149
+ BranchInfo = Data.define(:refname, :remote_name, :target_oid, :current, :worktree_path, :symref, :upstream) do
150
+ # @param refname [String] the full branch refname
151
+ #
152
+ # @param remote_name [String, nil] resolved remote name, nil for local branches,
153
+ # or omitted to derive from `refname`
154
+ #
155
+ # @param target_oid [String, nil] the commit object ID, or nil for unborn branches
156
+ #
157
+ # @param current [Boolean] whether this branch is currently checked out
158
+ #
159
+ # @param worktree_path [String, nil] path to another linked worktree, or nil
160
+ #
161
+ # @param symref [String, nil] symbolic reference target, or nil
162
+ #
163
+ # @param upstream [String, nil] upstream refname, or nil
164
+ #
165
+ def initialize(refname:, target_oid:, current:, worktree_path:, symref:, upstream:, # rubocop:disable Metrics/ParameterLists
166
+ remote_name: REMOTE_NAME_NOT_GIVEN)
167
+ remote_name = self.class.fallback_remote_name(refname) if remote_name.equal?(REMOTE_NAME_NOT_GIVEN)
168
+ self.class.validate_remote_name!(refname, remote_name)
169
+
170
+ super
171
+ end
172
+
173
+ # @param refname [String] the branch refname to validate
174
+ #
175
+ # @param remote_name [String, nil] the remote name to validate
176
+ #
177
+ # @return [void]
178
+ #
179
+ # @raise [ArgumentError] if the remote name contradicts the refname type
180
+ def self.validate_remote_name!(refname, remote_name)
181
+ if remote_tracking_refname?(refname)
182
+ unless remote_name.is_a?(String) && !remote_name.empty?
183
+ raise ArgumentError, 'remote_name must be a non-empty String for remote-tracking refname'
184
+ end
185
+
186
+ remote_ref_prefix = %r{\A(?:refs/)?remotes/#{Regexp.escape(remote_name)}/}
187
+ raise ArgumentError, 'remote_name must match remote-tracking refname' unless refname.match?(remote_ref_prefix)
188
+ elsif !remote_name.nil?
189
+ raise ArgumentError, 'remote_name must be nil for local branch refname'
190
+ end
191
+ end
192
+
193
+ # @param refname [String] the branch refname to parse
194
+ #
195
+ # @return [String, nil] the regex-derived remote name, or nil for local branches
196
+ def self.fallback_remote_name(refname)
197
+ refname.match(Git::BRANCH_REFNAME_REGEXP)[:remote_name]
198
+ end
199
+
200
+ # @param refname [String] the branch refname to inspect
201
+ #
202
+ # @return [Boolean] true if the refname is a remote-tracking refname
203
+ def self.remote_tracking_refname?(refname)
204
+ refname.match?(%r{\A(?:refs/)?remotes/[^/]+/.+})
205
+ end
206
+
207
+ # @return [Boolean] always false for BranchInfo (see DetachedHeadInfo for detached state)
208
+ def detached? = false
209
+
210
+ # @return [Boolean] true if this is an unborn branch (no commits yet)
211
+ def unborn? = target_oid.nil?
212
+
213
+ # @return [String] the short branch name without any remote or heads prefix
214
+ # (e.g., 'main' or 'feature/foo')
215
+ def short_name
216
+ return refname.delete_prefix('refs/heads/') if remote_name.nil?
217
+
218
+ remote_ref_prefix = %r{\A(?:refs/)?remotes/#{Regexp.escape(remote_name)}/}
219
+ refname.sub(remote_ref_prefix, '')
220
+ end
221
+
222
+ # @return [Boolean] true if this is the currently checked out branch
223
+ def current? = current
224
+
225
+ # @return [Boolean] true if this branch is checked out in another linked worktree
226
+ def other_worktree? = !worktree_path.nil?
227
+
228
+ # @return [Boolean] true if this is a symbolic reference
229
+ def symref? = !symref.nil?
230
+
231
+ # @return [Boolean] true if this is a remote-tracking branch
232
+ def remote? = !remote_name.nil?
233
+
234
+ # @return [String] string representation (the full refname)
235
+ def to_s = refname
236
+ end
237
+ end