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
@@ -0,0 +1,522 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/arguments'
4
+ require 'git/system_call_guard'
5
+ require 'git/version'
6
+ require 'git/version_constraint'
7
+
8
+ module Git
9
+ module Commands
10
+ # @api private
11
+ #
12
+ # Base class for git command implementations.
13
+ #
14
+ # Provides default {#initialize} and {#call} methods so that simple commands
15
+ # only need to declare their arguments:
16
+ #
17
+ # class Add < Git::Commands::Base
18
+ # arguments do
19
+ # literal 'add'
20
+ # flag_option :all
21
+ # flag_option :force
22
+ # end_of_options
23
+ # operand :paths, repeatable: true
24
+ # end
25
+ #
26
+ # # Execute the git add command
27
+ # # ...YARD docs...
28
+ # def call(...) = super
29
+ # end
30
+ #
31
+ # Commands whose git process may exit with a non-zero status that is
32
+ # *not* an error can declare the acceptable range of exit codes:
33
+ #
34
+ # class Delete < Git::Commands::Base
35
+ # arguments do
36
+ # literal 'branch'
37
+ # literal '--delete'
38
+ # operand :branch_names, repeatable: true, required: true
39
+ # end
40
+ #
41
+ # allow_exit_status 0..1
42
+ #
43
+ # # Execute the git branch --delete command
44
+ # # ...YARD docs...
45
+ # def call(...) = super
46
+ # end
47
+ #
48
+ # Commands with execution options (e.g., timeout) work with the default
49
+ # `call` — execution options are extracted and forwarded automatically.
50
+ class Base # rubocop:disable Metrics/ClassLength
51
+ class << self
52
+ # @return [Git::Commands::Arguments, nil] the frozen argument definition for this command
53
+ attr_reader :args_definition
54
+
55
+ # Define the command's arguments using the {Arguments} DSL.
56
+ #
57
+ # @return [void]
58
+ #
59
+ # @raise [ArgumentError] if called more than once on the same class
60
+ #
61
+ # @yield the block passed to {Arguments.define}
62
+ #
63
+ def arguments(&)
64
+ raise ArgumentError, "arguments already defined for #{name}" if @args_definition
65
+
66
+ @args_definition = Arguments.define(&).freeze
67
+ end
68
+
69
+ # @return [Range, nil] range of exit status values accepted by this command
70
+ attr_reader :allowed_exit_status_range
71
+
72
+ # Declare the acceptable range of exit status values for this command.
73
+ #
74
+ # @example git-diff exits 1 when a diff is found (not an error)
75
+ # allow_exit_status 0..1
76
+ #
77
+ # @example git-fsck uses exit codes 0-7 as bit flags
78
+ # allow_exit_status 0..7
79
+ #
80
+ # @param range [Range] range of accepted exit status values
81
+ #
82
+ # @return [void]
83
+ #
84
+ # @raise [ArgumentError] if range is invalid
85
+ #
86
+ def allow_exit_status(range)
87
+ raise ArgumentError, 'allow_exit_status expects a Range' unless range.is_a?(Range)
88
+ unless range.begin.is_a?(Integer) && range.end.is_a?(Integer)
89
+ raise ArgumentError, 'allow_exit_status bounds must be Integers'
90
+ end
91
+
92
+ raise ArgumentError, 'allow_exit_status range must not be empty' if range.begin > range.end
93
+
94
+ @allowed_exit_status_range = range
95
+ end
96
+
97
+ # @return [Git::VersionConstraint, nil] version constraint for this command
98
+ #
99
+ # Returns +nil+ if the command is available in all supported git versions.
100
+ attr_reader :git_version_constraint
101
+
102
+ # @!attribute [r] skip_version_validation?
103
+ #
104
+ # @return [Boolean] whether this command skips version validation
105
+ def skip_version_validation? = !!@skip_version_validation
106
+
107
+ # Declare that this command should skip version validation.
108
+ #
109
+ # This is intended for internal use only — specifically for the
110
+ # `git version` command, which cannot validate versions without
111
+ # causing infinite recursion.
112
+ #
113
+ # @return [void]
114
+ #
115
+ # @api private
116
+ #
117
+ def skip_version_validation
118
+ @skip_version_validation = true
119
+ end
120
+
121
+ # Declare the git version requirements for this command.
122
+ #
123
+ # Use this when the command (or the specific sub-action this class wraps) was
124
+ # introduced in a git version later than +Git::MINIMUM_GIT_VERSION+, or when
125
+ # the command was removed in a later version. When not declared, the command
126
+ # is assumed to be available in all supported git versions.
127
+ #
128
+ # @example git-am --retry requires git 2.46.0 or later
129
+ # requires_git_version '2.46.0'
130
+ #
131
+ # @example Feature with version range
132
+ # requires_git_version '2.29.0', before: '2.50.0'
133
+ #
134
+ # @example Feature available before git 2.50.0
135
+ # requires_git_version before: '2.50.0'
136
+ #
137
+ # @param min [String, nil] minimum version
138
+ #
139
+ # @param before [String, nil] upper bound version (exclusive)
140
+ #
141
+ # @return [void]
142
+ #
143
+ # @raise [ArgumentError] if version format is invalid or called twice
144
+ #
145
+ def requires_git_version(min = nil, before: nil)
146
+ raise ArgumentError, 'requires_git_version already declared for this class' if @git_version_constraint
147
+
148
+ @git_version_constraint = normalize_version_constraint(min, before)
149
+ end
150
+
151
+ private
152
+
153
+ # Normalize a version constraint to a VersionConstraint
154
+ #
155
+ # @param min [String, nil] minimum version
156
+ #
157
+ # @param before_version [String, nil] upper bound version
158
+ #
159
+ # @return [Git::VersionConstraint] the normalized constraint
160
+ #
161
+ # @raise [ArgumentError] if the constraint is invalid
162
+ #
163
+ def normalize_version_constraint(min, before_version)
164
+ raise ArgumentError, 'requires_git_version requires min or before:' unless min || before_version
165
+
166
+ min_version = min ? parse_version(min, 'min') : nil
167
+ before_parsed = before_version ? parse_version(before_version, 'before:') : nil
168
+
169
+ Git::VersionConstraint.new(min: min_version, before: before_parsed)
170
+ end
171
+
172
+ # Parse a version string into a Git version object
173
+ #
174
+ # @param version [String] version string to parse
175
+ #
176
+ # @param key_name [String] argument name used in validation errors
177
+ #
178
+ # @return [Git::Version] the parsed version
179
+ #
180
+ # @raise [ArgumentError] if the version format is invalid
181
+ #
182
+ def parse_version(version, key_name)
183
+ validate_version_format!(version, key_name)
184
+ Git::Version.parse(version)
185
+ end
186
+
187
+ # Validate a version string uses the required format
188
+ #
189
+ # @param version [Object] value to validate
190
+ #
191
+ # @param context [String, nil] argument name included in validation errors
192
+ #
193
+ # @return [void]
194
+ #
195
+ # @raise [ArgumentError] if the value is not a `major.minor.patch` version string
196
+ #
197
+ def validate_version_format!(version, context = nil)
198
+ return if version.is_a?(String) && version.match?(/\A\d+\.\d+\.\d+\z/)
199
+
200
+ subject = context || 'a version'
201
+ raise ArgumentError,
202
+ "requires_git_version expects #{subject} to be a 'major.minor.patch' version string, " \
203
+ "got: #{version.inspect}"
204
+ end
205
+ end
206
+
207
+ # @param execution_context [Git::ExecutionContext] context that provides
208
+ # {Git::ExecutionContext#command_capturing} and {Git::ExecutionContext#command_streaming}
209
+ def initialize(execution_context)
210
+ @execution_context = execution_context
211
+ end
212
+
213
+ # Execute the git command.
214
+ #
215
+ # @overload call(*args, **kwargs)
216
+ # Bind arguments and execute the command.
217
+ #
218
+ # Execution options (declared via `execution_option` in the Arguments
219
+ # DSL) are extracted from the bound arguments via
220
+ # {Git::Commands::Arguments::Bound#execution_options} and forwarded as
221
+ # keyword arguments to the execution context via {#execute_command}.
222
+ #
223
+ # When the `:out` execution option is present, stdout is streamed using
224
+ # `@execution_context.command_streaming`. Otherwise, stdout is captured
225
+ # using `@execution_context.command_capturing`.
226
+ #
227
+ # @example
228
+ # # In a command subclass:
229
+ # # result = command.call('HEAD', timeout: 10)
230
+ #
231
+ # @param args [Array] positional arguments forwarded to {Arguments#bind}
232
+ #
233
+ # @param kwargs [Hash] keyword arguments forwarded to {Arguments#bind}
234
+ #
235
+ # @return [Git::CommandLine::Result] the result of calling `git`
236
+ #
237
+ # @raise [ArgumentError] if no arguments definition is declared on the command class
238
+ #
239
+ # @raise [Git::FailedError] if git returns an exit code outside the allowed range
240
+ #
241
+ # @raise [Git::VersionError] if the installed git version doesn't meet requirements
242
+ def call(*, **)
243
+ bound = args_definition.bind(*, **)
244
+ validate_version!(bound.execution_options)
245
+ result = execute_command(bound)
246
+ validate_exit_status!(result)
247
+ result
248
+ end
249
+
250
+ private
251
+
252
+ # Return the argument definition declared by this command class
253
+ #
254
+ # @return [Git::Commands::Arguments] the argument definition
255
+ #
256
+ # @raise [ArgumentError] if no argument definition is declared
257
+ #
258
+ def args_definition
259
+ self.class.args_definition || raise(ArgumentError, "arguments not defined for #{self.class.name}")
260
+ end
261
+
262
+ # Execute a bound git command through the execution context
263
+ #
264
+ # @param bound [Git::Commands::Arguments::Bound] bound command arguments
265
+ #
266
+ # @return [Git::CommandLine::Result] the command result
267
+ #
268
+ def execute_command(bound)
269
+ exec_opts = execution_opts(bound)
270
+
271
+ if exec_opts.key?(:out)
272
+ @execution_context.command_streaming(*bound, **exec_opts, raise_on_failure: false)
273
+ else
274
+ @execution_context.command_capturing(*bound, **capturing_opts(exec_opts), raise_on_failure: false)
275
+ end
276
+ end
277
+
278
+ # Build execution options for a bound command
279
+ #
280
+ # @param bound [Git::Commands::Arguments::Bound] bound command arguments
281
+ #
282
+ # @return [Hash] execution options for the command line
283
+ #
284
+ def execution_opts(bound)
285
+ caller_env = bound.execution_options.fetch(:env, {}) || {}
286
+ merged_env = caller_env.merge(env)
287
+ opts = bound.execution_options.except(:env)
288
+ merged_env.empty? ? opts : opts.merge(env: merged_env)
289
+ end
290
+
291
+ # Build options for captured command output
292
+ #
293
+ # @param exec_opts [Hash] execution options for the command line
294
+ #
295
+ # @return [Hash] options for captured command output
296
+ #
297
+ def capturing_opts(exec_opts)
298
+ opts = exec_opts
299
+ opts = opts.merge(normalize: false) unless normalize_captured_stdout?
300
+ opts = opts.merge(chomp: false) unless chomp_captured_stdout?
301
+ opts
302
+ end
303
+
304
+ # Whether {#execute_command} should apply Ruby string normalization to
305
+ # `result.stdout` on the capturing path.
306
+ #
307
+ # When `true` (the default), `command_capturing` normalizes the encoding of
308
+ # captured stdout. Override to return `false` in subclasses whose output is
309
+ # intrinsically binary (e.g. `git archive`), so that stdout bytes in
310
+ # `result.stdout` are returned unchanged.
311
+ #
312
+ # This hook only affects the **capturing** path — when an `out:` execution
313
+ # option is present, stdout is streamed directly to the caller-supplied IO
314
+ # object and is never normalized or chomped regardless of this setting.
315
+ #
316
+ # @return [Boolean]
317
+ def normalize_captured_stdout?
318
+ true
319
+ end
320
+
321
+ # Whether {#execute_command} should chomp trailing newlines from
322
+ # `result.stdout` on the capturing path.
323
+ #
324
+ # When `true` (the default), `command_capturing` strips the trailing
325
+ # newline from captured stdout. Override to return `false` in subclasses
326
+ # whose output must preserve trailing whitespace (e.g. `git show`, which
327
+ # can return blob content with significant trailing newlines).
328
+ #
329
+ # This hook only affects the **capturing** path — when an `out:` execution
330
+ # option is present, stdout is streamed directly to the caller-supplied IO
331
+ # object and is never chomped regardless of this setting.
332
+ #
333
+ # @return [Boolean]
334
+ def chomp_captured_stdout?
335
+ true
336
+ end
337
+
338
+ # Environment variable overrides to pass to the subprocess.
339
+ #
340
+ # Returns an empty hash by default. Subclasses may override this method
341
+ # to inject process-level environment changes required for correctness
342
+ # (e.g. unsetting `GIT_INDEX_FILE` for worktree management commands).
343
+ #
344
+ # The returned hash is merged with any environment overrides the caller
345
+ # supplies via the `env:` execution option — this hook's values win on
346
+ # conflict so that safety invariants cannot be accidentally overridden.
347
+ #
348
+ # @return [Hash] environment variable overrides (key: variable name, value: new value or nil to unset)
349
+ #
350
+ def env
351
+ {}
352
+ end
353
+
354
+ # Return the allowed exit status range for this command
355
+ #
356
+ # @return [Range] range of accepted exit status values
357
+ #
358
+ def allowed_exit_status_range
359
+ self.class.allowed_exit_status_range || (0..0)
360
+ end
361
+
362
+ # Validate that a command result has an accepted exit status
363
+ #
364
+ # @param result [Git::CommandLine::Result] command result to validate
365
+ #
366
+ # @return [void]
367
+ #
368
+ # @raise [Git::FailedError] if the result exit status is not accepted
369
+ #
370
+ def validate_exit_status!(result)
371
+ raise Git::FailedError, result unless allowed_exit_status_range.include?(result.status.exitstatus)
372
+ end
373
+
374
+ # Validate that the installed git version meets requirements
375
+ #
376
+ # Raises Git::VersionError if:
377
+ # 1. The installed version is below Git::MINIMUM_GIT_VERSION (floor check)
378
+ # 2. The command has a class-level constraint that isn't satisfied
379
+ #
380
+ # Floor check always runs first and fails fast.
381
+ #
382
+ # @param exec_opts [Hash] execution options used to query git version
383
+ #
384
+ # @return [void]
385
+ #
386
+ # @raise [Git::VersionError] if the installed git version is unsupported
387
+ #
388
+ def validate_version!(exec_opts = {})
389
+ return if self.class.skip_version_validation?
390
+
391
+ actual_version = @execution_context.git_version(timeout: exec_opts[:timeout])
392
+
393
+ # Floor check: fail-fast if git is too old for the gem itself
394
+ validate_floor_version!(actual_version)
395
+
396
+ # Class-level constraint check
397
+ validate_class_version_constraint!(actual_version)
398
+ end
399
+
400
+ # Validate that git satisfies the gem-wide minimum version
401
+ #
402
+ # @param actual_version [Git::Version] installed git version
403
+ #
404
+ # @return [void]
405
+ #
406
+ # @raise [Git::VersionError] if the installed git version is too old
407
+ #
408
+ def validate_floor_version!(actual_version)
409
+ return if actual_version >= Git::MINIMUM_GIT_VERSION
410
+
411
+ raise Git::VersionError.new(
412
+ subject: 'The git gem',
413
+ constraint: Git::VersionConstraint.new(min: Git::MINIMUM_GIT_VERSION, before: nil),
414
+ actual_version: actual_version
415
+ )
416
+ end
417
+
418
+ # Validate that git satisfies this command class's version constraint
419
+ #
420
+ # @param actual_version [Git::Version] installed git version
421
+ #
422
+ # @return [void]
423
+ #
424
+ # @raise [Git::VersionError] if the installed git version is unsupported
425
+ #
426
+ def validate_class_version_constraint!(actual_version)
427
+ constraint = self.class.git_version_constraint
428
+ return unless constraint
429
+ return if constraint.satisfied_by?(actual_version)
430
+
431
+ raise Git::VersionError.new(
432
+ subject: self.class,
433
+ constraint: constraint,
434
+ actual_version: actual_version
435
+ )
436
+ end
437
+
438
+ # Opens an in-memory IO pipe, spawns a background thread to write
439
+ # `content` to the write end (then close it), and immediately yields
440
+ # the read end. The write and close happen concurrently with the block.
441
+ #
442
+ # The read end can be passed as the `in:` keyword to
443
+ # {Git::ExecutionContext#command_capturing} / {Git::CommandLine#run_with_capture}, connecting it directly to
444
+ # the spawned git process's stdin without an intermediate file or shell
445
+ # heredoc. This is required because `Process.spawn` only accepts real IO
446
+ # objects with a file descriptor — `StringIO` does not work.
447
+ #
448
+ # The threaded write prevents deadlocks when `content` exceeds the OS
449
+ # pipe buffer: the subprocess can drain the pipe concurrently while the
450
+ # writer thread continues writing.
451
+ #
452
+ # Pass an empty string when the process should receive no input (e.g.
453
+ # when `--batch-all-objects` is used and git enumerates objects itself).
454
+ #
455
+ # Both ends of the pipe are closed by the time this method returns or
456
+ # raises, whether the failure happens in the block, in the writer thread,
457
+ # or before the writer thread can be started.
458
+ #
459
+ # @example Feed bound object names to a git batch command
460
+ # bound = args_definition.bind(*args, **kwargs)
461
+ # stdin_content = Array(bound.object).map { |object| "#{object}\n" }.join
462
+ # with_stdin(stdin_content) do |reader|
463
+ # @execution_context.command_capturing('cat-file', '--batch-check', in: reader, raise_on_failure: false)
464
+ # end
465
+ #
466
+ # @param content [String] text to write to the process's stdin
467
+ #
468
+ # @return [Object] the value returned by the block
469
+ #
470
+ # @raise [Git::Error] if the pipe cannot be created (for example, when the
471
+ # process is out of file descriptors); the `SystemCallError` is the `cause`
472
+ #
473
+ # @raise [Git::Error] if the writer thread cannot be started (for example,
474
+ # when the process cannot allocate another thread); the `ThreadError` is
475
+ # the `cause`
476
+ #
477
+ # @yield [reader] the read end of the pipe
478
+ #
479
+ # @yieldparam reader [IO] the read end of the pipe; valid only for the
480
+ # duration of the block
481
+ #
482
+ # @yieldreturn [Object] the block's return value, which becomes the method's return value
483
+ #
484
+ def with_stdin(content)
485
+ reader, writer = Git::SystemCallGuard.call('Failed to create a pipe for stdin') { IO.pipe }
486
+ writer_thread = start_stdin_writer(content, writer)
487
+ yield reader
488
+ ensure
489
+ reader.close unless reader.nil? || reader.closed?
490
+ # The writer thread owns writer and closes it when it finishes. Close it
491
+ # here only when the thread was never started (Thread.new raised).
492
+ writer.close if writer_thread.nil? && !(writer.nil? || writer.closed?)
493
+ writer_thread&.join
494
+ end
495
+
496
+ # Spawns a thread that writes content to writer then closes it.
497
+ # Rescues EPIPE/IOError so the thread exits cleanly when the subprocess
498
+ # closes its stdin early (e.g. on error exit before reading all input).
499
+ #
500
+ # @param content [String] text to write to the pipe
501
+ #
502
+ # @param writer [IO] write end of the pipe
503
+ #
504
+ # @return [Thread] thread writing content to the pipe
505
+ #
506
+ # @raise [Git::Error] if the thread cannot be started; the `ThreadError` is
507
+ # the `cause`
508
+ #
509
+ def start_stdin_writer(content, writer)
510
+ Thread.new do
511
+ writer.write(content) unless content.empty?
512
+ rescue Errno::EPIPE, IOError
513
+ nil # subprocess closed stdin early
514
+ ensure
515
+ writer.close unless writer.closed?
516
+ end
517
+ rescue ThreadError => e
518
+ raise Git::Error, "Failed to start the stdin writer thread: #{e.message}"
519
+ end
520
+ end
521
+ end
522
+ end
@@ -0,0 +1,102 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/base'
4
+
5
+ module Git
6
+ module Commands
7
+ module Branch
8
+ # Implements the `git branch --copy` command for copying branches
9
+ #
10
+ # This command copies a branch, together with its config and reflog.
11
+ # If the old branch name is omitted, copies the current branch.
12
+ #
13
+ # @example Copy the current branch
14
+ # copy = Git::Commands::Branch::Copy.new(execution_context)
15
+ # copy.call('new-branch-name')
16
+ #
17
+ # @example Copy a specific branch
18
+ # copy = Git::Commands::Branch::Copy.new(execution_context)
19
+ # copy.call('old-branch-name', 'new-branch-name')
20
+ #
21
+ # @example Force copy (overwrite existing branch)
22
+ # copy = Git::Commands::Branch::Copy.new(execution_context)
23
+ # copy.call('old-branch', 'existing-branch', force: true)
24
+ #
25
+ # @note `arguments` block audited against https://git-scm.com/docs/git-branch/2.53.0
26
+ #
27
+ # @see Git::Commands::Branch
28
+ #
29
+ # @see https://git-scm.com/docs/git-branch git-branch
30
+ #
31
+ # @api private
32
+ #
33
+ class Copy < Git::Commands::Base
34
+ # NOTE: The positional arguments follow Ruby semantics:
35
+ # - When one positional is provided, it fills new_branch (required)
36
+ # - When two positionals are provided, they fill old_branch and new_branch
37
+ #
38
+ # This matches the git CLI: `git branch -c [<old-branch>] <new-branch>`
39
+ arguments do
40
+ literal 'branch'
41
+ literal '--copy'
42
+ flag_option %i[force f]
43
+
44
+ end_of_options
45
+
46
+ operand :old_branch
47
+ operand :new_branch, required: true
48
+ end
49
+
50
+ # Executes the git branch --copy command to copy a branch
51
+ #
52
+ # @overload call(new_branch, **options)
53
+ #
54
+ # Copies the current branch to the new_branch
55
+ #
56
+ # @param new_branch [String] the new name for the copied branch
57
+ #
58
+ # @param options [Hash] command options
59
+ #
60
+ # @option options [Boolean, nil] :force (nil) allow copying even if new_branch already
61
+ # exists
62
+ #
63
+ # Alias: :f
64
+ #
65
+ # @return [Git::CommandLine::Result] the result of calling `git branch --copy`
66
+ #
67
+ # @raise [ArgumentError] if unsupported options are provided
68
+ #
69
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
70
+ #
71
+ # @api public
72
+ #
73
+ # @overload call(old_branch, new_branch, **options)
74
+ #
75
+ # Copies old_branch to new_branch
76
+ #
77
+ # @param old_branch [String] branch to copy from
78
+ #
79
+ # @param new_branch [String] the new name for the copied branch
80
+ #
81
+ # @param options [Hash] command options
82
+ #
83
+ # @option options [Boolean, nil] :force (nil) allow copying even if new_branch already
84
+ # exists
85
+ #
86
+ # Alias: :f
87
+ #
88
+ # @return [Git::CommandLine::Result] the result of calling `git branch --copy`
89
+ #
90
+ # @raise [ArgumentError] if unsupported options are provided
91
+ #
92
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
93
+ #
94
+ # @api public
95
+ #
96
+ def call(*, **)
97
+ super
98
+ end
99
+ end
100
+ end
101
+ end
102
+ end