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/lib/git.rb CHANGED
@@ -1,5 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # active_support/deprecation alone does not load everything its built-in
4
+ # behaviors use: :log reaches ActiveSupport::IsolatedExecutionState through the
5
+ # logger and :report reaches ActiveSupport.error_reporter. Outside Rails nothing
6
+ # else loads them, so require the ActiveSupport entry point first.
7
+ require 'active_support'
3
8
  require 'active_support/deprecation'
4
9
 
5
10
  # Define Git::Deprecation before requiring the rest of the library to ensure that
@@ -7,12 +12,51 @@ require 'active_support/deprecation'
7
12
  # configured according to the GIT_DEPRECATION_BEHAVIOR environment variable.
8
13
  #
9
14
  module Git
15
+ # The gem name handed to ActiveSupport::Deprecation
16
+ #
17
+ # ActiveSupport's :notify behavior builds its notification name by calling
18
+ # `underscore` on the gem name. That is a String core extension this gem does
19
+ # not load, because requiring it adds twenty-one methods to String in every
20
+ # process that loads the gem. This subclass answers `underscore` itself, so
21
+ # :notify works and String stays untouched. Everywhere else ActiveSupport
22
+ # interpolates the name or passes it through, where it behaves as "Git".
23
+ #
24
+ # @api private
25
+ class DeprecationGemName < String
26
+ # The segment of the notification name after "deprecation."
27
+ #
28
+ # @return [String] "git"
29
+ def underscore = 'git'
30
+ end
31
+ private_constant :DeprecationGemName
32
+
10
33
  # The deprecation instance used to emit deprecation warnings for the Git gem
11
34
  #
35
+ # ActiveSupport defaults the deprecation horizon to a Rails version, and this
36
+ # gem never interpolates it into a warning: every warning is written by hand
37
+ # per ADR-0007. The horizon is informational only, so it carries the ADR's
38
+ # wording instead of a version that would go stale.
39
+ #
12
40
  # @api public
13
- Deprecation = ActiveSupport::Deprecation.new('5.0.0', 'Git')
41
+ Deprecation = ActiveSupport::Deprecation.new('in a future major release', DeprecationGemName.new('Git'))
42
+
43
+ # Configure a deprecation instance from a GIT_DEPRECATION_BEHAVIOR value
44
+ #
45
+ # @param deprecation [ActiveSupport::Deprecation] the deprecation instance to configure
46
+ #
47
+ # @param behavior [String, nil] the desired behavior name (e.g. `'silence'`); when
48
+ # `nil` the deprecation instance is left unchanged
49
+ #
50
+ # @return [void]
51
+ #
52
+ # @raise [ArgumentError] if `behavior` is not one of the keys of
53
+ # `ActiveSupport::Deprecation::DEFAULT_BEHAVIORS`
54
+ #
55
+ # @api private
56
+ #
57
+ def self.configure_deprecation_behavior(deprecation, behavior)
58
+ return if behavior.nil?
14
59
 
15
- if (behavior = ENV.fetch('GIT_DEPRECATION_BEHAVIOR', nil))
16
60
  behavior = behavior.strip
17
61
  allowed_behaviors = ActiveSupport::Deprecation::DEFAULT_BEHAVIORS.keys.map(&:to_s)
18
62
 
@@ -22,242 +66,105 @@ module Git
22
66
  "expected one of: #{allowed_behaviors.join(', ')}"
23
67
  end
24
68
 
25
- Deprecation.behavior = behavior.to_sym
69
+ deprecation.behavior = behavior.to_sym
26
70
  end
71
+ private_class_method :configure_deprecation_behavior
72
+
73
+ configure_deprecation_behavior(Deprecation, ENV.fetch('GIT_DEPRECATION_BEHAVIOR', nil))
27
74
  end
28
75
 
29
- require 'git/author'
30
- require 'git/base'
31
- require 'git/branch'
32
- require 'git/branches'
33
- require 'git/command_line_result'
76
+ require 'git/author_info'
77
+ require 'git/branch_info'
34
78
  require 'git/command_line'
79
+ require 'process_executer'
35
80
  require 'git/config'
81
+ require 'git/config_entry_info'
82
+ require 'git/parsers/config_entry'
83
+ require 'git/configuring'
84
+ require 'git/factories'
36
85
  require 'git/diff'
86
+ require 'git/diff_file_numstat_info'
87
+ require 'git/diff_file_patch_info'
88
+ require 'git/diff_file_raw_info'
89
+ require 'git/diff_info'
90
+ require 'git/parsers/diff'
91
+ require 'git/diff_result'
92
+ require 'git/dirstat_info'
37
93
  require 'git/encoding_utils'
38
94
  require 'git/errors'
39
95
  require 'git/escaped_path'
96
+ require 'git/execution_context'
97
+ require 'git/execution_context/global'
98
+ require 'git/file_ref'
40
99
  require 'git/fsck_object'
41
100
  require 'git/fsck_result'
42
- require 'git/index'
43
- require 'git/lib'
101
+ require 'git/parsers/ls_remote'
102
+ require 'git/parsers/remote'
103
+ require 'git/parsers/status'
104
+ require 'git/version_constraint'
105
+ require 'git/commands'
44
106
  require 'git/log'
45
107
  require 'git/object'
46
- require 'git/path'
47
- require 'git/remote'
108
+ require 'git/remote_info'
48
109
  require 'git/repository'
49
- require 'git/status'
50
- require 'git/stash'
51
- require 'git/stashes'
110
+ require 'git/status_file_info'
111
+ require 'git/status_info'
112
+ require 'git/stash_info'
113
+ require 'git/system_call_guard'
114
+ require 'git/tag_delete_failure'
115
+ require 'git/tag_delete_result'
116
+ require 'git/tag_info'
52
117
  require 'git/url'
53
118
  require 'git/version'
54
- require 'git/working_directory'
55
- require 'git/worktree'
56
- require 'git/worktrees'
119
+ require 'git/worktree_info'
57
120
 
58
121
  # The Git module provides the basic functions to open a git
59
122
  # reference to work with. You can open a working directory,
60
123
  # open a bare repository, initialize a new repo or clone an
61
124
  # existing remote repository.
62
125
  #
63
- # @author Scott Chacon (mailto:schacon@gmail.com)
64
- #
65
- module Git # rubocop:disable Style/OneClassPerFile
66
- # Internal alias for Git::Lib, used by the gem itself after the public constant
67
- # is deprecated. Code outside the gem should not reference this constant.
68
- # @api private
69
- LibImpl = remove_const(:Lib)
70
-
71
- # @api private
72
- def self.const_missing(name)
73
- return super unless name == :Lib
74
-
75
- Git::Deprecation.warn(
76
- 'Git::Lib is deprecated and will be removed in version 5.x. ' \
77
- 'Use the #lib accessor on the object returned by Git.init, Git.open, or Git.clone instead.'
78
- )
79
- const_set(:Lib, LibImpl)
80
- end
81
-
82
- # g.config('user.name', 'Scott Chacon') # sets value
83
- # g.config('user.email', 'email@email.com') # sets value
84
- # g.config('user.name') # returns 'Scott Chacon'
85
- # g.config # returns whole config hash
86
- def config(name = nil, value = nil)
87
- lib = LibImpl.new
88
- if name && value
89
- # set value
90
- lib.config_set(name, value)
91
- elsif name
92
- # return value
93
- lib.config_get(name)
94
- else
95
- # return hash
96
- lib.config_list
97
- end
98
- end
99
-
100
- def self.configure
101
- yield Base.config
102
- end
103
-
104
- def self.config
105
- Base.config
106
- end
107
-
108
- def global_config(name = nil, value = nil)
109
- self.class.global_config(name, value)
110
- end
126
+ module Git
127
+ extend Git::Configuring
128
+ extend Git::Factories
111
129
 
112
- # Open a bare repository
130
+ # Minimum git version required by this gem
113
131
  #
114
- # Opens a bare repository located in the `git_dir` directory.
115
- # Since there is no working copy, you can not checkout or commit
116
- # but you can do most read operations.
132
+ # Commands and features may require newer versions, but this is the absolute
133
+ # minimum supported version for the gem as a whole.
117
134
  #
118
- # @see https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository
119
- # What is a bare repository?
135
+ # @return [Git::Version]
120
136
  #
121
- # @example Open a bare repository and retrieve the first commit SHA
122
- # repository = Git.bare('ruby-git.git')
123
- # puts repository.log[0].sha #=> "64c6fa011d3287bab9158049c85f3e85718854a0"
137
+ # @api public
124
138
  #
125
- # @param [Pathname] git_dir The path to the bare repository directory
126
- # containing an initialized Git repository. If a relative path is given, it
127
- # is converted to an absolute path using
128
- # [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
139
+ MINIMUM_GIT_VERSION = Version.parse('2.43.0')
140
+
141
+ # Configures the gem by yielding {Git::Config.instance} to the block
129
142
  #
130
- # @param [Hash] options The options for this command (see list of valid
131
- # options below)
143
+ # @example Set the global git binary path
144
+ # Git.configure { |c| c.binary_path = '/usr/local/bin/git' }
132
145
  #
133
- # @option options [String, nil] :git_ssh An optional custom SSH command
146
+ # @return [void]
134
147
  #
135
- # - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
136
- # - If nil, disables SSH for this instance.
137
- # - If a non-empty string, uses that value for this instance.
148
+ # @yield [config] yields the singleton config object
138
149
  #
139
- # @option options [Logger] :log A logger to use for Git operations. Git commands
140
- # are logged at the `:info` level. Additional logging is done at the `:debug`
141
- # level.
150
+ # @yieldparam config [Git::Config] the singleton config object
142
151
  #
143
- # @return [Git::Base] an object that can execute git commands in the context
144
- # of the bare repository.
152
+ # @yieldreturn [void]
145
153
  #
146
- def self.bare(git_dir, options = {})
147
- Base.bare(git_dir, options)
154
+ def self.configure
155
+ yield Git::Config.instance
156
+ nil
148
157
  end
149
158
 
150
- # Clone a repository into an empty or newly created directory
151
- #
152
- # @see https://git-scm.com/docs/git-clone git clone
153
- # @see https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a GIT URLs
154
- #
155
- # @param repository_url [URI, Pathname] The (possibly remote) repository url to clone
156
- # from. See [GIT URLS](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a)
157
- # for more information.
158
- #
159
- # @param directory [Pathname, nil] The directory to clone into
160
- #
161
- # If `directory` is a relative directory it is relative to the `path` option if
162
- # given. If `path` is not given, `directory` is relative to the current working
163
- # directory.
164
- #
165
- # If `nil`, `directory` will be set to the basename of the last component of
166
- # the path from the `repository_url`. For example, for the URL:
167
- # `https://github.com/org/repo.git`, `directory` will be set to `repo`.
168
- #
169
- # If the last component of the path is `.git`, the next-to-last component of
170
- # the path is used. For example, for the URL `/Users/me/foo/.git`, `directory`
171
- # will be set to `foo`.
172
- #
173
- # @param [Hash] options The options for this command (see list of valid
174
- # options below)
175
- #
176
- # @option options [Boolean] :bare Make a bare Git repository. See
177
- # [what is a bare repository?](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository).
178
- #
179
- # @option options [String] :branch The name of a branch or tag to checkout
180
- # instead of the default branch.
181
- #
182
- # @option options [Array, String] :config A list of configuration options to
183
- # set on the newly created repository.
184
- #
185
- # @option options [Integer] :depth Create a shallow clone with a history
186
- # truncated to the specified number of commits.
187
- #
188
- # @option options [String] :filter Request that the server send a partial
189
- # clone according to the given filter
190
- #
191
- # @option options [Boolean, nil] :single_branch Control whether the clone
192
- # limits fetch refspecs to a single branch.
193
- # - If nil (default), no flag is passed and the Git default is used.
194
- # - If true, `--single-branch` is passed to limit the refspec to the
195
- # checkout branch.
196
- # - If false, `--no-single-branch` is passed to broaden the refspec (useful
197
- # for shallow clones that should include all branches).
159
+ # Returns the process-wide {Git::Config} singleton
198
160
  #
199
- # @option options [String, nil] :git_ssh An optional custom SSH command
161
+ # @example Read the configured binary path
162
+ # Git.config.binary_path #=> "git"
200
163
  #
201
- # - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
202
- # - If nil, disables SSH for this instance.
203
- # - If a non-empty string, uses that value for this instance.
164
+ # @return [Git::Config] the singleton config object
204
165
  #
205
- # @option options [Logger] :log A logger to use for Git operations. Git
206
- # commands are logged at the `:info` level. Additional logging is done
207
- # at the `:debug` level.
208
- #
209
- # @option options [Boolean] :mirror Set up a mirror of the source repository.
210
- #
211
- # @option options [String] :origin Use the value instead `origin` to track
212
- # the upstream repository.
213
- #
214
- # @option options [Pathname] :path The directory to clone into. May be used
215
- # as an alternative to the `directory` parameter. If specified, the
216
- # `path` option is used instead of the `directory` parameter.
217
- #
218
- # @option options [Boolean] :recursive After the clone is created, initialize
219
- # all submodules within, using their default settings.
220
- #
221
- # @example Clone into the default directory `ruby-git`
222
- # git = Git.clone('https://github.com/ruby-git/ruby-git.git')
223
- #
224
- # @example Clone and then checkout the `development` branch
225
- # git = Git.clone('https://github.com/ruby-git/ruby-git.git', branch: 'development')
226
- #
227
- # @example Clone into a different directory `my-ruby-git`
228
- # git = Git.clone('https://github.com/ruby-git/ruby-git.git', 'my-ruby-git')
229
- # # or:
230
- # git = Git.clone('https://github.com/ruby-git/ruby-git.git', path: 'my-ruby-git')
231
- #
232
- # @example Create a bare repository in the directory `ruby-git.git`
233
- # git = Git.clone('https://github.com/ruby-git/ruby-git.git', bare: true)
234
- #
235
- # @example Clone a repository and set a single config option
236
- # git = Git.clone(
237
- # 'https://github.com/ruby-git/ruby-git.git',
238
- # config: 'submodule.recurse=true'
239
- # )
240
- #
241
- # @example Clone a repository and set multiple config options
242
- # git = Git.clone(
243
- # 'https://github.com/ruby-git/ruby-git.git',
244
- # config: ['user.name=John Doe', 'user.email=john@doe.com']
245
- # )
246
- #
247
- # @example Clone using a specific SSH key
248
- # git = Git.clone(
249
- # 'git@github.com:ruby-git/ruby-git.git',
250
- # 'local-dir',
251
- # git_ssh: 'ssh -i /path/to/private_key'
252
- # )
253
- #
254
- # @return [Git::Base] an object that can execute git commands in the context
255
- # of the cloned local working copy or cloned repository.
256
- #
257
- def self.clone(repository_url, directory = nil, options = {})
258
- clone_to_options = options.slice(:bare, :mirror)
259
- directory ||= Git::URL.clone_to(repository_url, **clone_to_options)
260
- Base.clone(repository_url, directory, options)
166
+ def self.config
167
+ Git::Config.instance
261
168
  end
262
169
 
263
170
  # Returns the name of the default branch of the given repository
@@ -280,15 +187,16 @@ module Git # rubocop:disable Style/OneClassPerFile
280
187
  # @example with the logging option
281
188
  # logger = Logger.new(STDOUT, level: Logger::INFO)
282
189
  # Git.default_branch('.', log: logger) # => 'master'
283
- # I, [2022-04-13T16:01:33.221596 #18415] INFO -- : git '-c' 'core.quotePath=true'
284
- # '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD' 2>&1
190
+ # # Logs the executed git command to STDOUT, for example:
191
+ # # I, [2022-04-13T16:01:33.221596 #18415] INFO -- : git '-c' 'core.quotePath=true'
192
+ # # '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD' 2>&1
285
193
  #
286
194
  # @param repository [URI, Pathname, String] The (possibly remote) repository to get the default branch name for
287
195
  #
288
196
  # See [GIT URLS](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a)
289
197
  # for more information.
290
198
  #
291
- # @param [Hash] options The options for this command (see list of valid
199
+ # @param options [Hash] The options for this command (see list of valid
292
200
  # options below)
293
201
  #
294
202
  # @option options [Logger] :log A logger to use for Git operations. Git
@@ -298,189 +206,268 @@ module Git # rubocop:disable Style/OneClassPerFile
298
206
  # @return [String] the name of the default branch
299
207
  #
300
208
  def self.default_branch(repository, options = {})
301
- Base.repository_default_branch(repository, options)
209
+ context = Git::ExecutionContext::Global.new(logger: options[:log])
210
+ output = Git::Commands::LsRemote.new(context).call(repository, 'HEAD', symref: true).stdout
211
+ Git::Parsers::LsRemote.parse_default_branch(output)
302
212
  end
303
213
 
304
- # Export the current HEAD (or a branch, if <tt>options[:branch]</tt>
305
- # is specified) into the +name+ directory, then remove all traces of git from the
306
- # directory.
214
+ # Clone a repository into `directory` then remove its `.git` directory
307
215
  #
308
- # See +clone+ for options. Does not obey the <tt>:remote</tt> option,
309
- # since the .git info will be deleted anyway; always uses the default
310
- # remote, 'origin.'
216
+ # Exports the current HEAD (or the specific branch given in <tt>options[:branch]</tt>)
217
+ # into the given `directory`. It then removes all traces of git from the directory.
311
218
  #
312
- # <tt>options[:branch]</tt> is the short name of the ref: a branch name such as
313
- # 'main' or a tag name such as 'v1.0.0'. A full ref path such as
314
- # 'refs/tags/v1.0.0' or a commit SHA is not accepted.
315
- #
316
- # Removing +.git+ is not atomic. If it fails, the exported files are complete and
317
- # usable, but the directory keeps whatever part of +.git+ could not be deleted.
219
+ # Removing `.git` is not atomic. If it fails, the exported files are complete and
220
+ # usable, but the directory keeps whatever part of `.git` could not be deleted.
318
221
  # Nothing is cleaned up, because the exported files are the deliverable and the
319
222
  # leftover has to be removed by hand once the cause of the failure is fixed.
320
223
  #
321
- # @raise [SystemCallError] if the +.git+ directory cannot be removed. The exported
322
- # files are left in place, and the directory keeps whatever part of +.git+ could
323
- # not be deleted.
324
- def self.export(repository, name, options = {})
325
- options.delete(:remote)
326
- repo = clone(repository, name, { depth: 1 }.merge(options))
327
- FileUtils.rm_r File.join(repo.dir.to_s, '.git')
224
+ # Takes the same options as {Git.clone} except that `:depth` defaults to 1.
225
+ #
226
+ # @param repository_url [String, URI, Pathname] the repository to export from
227
+ #
228
+ # @param directory [String, Pathname, nil] the directory to export into; defaults to the
229
+ # repository basename
230
+ #
231
+ # @param options [Hash] options forwarded to {Git.clone} (`:depth` defaults to 1)
232
+ #
233
+ # @option options [String] :branch the branch or tag to export instead of HEAD.
234
+ # Give the short name (`main`, `v1.0.0`); a full ref path such as
235
+ # `refs/tags/v1.0.0` or a commit SHA is not accepted. Use `:revision` to
236
+ # export a SHA.
237
+ #
238
+ # @return [void]
239
+ #
240
+ # @raise [Git::Error] if the `.git` directory cannot be removed. The exported
241
+ # files are left in place, and the directory keeps whatever part of `.git`
242
+ # could not be deleted.
243
+ #
244
+ def self.export(repository_url, directory = nil, options = {})
245
+ repo = clone(repository_url, directory, { depth: 1 }.merge(options))
246
+ git_dir = File.join(repo.dir.to_s, '.git')
247
+ Git::SystemCallGuard.call(
248
+ "Failed to remove '#{git_dir}'; the exported files are in place, but part of the " \
249
+ 'repository remains and has to be removed by hand'
250
+ ) { FileUtils.rm_r(git_dir) }
328
251
  end
329
252
 
330
- # Same as g.config, but forces it to be at the global level
331
- #
332
- # g.config('user.name', 'Scott Chacon') # sets value
333
- # g.config('user.email', 'email@email.com') # sets value
334
- # g.config('user.name') # returns 'Scott Chacon'
335
- # g.config # returns whole config hash
336
- def self.global_config(name = nil, value = nil)
337
- lib = LibImpl.new(nil, nil)
338
- if name && value
339
- # set value
340
- lib.global_config_set(name, value)
341
- elsif name
342
- # return value
343
- lib.global_config_get(name)
344
- else
345
- # return hash
346
- lib.global_config_list
347
- end
348
- end
253
+ # Option keys accepted by {.ls_remote}
254
+ #
255
+ # Parser-incompatible options such as `:get_url` and `:symref` are intentionally
256
+ # excluded because {Git::Parsers::LsRemote.parse_output} cannot handle the
257
+ # non-standard output formats those flags produce.
258
+ #
259
+ # @return [Array<Symbol>]
260
+ #
261
+ # @api private
262
+ #
263
+ LS_REMOTE_ALLOWED_OPTS = %i[
264
+ branches b heads h tags t refs upload_pack quiet q exit_code sort server_option o timeout
265
+ ].freeze
266
+ private_constant :LS_REMOTE_ALLOWED_OPTS
349
267
 
350
- # Create an empty Git repository or reinitialize an existing Git repository
268
+ # Displays references available in a remote repository along with the associated commit IDs
351
269
  #
352
- # @param [Pathname] directory If the `:bare` option is NOT given or is not
353
- # `true`, the repository will be created in `"#{directory}/.git"`.
354
- # Otherwise, the repository is created in `"#{directory}"`.
270
+ # @example From a remote repository given its URL
271
+ # references = Git.ls_remote('https://github.com/user/repo.git')
355
272
  #
356
- # All directories along the path to `directory` are created if they do not exist.
273
+ # @example From the default remote of the current repository
274
+ # references = Git.ls_remote
357
275
  #
358
- # A relative path is referenced from the current working directory of the process
359
- # and converted to an absolute path using
360
- # [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
276
+ # @example From a specific remote of the current repository
277
+ # references = Git.ls_remote('origin')
361
278
  #
362
- # @param [Hash] options The options for this command (see list of valid
363
- # options below)
279
+ # @param repository [String] the target repository location or the name of a remote
364
280
  #
365
- # @option options [Boolean] :bare Instead of creating a repository at
366
- # `"#{directory}/.git"`, create a bare repository at `"#{directory}"`.
367
- # See [what is a bare repository?](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository).
281
+ # Defaults to `'.'` (the current directory). Passing `nil` raises
282
+ # `ArgumentError`; pass `'.'` or omit the argument.
368
283
  #
369
- # @option options [String] :initial_branch Use the specified name for the
370
- # initial branch in the newly created repository.
284
+ # @param options [Hash] the options to pass to the git command
371
285
  #
372
- # @option options [Pathname] :repository the path to put the newly initialized
373
- # Git repository. The default for non-bare repository is `"#{directory}/.git"`.
286
+ # @option options [Boolean, nil] :branches (nil) limit output to refs under `refs/heads/`
374
287
  #
375
- # A relative path is referenced from the current working directory of the process
376
- # and converted to an absolute path using
377
- # [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
288
+ # Alias: `:b`
378
289
  #
379
- # @option options [String, nil] :git_ssh An optional custom SSH command
290
+ # @option options [Boolean, nil] :heads (nil) limit output to refs under `refs/heads/`
380
291
  #
381
- # - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
382
- # - If nil, disables SSH for this instance.
383
- # - If a non-empty string, uses that value for this instance.
292
+ # Deprecated: use `:branches` instead. Kept for backward compatibility with
293
+ # older git versions where `--heads` is the only supported flag.
384
294
  #
385
- # @option options [Logger] :log A logger to use for Git operations. Git
386
- # commands are logged at the `:info` level. Additional logging is done
387
- # at the `:debug` level.
295
+ # Alias: `:h`
296
+ #
297
+ # @option options [Boolean, nil] :tags (nil) limit output to refs under `refs/tags/`
298
+ #
299
+ # Alias: `:t`
300
+ #
301
+ # @option options [Boolean, nil] :refs (nil) exclude peeled tags and pseudorefs
302
+ # like `HEAD` from the output
303
+ #
304
+ # @option options [String] :upload_pack (nil) full path to `git-upload-pack` on the
305
+ # remote host
306
+ #
307
+ # Useful when accessing repositories via SSH where the daemon does not use the
308
+ # PATH configured by the user.
309
+ #
310
+ # @option options [Boolean, nil] :quiet (nil) do not print the remote URL to stderr
311
+ #
312
+ # Alias: `:q`
313
+ #
314
+ # @option options [Boolean, nil] :exit_code (nil) exit with status `2` when no
315
+ # matching refs are found in the remote repository
388
316
  #
389
- # @return [Git::Base] an object that can execute git commands in the context
390
- # of the newly initialized repository
317
+ # Without this option, the command exits `0` whenever it successfully
318
+ # communicates with the remote, even if no refs match.
391
319
  #
392
- # @example Initialize a repository in the current directory
393
- # git = Git.init
320
+ # @option options [String] :sort (nil) sort output by the given key
394
321
  #
395
- # @example Initialize a repository in some other directory
396
- # git = Git.init '~/code/ruby-git'
322
+ # Prefix `-` for descending order. Supports `"version:refname"` or `"v:refname"`.
323
+ # See `git for-each-ref` for sort key documentation.
397
324
  #
398
- # @example Initialize a bare repository
399
- # git = Git.init '~/code/ruby-git.git', bare: true
325
+ # @option options [String, Array<String>] :server_option (nil) transmit a string to
326
+ # the server when communicating using protocol version 2
400
327
  #
401
- # @example Initialize a repository in a non-default location (outside of the working copy)
402
- # git = Git.init '~/code/ruby-git', repository: '~/code/ruby-git.git'
328
+ # The string must not contain NUL or LF characters. Repeatable by passing an
329
+ # Array. Alias: `:o`
403
330
  #
404
- # @see https://git-scm.com/docs/git-init git init
331
+ # @option options [Numeric] :timeout (nil) execution timeout in seconds
405
332
  #
406
- def self.init(directory = '.', options = {})
407
- Base.init(directory, options)
333
+ # @option options [Logger] :log (nil) a logger to use for Git operations
334
+ #
335
+ # Git commands are logged at the `:info` level. Additional logging is done at
336
+ # the `:debug` level.
337
+ #
338
+ # @return [Hash{String => Hash}] the available references of the target repo
339
+ #
340
+ # @raise [ArgumentError] if `repository` is `nil` or `options` contains an unknown key
341
+ #
342
+ def self.ls_remote(repository = '.', options = {})
343
+ raise ArgumentError, 'repository must not be nil' if repository.nil?
344
+
345
+ options = options.dup
346
+ log = options.delete(:log)
347
+ unknown = options.keys - LS_REMOTE_ALLOWED_OPTS
348
+ raise ArgumentError, "Unknown options: #{unknown.join(', ')}" unless unknown.empty?
349
+
350
+ context = Git::ExecutionContext::Global.new(logger: log)
351
+ output_lines = Git::Commands::LsRemote.new(context).call(repository, **options).stdout.split("\n")
352
+ Git::Parsers::LsRemote.parse_output(output_lines)
408
353
  end
409
354
 
410
- # returns a Hash containing information about the references
411
- # of the target repository
355
+ # Thread-safe cache for git versions, keyed by binary path.
356
+ @git_version_cache_mutex = Mutex.new
357
+ @git_version_cache = {}
358
+
359
+ # Return the cached git version for the given binary path
360
+ #
361
+ # If it isn't already known, compute it using the given block.
412
362
  #
413
- # options
414
- # :refs
363
+ # @param binary_path [String] the path to the git binary
415
364
  #
416
- # @param [String|NilClass] location the target repository location or nil for '.'
417
- # @return [{String=>Hash}] the available references of the target repo.
418
- def self.ls_remote(location = nil, options = {})
419
- LibImpl.new.ls_remote(location, options)
365
+ # @return [Git::Version] the git version
366
+ #
367
+ # @yield [] compute the git version if it is not cached
368
+ #
369
+ # @yieldreturn [Git::Version] the computed git version
370
+ #
371
+ # @api private
372
+ def self.cached_git_version(binary_path, &block)
373
+ @git_version_cache_mutex.synchronize do
374
+ @git_version_cache[binary_path] ||= block.call
375
+ end
420
376
  end
421
377
 
422
- # Open a an existing Git working directory
378
+ # Clear the cached git version for all binary paths
423
379
  #
424
- # Git.open will most likely be the most common way to create
425
- # a git reference, referring to an existing working directory.
380
+ # @return [void]
426
381
  #
427
- # If not provided in the options, the library will assume
428
- # the repository and index are in the default places (`.git/`, `.git/index`).
382
+ # @api private
383
+ def self.clear_git_version_cache
384
+ @git_version_cache_mutex.synchronize do
385
+ @git_version_cache.clear
386
+ end
387
+ end
388
+
389
+ # Return the version of a git binary as a {Git::Version}
429
390
  #
430
- # @example Open the Git working directory in the current directory
431
- # git = Git.open
391
+ # @example Default binary
392
+ # Git.git_version #=> #<Git::Version 2.42.0>
432
393
  #
433
- # @example Open a Git working directory in some other directory
434
- # git = Git.open('~/Projects/ruby-git')
394
+ # @example Explicit binary path
395
+ # Git.git_version('/opt/homebrew/bin/git') #=> #<Git::Version 2.42.0>
435
396
  #
436
- # @example Use a logger to see what is going on
437
- # logger = Logger.new(STDOUT)
438
- # git = Git.open('~/Projects/ruby-git', log: logger)
397
+ # @param binary_path [String, nil] path to the git binary; defaults to
398
+ # `Git::Config.instance.binary_path`
439
399
  #
440
- # @example Open a working copy whose repository is in a non-standard directory
441
- # git = Git.open('~/Projects/ruby-git', repository: '~/Project/ruby-git.git')
400
+ # @return [Git::Version] the parsed git version
442
401
  #
443
- # @param [Pathname] working_dir the path to the working directory to use
444
- # for git commands.
402
+ # @raise [Git::UnexpectedResultError] if the version output cannot be parsed
445
403
  #
446
- # A relative path is referenced from the current working directory of the process
447
- # and converted to an absolute path using
448
- # [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
404
+ # @raise [Git::FailedError] if the git binary exits with a non-zero status
449
405
  #
450
- # @param [Hash] options The options for this command (see list of valid
451
- # options below)
406
+ # @raise [Git::Error] if the binary is not found or fails to launch
407
+ #
408
+ def self.git_version(binary_path = nil)
409
+ path = binary_path || Git::Config.instance.binary_path
410
+ cached_git_version(path) { run_git_version(path) }
411
+ end
412
+
413
+ # Return the version of the git binary
452
414
  #
453
- # @option options [Pathname] :repository used to specify a non-standard path to
454
- # the repository directory. The default is `"#{working_dir}/.git"`.
415
+ # @param path [String] the path to the git binary
455
416
  #
456
- # @option options [Pathname] :index used to specify a non-standard path to an
457
- # index file. The default is `"#{working_dir}/.git/index"`
417
+ # @return [Git::Version] the parsed git version
458
418
  #
459
- # @option options [String, nil] :git_ssh An optional custom SSH command
419
+ # @raise [Git::UnexpectedResultError] if the version output cannot be parsed
460
420
  #
461
- # - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
462
- # - If nil, disables SSH for this instance.
463
- # - If a non-empty string, uses that value for this instance.
421
+ # @raise [Git::FailedError] if the git binary exits with a non-zero status
464
422
  #
465
- # @option options [Logger] :log A logger to use for Git operations. Git
466
- # commands are logged at the `:info` level. Additional logging is done
467
- # at the `:debug` level.
423
+ # @raise [Git::Error] if the binary is not found or fails to launch
468
424
  #
469
- # @return [Git::Base] an object that can execute git commands in the context
470
- # of the opened working copy
425
+ # @api private
471
426
  #
472
- def self.open(working_dir, options = {})
473
- Base.open(working_dir, options)
427
+ def self.run_git_version(path)
428
+ output = Git::Commands::Version.new(Git::ExecutionContext::Global.new(binary_path: path)).call.stdout
429
+ Git::Version.parse(output)
474
430
  end
431
+ private_class_method :run_git_version
475
432
 
476
- # Return the version of the git binary
433
+ # @api private
434
+ def self.execution_context
435
+ Git::ExecutionContext::Global.new
436
+ end
437
+ private_class_method :execution_context
438
+
439
+ # Scopes that require an active repository and cannot be used at the Git module level
440
+ #
441
+ # @api private
442
+ #
443
+ REPOSITORY_SPECIFIC_SCOPES = %i[local worktree blob].freeze
444
+ private_constant :REPOSITORY_SPECIFIC_SCOPES
445
+
446
+ # Raises +ArgumentError+ when a repository-specific scope is requested.
477
447
  #
478
- # @example
479
- # Git.binary_version # => [2, 46, 0]
448
+ # The +:local+, +:worktree+, and +:blob+ scopes require an active git
449
+ # repository and are therefore not valid at the Git module level.
480
450
  #
481
- # @return [Array<Integer>] the version of the git binary
451
+ # @param options_to_check [Hash{Symbol => Object}] the scope options to check
482
452
  #
483
- def self.binary_version(binary_path = Git::Base.config.binary_path)
484
- Base.binary_version(binary_path)
453
+ # If any of the options listed in +REPOSITORY_SPECIFIC_SCOPES+ are present and
454
+ # truthy, an +ArgumentError+ will be raised.
455
+ #
456
+ # @option options_to_check [Object] :local truthy value requests local scope
457
+ #
458
+ # @option options_to_check [Object] :worktree truthy value requests worktree scope
459
+ #
460
+ # @option options_to_check [Object] :blob truthy value requests blob scope
461
+ #
462
+ # @raise [ArgumentError] if a repository-specific scope is requested
463
+ #
464
+ # @api private
465
+ #
466
+ def self.assert_valid_scope!(**options_to_check)
467
+ invalid = REPOSITORY_SPECIFIC_SCOPES.select { |s| options_to_check[s] }
468
+ return if invalid.empty?
469
+
470
+ raise ArgumentError, "#{invalid.join(', ')} scope requires a repository"
485
471
  end
472
+ private_class_method :assert_valid_scope!
486
473
  end