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,65 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/gc'
4
+ require 'git/commands/repack'
5
+
6
+ module Git
7
+ class Repository
8
+ # Facade methods for repository maintenance and optimization operations
9
+ #
10
+ # These methods pack objects, compress history, prune unreachable objects, and
11
+ # otherwise keep the repository in good health.
12
+ #
13
+ # Included by {Git::Repository}.
14
+ #
15
+ # @api private
16
+ #
17
+ module Maintenance
18
+ # Repack loose objects into pack files
19
+ #
20
+ # Packs all unpacked objects and removes redundant pack files. This is
21
+ # equivalent to running `git repack -a -d`, which packs all objects into a
22
+ # single pack and deletes any packs that become redundant.
23
+ #
24
+ # This method uses the fixed options `a: true, d: true` (matching the 4.x
25
+ # behavior). No additional options are exposed.
26
+ #
27
+ # @example Repack the repository
28
+ # repo.repack
29
+ #
30
+ # @return [String] the stdout from `git repack`. Git writes all progress
31
+ # and summary output to stderr, so the returned string is typically empty.
32
+ # Returns `String` to match the 4.x public contract (`Git::Lib#command`
33
+ # returned `result.stdout`).
34
+ #
35
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
36
+ #
37
+ def repack
38
+ Git::Commands::Repack.new(@execution_context).call(a: true, d: true).stdout
39
+ end
40
+
41
+ # Run garbage collection to optimize and clean up the repository
42
+ #
43
+ # Runs `git gc` to perform housekeeping tasks including object compression,
44
+ # pruning of unreachable objects, and ref packing. This is equivalent to
45
+ # running `git gc --prune --aggressive --auto`.
46
+ #
47
+ # This method uses the fixed options `prune: true, aggressive: true, auto: true`
48
+ # (matching the 4.x behavior). No additional options are exposed.
49
+ #
50
+ # @example Run garbage collection
51
+ # repo.gc
52
+ #
53
+ # @return [String] the stdout from `git gc`. Git writes all progress
54
+ # and summary output to stderr, so the returned string is typically empty.
55
+ # Returns `String` to match the 4.x public contract (`Git::Lib#command`
56
+ # returned `result.stdout`).
57
+ #
58
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
59
+ #
60
+ def gc
61
+ Git::Commands::Gc.new(@execution_context).call(prune: true, aggressive: true, auto: true).stdout
62
+ end
63
+ end
64
+ end
65
+ end
@@ -0,0 +1,429 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'tempfile'
4
+ require 'git/commands/diff'
5
+ require 'git/commands/merge/start'
6
+ require 'git/commands/merge_base'
7
+ require 'git/commands/revert/start'
8
+ require 'git/commands/show'
9
+ require 'git/repository/shared_private'
10
+ require 'git/system_call_guard'
11
+
12
+ module Git
13
+ class Repository
14
+ # Facade methods for merge operations: merging branches into the current branch
15
+ # or into another branch, and finding common ancestors between commits
16
+ #
17
+ # Included by {Git::Repository}.
18
+ #
19
+ # @api private
20
+ #
21
+ module Merging
22
+ # Option keys accepted by {#merge}
23
+ #
24
+ # Derived from the 4.x option map for `Git::Lib#merge`.
25
+ MERGE_ALLOWED_OPTS = %i[no_commit no_ff m message].freeze
26
+ private_constant :MERGE_ALLOWED_OPTS
27
+
28
+ # Option keys accepted by {#merge_base}
29
+ #
30
+ # Derived from the 4.x option map for `Git::Lib#merge_base`.
31
+ MERGE_BASE_ALLOWED_OPTS = %i[octopus independent fork_point all].freeze
32
+ private_constant :MERGE_BASE_ALLOWED_OPTS
33
+
34
+ # Merge one or more branches into the current branch
35
+ #
36
+ # The merge commit message may be given by the message positional argument, the
37
+ # `:message` option, or the `:m` option; if more than one is provided, the
38
+ # precedence is positional argument > `:message` > `:m`.
39
+ #
40
+ # @example Merge a single branch
41
+ # repo.merge('feature')
42
+ #
43
+ # @example Merge a branch with a no-fast-forward commit message
44
+ # repo.merge('feature', 'Merge feature into main', no_ff: true)
45
+ #
46
+ # @example Octopus merge of multiple branches
47
+ # repo.merge(%w[feature-a feature-b])
48
+ #
49
+ # @example Merge without committing
50
+ # repo.merge('feature', nil, no_commit: true)
51
+ #
52
+ # @param branch [#to_s, Array<#to_s>] the branch or branches to merge into the
53
+ # current branch
54
+ #
55
+ # When an Array is given, an octopus merge is performed; each branch-ish
56
+ # object (e.g., {Git::BranchInfo}) is coerced to a String via `#to_s`.
57
+ #
58
+ # @param message [String, nil] optional commit message for the merge commit
59
+ #
60
+ # Translated to the `-m` flag internally. For fast-forward merges git ignores
61
+ # this value; use `no_ff: true` to ensure a merge commit is created and the
62
+ # message is recorded.
63
+ #
64
+ # @param opts [Hash] additional options forwarded to `git merge`
65
+ #
66
+ # @option opts [Boolean, nil] :no_commit (nil) stop before creating the merge commit
67
+ # (`--no-commit`)
68
+ #
69
+ # @option opts [Boolean, nil] :no_ff (nil) create a merge commit even when
70
+ # fast-forward is possible (`--no-ff`)
71
+ #
72
+ # @option opts [String] :message (nil) commit message
73
+ #
74
+ # Prefer the `:m` option instead of this one. Translated to the `-m` flag.
75
+ # Identical to the positional `message` argument and the `:m` option.
76
+ #
77
+ # @option opts [String] :m (nil) commit message (`-m` flag)
78
+ #
79
+ # @return [String] git's stdout from the merge command
80
+ #
81
+ # @raise [ArgumentError] when unsupported options are provided
82
+ #
83
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
84
+ #
85
+ # @note On a conflict, the merge is left in progress: the conflicted paths
86
+ # are in the index and working tree, and `MERGE_HEAD` is set until the
87
+ # caller commits the resolution or aborts the merge.
88
+ #
89
+ def merge(branch, message = nil, opts = {})
90
+ SharedPrivate.assert_valid_opts!(MERGE_ALLOWED_OPTS, **opts)
91
+
92
+ # Dup so callers who reuse the same opts hash are not affected
93
+ opts = opts.dup
94
+
95
+ # Merge positional message into opts so the rest of the logic is uniform
96
+ opts[:message] = message if message
97
+
98
+ # git merge uses -m, not --message; translate the key
99
+ opts[:m] = opts.delete(:message) if opts.key?(:message)
100
+
101
+ branches = Array(branch).map(&:to_s)
102
+ Git::Commands::Merge::Start.new(@execution_context).call(*branches, no_edit: true, **opts).stdout
103
+ end
104
+
105
+ # Option keys accepted by {#merge_into}
106
+ #
107
+ # The keys accepted by {#merge} except `:no_commit`. A merge stopped before
108
+ # its commit leaves `target_branch` unchanged, and the restore checkout would
109
+ # carry the staged merge result onto the original branch instead.
110
+ MERGE_INTO_ALLOWED_OPTS = %i[no_ff m message].freeze
111
+ private_constant :MERGE_INTO_ALLOWED_OPTS
112
+
113
+ # Merge one or more branches into another branch without leaving the current branch
114
+ #
115
+ # Records the current branch (or the current commit when HEAD is detached),
116
+ # checks out `target_branch`, merges `branch` into it with {#merge}, then
117
+ # checks out the original branch or commit again. Use {#merge} directly when
118
+ # the target is the currently checked-out branch.
119
+ #
120
+ # `target_branch` must be an existing local branch. Unlike {#checkout}, a
121
+ # commit SHA, tag, or remote-tracking branch is rejected before any checkout
122
+ # happens: those detach HEAD, and the merge commit made there would be left
123
+ # dangling once the original branch is restored while the named ref stayed
124
+ # unchanged.
125
+ #
126
+ # HEAD must be on a branch with at least one commit, or detached: an unborn
127
+ # branch (no commits yet) cannot be checked out again by name, so it is
128
+ # rejected before any checkout happens.
129
+ #
130
+ # Option keys, the source list, and `target_branch` are checked before any
131
+ # branch is checked out, so those failures never leave the repository on
132
+ # `target_branch`. Anything rejected later, such as an option value that is
133
+ # not accepted or a source ref that does not exist, surfaces inside {#merge}
134
+ # after the checkout and leaves the repository checked out on `target_branch`.
135
+ #
136
+ # The `:no_commit` option is not accepted: a merge stopped before its commit
137
+ # would leave `target_branch` unchanged and the restore checkout would carry
138
+ # the staged result onto the original branch. To merge without committing,
139
+ # call {#checkout} and {#merge} directly.
140
+ #
141
+ # @example Merge a feature branch into main while staying on the current branch
142
+ # repo.merge_into('main', 'feature')
143
+ #
144
+ # @example Merge with a no-fast-forward commit message
145
+ # repo.merge_into('main', 'feature', 'Merge feature into main', no_ff: true)
146
+ #
147
+ # @example Octopus merge of multiple branches into main
148
+ # repo.merge_into('main', %w[feature-a feature-b])
149
+ #
150
+ # @param target_branch [String] the name of an existing local branch to
151
+ # merge into
152
+ #
153
+ # @param branch [#to_s, Array<#to_s>] the branch or branches to merge into
154
+ # `target_branch`; accepts the same forms as {#merge}, but must name at
155
+ # least one branch
156
+ #
157
+ # @param message [String, nil] optional commit message for the merge commit;
158
+ # see {#merge} for how it interacts with the `:message` and `:m` options
159
+ #
160
+ # @param opts [Hash] additional options forwarded to {#merge}
161
+ #
162
+ # @option opts [Boolean, nil] :no_ff (nil) create a merge commit even when
163
+ # fast-forward is possible (`--no-ff`)
164
+ #
165
+ # @option opts [String] :message (nil) commit message; prefer the `:m` option
166
+ #
167
+ # @option opts [String] :m (nil) commit message (`-m` flag)
168
+ #
169
+ # @return [String] git's stdout from the merge command
170
+ #
171
+ # @raise [ArgumentError] when unsupported options (including `:no_commit`)
172
+ # are provided
173
+ #
174
+ # @raise [ArgumentError] when `branch` is `nil` or an empty Array
175
+ #
176
+ # @raise [ArgumentError] when `target_branch` is not an existing local branch
177
+ #
178
+ # @raise [Git::Error] when HEAD is on an unborn branch
179
+ #
180
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
181
+ #
182
+ # @note If the merge or the restore checkout fails, the repository is left
183
+ # checked out on `target_branch` rather than restored to the original
184
+ # branch. On a conflict, the merge is also left in progress. When the
185
+ # restore checkout is the step that fails, the merge has already been
186
+ # committed on `target_branch`.
187
+ #
188
+ def merge_into(target_branch, branch, message = nil, opts = {})
189
+ SharedPrivate.assert_valid_opts!(MERGE_INTO_ALLOWED_OPTS, **opts)
190
+ raise ArgumentError, 'at least one branch to merge is required' if Array(branch).empty?
191
+
192
+ SharedPrivate.assert_local_branch!(self, target_branch)
193
+ restore_point = SharedPrivate.head_restore_point(self)
194
+ checkout(target_branch)
195
+ output = merge(branch, message, opts)
196
+ # Runs only on success. See ADR-0009.
197
+ checkout(restore_point)
198
+ output
199
+ end
200
+
201
+ # Find common ancestor commit(s) for use in a merge
202
+ #
203
+ # @example Find the common ancestor of two branches
204
+ # repo.merge_base('main', 'feature') #=> ["abc123def456..."]
205
+ #
206
+ # @example Find all common ancestors of two branches
207
+ # repo.merge_base('branch-a', 'branch-b', all: true)
208
+ #
209
+ # @example Find the fork point of a branch (consults the reflog)
210
+ # repo.merge_base('main', 'feature', fork_point: true)
211
+ #
212
+ # @example Find independent commits not reachable from each other
213
+ # repo.merge_base('abc1234', 'main', 'feature', independent: true)
214
+ #
215
+ # @overload merge_base(*commits, options = {})
216
+ #
217
+ # @param commits [Array<String>] two or more commit SHAs, branch names,
218
+ # or refs to find the common ancestor(s) of
219
+ #
220
+ # @param options [Hash] merge-base options
221
+ #
222
+ # @option options [Boolean, nil] :octopus (nil) compute the best common
223
+ # ancestor for an n-way merge (intersection of all merge bases)
224
+ #
225
+ # @option options [Boolean, nil] :independent (nil) list commits not
226
+ # reachable from any other; useful for finding minimal merge points
227
+ #
228
+ # @option options [Boolean, nil] :fork_point (nil) find the fork point
229
+ # where a branch diverged from another, consulting the reflog
230
+ #
231
+ # @option options [Boolean, nil] :all (nil) output all merge bases instead
232
+ # of just the first when multiple equally good bases exist
233
+ #
234
+ # @return [Array<String>] commit SHAs of the common ancestor(s); empty
235
+ # when no common ancestor exists or `--fork-point` finds none
236
+ #
237
+ # @raise [ArgumentError] when unsupported options are provided
238
+ #
239
+ # @raise [Git::FailedError] when `git merge-base` exits outside the
240
+ # allowed range (exit code > 1)
241
+ #
242
+ def merge_base(*args)
243
+ opts = args.last.is_a?(Hash) ? args.pop : {}
244
+ SharedPrivate.assert_valid_opts!(MERGE_BASE_ALLOWED_OPTS, **opts)
245
+ result = Git::Commands::MergeBase.new(@execution_context).call(*args, **opts)
246
+ result.stdout.lines.map(&:strip).reject(&:empty?)
247
+ end
248
+
249
+ # Return the paths of files with unresolved merge conflicts
250
+ #
251
+ # @example List conflicting files after a failed merge
252
+ # paths = repo.unmerged
253
+ # # => ["config/settings.rb", "lib/git/base.rb"]
254
+ # paths.each { |path| puts "Conflict in #{path}" }
255
+ #
256
+ # @return [Array<String>] repository-relative paths of files with unresolved
257
+ # merge conflicts; empty array when the working tree has no conflicts
258
+ #
259
+ # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
260
+ #
261
+ # @see #each_conflict
262
+ #
263
+ def unmerged
264
+ Private.unmerged_paths(@execution_context)
265
+ end
266
+
267
+ # Iterate over files with merge conflicts, yielding conflict details for each
268
+ #
269
+ # For each unmerged file, the staged content for both sides of the conflict
270
+ # (stage 2 "ours" and stage 3 "theirs") is written to temporary files whose
271
+ # paths are yielded alongside the file path. The temporary files are deleted
272
+ # automatically when the block returns.
273
+ #
274
+ # @example Inspect conflicting files
275
+ # repo.each_conflict do |file, your_version, their_version|
276
+ # puts "Conflict in #{file}"
277
+ # puts "Your version:"
278
+ # puts File.read(your_version)
279
+ # puts "Their version:"
280
+ # puts File.read(their_version)
281
+ # end
282
+ #
283
+ # @return [Array<String>] the list of unmerged file paths
284
+ #
285
+ # @raise [Git::FailedError] when `git diff --cached` exits outside the
286
+ # allowed range (exit code > 2)
287
+ #
288
+ # @raise [Git::Error] when the staged content cannot be written to a
289
+ # temporary file
290
+ #
291
+ # @yield [file, your_version, their_version] passes conflict details for
292
+ # each unmerged file
293
+ #
294
+ # @yieldparam file [String] path to the conflicting file, relative to the
295
+ # working tree
296
+ #
297
+ # @yieldparam your_version [String] path to a temporary file containing the
298
+ # stage-2 (ours) content for the conflicting file
299
+ #
300
+ # @yieldparam their_version [String] path to a temporary file containing the
301
+ # stage-3 (theirs) content for the conflicting file
302
+ #
303
+ # @yieldreturn [void]
304
+ #
305
+ def each_conflict
306
+ Private.unmerged_paths(@execution_context).each do |file_path|
307
+ Private.write_staged_file(@execution_context, file_path, 2) do |your_file|
308
+ Private.write_staged_file(@execution_context, file_path, 3) do |their_file|
309
+ yield(file_path, your_file.path, their_file.path)
310
+ end
311
+ end
312
+ end
313
+ end
314
+
315
+ # Option keys accepted by {#revert}
316
+ #
317
+ # Derived from the 4.x option map for `Git::Lib#revert`.
318
+ REVERT_ALLOWED_OPTS = %i[no_edit].freeze
319
+ private_constant :REVERT_ALLOWED_OPTS
320
+
321
+ # Revert one or more existing commits by creating new commits that undo
322
+ # the changes those commits introduced
323
+ #
324
+ # The working tree must be clean before calling this method. By default
325
+ # the editor is suppressed (`--no-edit`) so the commit message is taken
326
+ # from git's default revert message without prompting.
327
+ #
328
+ # @example Revert the most recent commit
329
+ # repo.revert('HEAD')
330
+ #
331
+ # @example Revert a specific commit by SHA
332
+ # repo.revert('abc1234')
333
+ #
334
+ # @example Revert a range of commits
335
+ # repo.revert('HEAD~3..HEAD~1')
336
+ #
337
+ # @example Revert without suppressing the editor
338
+ # repo.revert('HEAD', no_edit: false)
339
+ #
340
+ # @param commitish [String, nil] the commit, ref, or rev range to revert;
341
+ # see `gitrevisions(7)` for accepted forms; defaults to `'HEAD'` when
342
+ # `nil`
343
+ #
344
+ # @param opts [Hash] additional options forwarded to `git revert`
345
+ #
346
+ # @option opts [Boolean, nil] :no_edit (true) suppress the commit-message
347
+ # editor (`--no-edit`); pass `false` to open the editor
348
+ #
349
+ # @return [String] git's stdout from the revert command
350
+ #
351
+ # @raise [ArgumentError] when unsupported options are provided
352
+ #
353
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
354
+ #
355
+ # @note On a conflict, the revert is left in progress with the conflicted
356
+ # paths in the index and working tree until the caller continues, skips,
357
+ # or aborts it. When more than one commit is reverted, the revert commits
358
+ # made before the conflict are on the branch; aborting the revert removes
359
+ # them again.
360
+ #
361
+ def revert(commitish = nil, opts = {})
362
+ commitish = 'HEAD' if commitish.nil?
363
+ SharedPrivate.assert_valid_opts!(REVERT_ALLOWED_OPTS, **opts)
364
+ opts = { no_edit: true }.merge(opts)
365
+ Git::Commands::Revert::Start.new(@execution_context).call(commitish, **opts).stdout
366
+ end
367
+
368
+ # Private helpers local to {Git::Repository::Merging}
369
+ #
370
+ # @api private
371
+ module Private
372
+ # Tempfile name prefixes for staged content, keyed by git stage index
373
+ STAGE_PREFIXES = { 2 => 'YOUR-', 3 => 'THEIR-' }.freeze
374
+
375
+ module_function
376
+
377
+ # Returns the list of file paths with unresolved merge conflicts
378
+ #
379
+ # @param execution_context [Git::ExecutionContext] the execution context
380
+ # used to run git commands
381
+ #
382
+ # @return [Array<String>] unmerged file paths
383
+ #
384
+ # @api private
385
+ #
386
+ def unmerged_paths(execution_context)
387
+ result = Git::Commands::Diff.new(execution_context).call(cached: true)
388
+ result.stdout.split("\n").filter_map do |line|
389
+ ::Regexp.last_match(1) if line =~ /^\* Unmerged path (.*)/
390
+ end
391
+ end
392
+
393
+ # Creates a Tempfile with the staged content for `file_path` at `stage`
394
+ # and yields the open IO object to the block
395
+ #
396
+ # @param execution_context [Git::ExecutionContext] the execution context
397
+ # used to run git commands
398
+ #
399
+ # @param file_path [String] repository-relative path to the conflicting file
400
+ #
401
+ # @param stage [Integer] git stage index (2 = ours, 3 = theirs)
402
+ #
403
+ # @return [void]
404
+ #
405
+ # @raise [Git::Error] if the staged content cannot be written to a
406
+ # temporary file
407
+ #
408
+ # @yield [f] yields the open Tempfile containing the staged content
409
+ #
410
+ # @yieldparam f [Tempfile] open IO object for the staged content
411
+ #
412
+ # @yieldreturn [void]
413
+ #
414
+ # @api private
415
+ #
416
+ def write_staged_file(execution_context, file_path, stage, &block)
417
+ Git::SystemCallGuard.call('Failed to write the staged content to a temporary file') do |guard|
418
+ Tempfile.create([STAGE_PREFIXES[stage], File.basename(file_path)]) do |f|
419
+ Git::Commands::Show.new(execution_context).call(":#{stage}:#{file_path}", out: f)
420
+ f.flush
421
+ guard.unguarded { block.call(f) }
422
+ end
423
+ end
424
+ end
425
+ end
426
+ private_constant :Private
427
+ end
428
+ end
429
+ end