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,221 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/commit'
4
+ require 'git/commands/commit_tree'
5
+ require 'git/commands/write_tree'
6
+ require 'git/repository/shared_private'
7
+
8
+ module Git
9
+ class Repository
10
+ # Facade methods for committing operations: recording commits, manipulating
11
+ # tree objects, and building commit objects outside the working tree
12
+ #
13
+ # Included by {Git::Repository}.
14
+ #
15
+ # @api private
16
+ #
17
+ module Committing
18
+ # Option keys accepted by {#commit}
19
+ COMMIT_ALLOWED_OPTS = %i[
20
+ all amend allow_empty allow_empty_message author date
21
+ gpg_sign no_gpg_sign no_verify
22
+ ].freeze
23
+ private_constant :COMMIT_ALLOWED_OPTS
24
+
25
+ # Option keys accepted by {#commit_tree}
26
+ COMMIT_TREE_ALLOWED_OPTS = %i[parent p parents message m].freeze
27
+ private_constant :COMMIT_TREE_ALLOWED_OPTS
28
+
29
+ # Record staged changes as a new commit
30
+ #
31
+ # @example Commit with a message
32
+ # repo.commit('Add README')
33
+ #
34
+ # @example Amend the previous commit, reusing its message
35
+ # repo.commit(nil, amend: true)
36
+ #
37
+ # @example Stage all modified files and commit
38
+ # repo.commit('Cleanup', all: true)
39
+ #
40
+ # @param message [String, nil] the commit message; pass `nil` to omit
41
+ # (e.g. when using `:amend` to reuse the previous message)
42
+ #
43
+ # @param opts [Hash] options for the commit command
44
+ #
45
+ # @option opts [Boolean, nil] :all (nil) automatically stage modified and
46
+ # deleted files before committing
47
+ #
48
+ # @option opts [Boolean, nil] :amend (nil) replace the tip of the current
49
+ # branch with a new commit
50
+ #
51
+ # @option opts [Boolean, nil] :allow_empty (nil) allow committing with no
52
+ # changes
53
+ #
54
+ # @option opts [Boolean, nil] :allow_empty_message (nil) allow committing
55
+ # with an empty message
56
+ #
57
+ # @option opts [String] :author (nil) override the commit author in
58
+ # `A U Thor <author@example.com>` format
59
+ #
60
+ # @option opts [String] :date (nil) override the author date
61
+ #
62
+ # @option opts [Boolean, String, nil] :gpg_sign (nil) GPG-sign the commit
63
+ #
64
+ # @option opts [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
65
+ #
66
+ # @option opts [Boolean, nil] :no_verify (nil) bypass the pre-commit and
67
+ # commit-msg hooks
68
+ #
69
+ # @return [String] git's stdout from the commit
70
+ #
71
+ # @raise [ArgumentError] when unsupported options are provided
72
+ #
73
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
74
+ #
75
+ def commit(message, opts = {})
76
+ SharedPrivate.assert_valid_opts!(COMMIT_ALLOWED_OPTS, **opts)
77
+
78
+ call_opts = { no_edit: true }
79
+ call_opts[:message] = message if message
80
+
81
+ Git::Commands::Commit.new(@execution_context).call(**call_opts, **opts).stdout
82
+ end
83
+
84
+ # Commit all modified tracked files without explicitly staging them first
85
+ #
86
+ # Equivalent to calling {#commit} with `all: true` merged into `opts`.
87
+ #
88
+ # @example Commit all changes with a message
89
+ # repo.commit_all('Update everything')
90
+ #
91
+ # @param message [String, nil] the commit message; pass `nil` to omit
92
+ # (e.g. when using `:amend` to reuse the previous message)
93
+ #
94
+ # @param opts [Hash] additional options forwarded to {#commit}
95
+ #
96
+ # @option opts [Boolean, nil] :all (nil) ignored because this method
97
+ # always commits with `all: true`
98
+ #
99
+ # @option opts [Boolean, nil] :amend (nil) replace the tip of the current
100
+ # branch with a new commit
101
+ #
102
+ # @option opts [Boolean, nil] :allow_empty (nil) allow committing with no
103
+ # changes
104
+ #
105
+ # @option opts [Boolean, nil] :allow_empty_message (nil) allow committing
106
+ # with an empty message
107
+ #
108
+ # @option opts [String] :author (nil) override the commit author in
109
+ # `A U Thor <author@example.com>` format
110
+ #
111
+ # @option opts [String] :date (nil) override the author date
112
+ #
113
+ # @option opts [Boolean, String, nil] :gpg_sign (nil) GPG-sign the commit
114
+ #
115
+ # @option opts [Boolean, nil] :no_gpg_sign (nil) disable GPG signing
116
+ #
117
+ # @option opts [Boolean, nil] :no_verify (nil) bypass the pre-commit and
118
+ # commit-msg hooks
119
+ #
120
+ # @return [String] git's stdout from the commit
121
+ #
122
+ # @raise [ArgumentError] when unsupported options are provided
123
+ #
124
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
125
+ #
126
+ def commit_all(message, opts = {})
127
+ commit(message, opts.merge(all: true))
128
+ end
129
+
130
+ # Create a commit object from a tree SHA without moving HEAD
131
+ #
132
+ # Unlike {#commit}, this does not read the index; it directly wraps
133
+ # `git commit-tree`.
134
+ #
135
+ # @example Commit a tree with a parent
136
+ # repo.commit_tree('deadbeef', message: 'snapshot', parent: 'HEAD')
137
+ #
138
+ # @param tree [String, nil] the tree SHA to commit; defaults to `nil`
139
+ #
140
+ # @param opts [Hash] options for the commit-tree command
141
+ #
142
+ # @option opts [String, Array<String>] :m (nil) the commit message
143
+ # paragraph(s) (short form)
144
+ #
145
+ # @option opts [String, Array<String>] :message (nil) the commit message
146
+ # paragraph(s) (normalized to `:m` before passing to the command)
147
+ #
148
+ # @option opts [String, Array<String>] :p (nil) parent commit SHA(s)
149
+ #
150
+ # @option opts [String] :parent (nil) a single parent commit SHA
151
+ # (normalized to `:p`)
152
+ #
153
+ # @option opts [Array<String>] :parents (nil) multiple parent commit
154
+ # SHAs (normalized to `:p`)
155
+ #
156
+ # @return [String] the SHA of the newly created commit object
157
+ #
158
+ # @raise [ArgumentError] when unsupported options are provided
159
+ #
160
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
161
+ #
162
+ def commit_tree(tree = nil, opts = {}) # rubocop:disable Metrics/AbcSize
163
+ SharedPrivate.assert_valid_opts!(COMMIT_TREE_ALLOWED_OPTS, **opts)
164
+
165
+ opts = opts.dup
166
+ opts[:p] = opts.delete(:parents) if opts.key?(:parents)
167
+ opts[:p] = opts.delete(:parent) if opts.key?(:parent)
168
+ opts[:m] = opts.delete(:message) if opts.key?(:message)
169
+ opts[:m] = "commit tree #{tree}" unless opts[:m]
170
+
171
+ Git::Commands::CommitTree.new(@execution_context).call(tree, **opts).stdout
172
+ end
173
+
174
+ # Write the current index to a tree object in the object store
175
+ #
176
+ # @example Get the tree SHA of the current index
177
+ # tree_sha = repo.write_tree
178
+ #
179
+ # @return [String] the SHA of the tree object written
180
+ #
181
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
182
+ #
183
+ def write_tree
184
+ Git::Commands::WriteTree.new(@execution_context).call.stdout
185
+ end
186
+
187
+ # Write the current index to a tree object and immediately commit it
188
+ #
189
+ # Combines {#write_tree} and {#commit_tree} in a single call.
190
+ #
191
+ # @example Commit the current index as a snapshot
192
+ # commit_sha = repo.write_and_commit_tree(message: 'snapshot')
193
+ #
194
+ # @param opts [Hash] options forwarded to {#commit_tree}
195
+ #
196
+ # @option opts [String, Array<String>] :m (nil) the commit message
197
+ # paragraph(s) (short form)
198
+ #
199
+ # @option opts [String, Array<String>] :message (nil) the commit message
200
+ # paragraph(s) (normalized to `:m` before passing to the command)
201
+ #
202
+ # @option opts [String, Array<String>] :p (nil) parent commit SHA(s)
203
+ #
204
+ # @option opts [String] :parent (nil) a single parent commit SHA
205
+ # (normalized to `:p`)
206
+ #
207
+ # @option opts [Array<String>] :parents (nil) multiple parent commit
208
+ # SHAs (normalized to `:p`)
209
+ #
210
+ # @return [String] the SHA of the newly created commit object
211
+ #
212
+ # @raise [ArgumentError] when unsupported options are provided
213
+ #
214
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
215
+ #
216
+ def write_and_commit_tree(opts = {})
217
+ commit_tree(write_tree, opts)
218
+ end
219
+ end
220
+ end
221
+ end
@@ -0,0 +1,454 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'fileutils'
4
+ require 'pathname'
5
+ require 'tmpdir'
6
+ require 'git/execution_context/repository'
7
+ require 'git/system_call_guard'
8
+
9
+ module Git
10
+ class Repository
11
+ # Facade methods for block-based directory and index context helpers
12
+ #
13
+ # The `with_*` helpers build a second {Git::Repository} bound to a different
14
+ # index file or working directory, yield it, and leave the receiver bound to
15
+ # its original index and working directory. Nothing on the receiver changes,
16
+ # so nothing on it is restored when the block exits. The working directory
17
+ # variants change the process working directory for the duration of the
18
+ # block and change it back afterward. The temporary variants remove the
19
+ # scratch directory they created, even if the block raises an exception.
20
+ #
21
+ # The second repository is built with `self.class.new(execution_context:)`,
22
+ # so a subclass of {Git::Repository} must accept that constructor call for
23
+ # the helpers to yield an instance of the subclass.
24
+ #
25
+ # Each `with_*` helper requires a block that declares a positional parameter
26
+ # for the yielded repository and raises `ArgumentError` otherwise. A block with no
27
+ # positional parameter is the v5.x form, which relied on the receiver being
28
+ # rebound; failing fast keeps that form from running against the original
29
+ # index or working directory.
30
+ #
31
+ # {#set_index} and {#set_working} are deprecated and warn on every call
32
+ # through {Git::Deprecation}; UPGRADING.md explains why and shows the
33
+ # replacements.
34
+ #
35
+ # Included by {Git::Repository}.
36
+ #
37
+ # @api private
38
+ #
39
+ module ContextHelpers
40
+ # Parameter types from `Proc#parameters` that receive a positional argument
41
+ CONTEXT_HELPERS_POSITIONAL_PARAMETERS = %i[req opt rest].freeze
42
+ private_constant :CONTEXT_HELPERS_POSITIONAL_PARAMETERS
43
+
44
+ # Deprecation message for {#set_index}
45
+ SET_INDEX_DEPRECATION = 'Git::Repository#set_index is deprecated and will be removed in a future major ' \
46
+ 'release. Open a repository bound to the index instead: ' \
47
+ 'Git.open(dir, index: path) or Git.bare(git_dir, index: path).'
48
+ private_constant :SET_INDEX_DEPRECATION
49
+
50
+ # Deprecation message for {#set_working}
51
+ SET_WORKING_DEPRECATION = 'Git::Repository#set_working is deprecated and will be removed in a future major ' \
52
+ 'release. Open a repository bound to the working tree instead: ' \
53
+ 'Git.open(work_dir, repository: git_dir).'
54
+ private_constant :SET_WORKING_DEPRECATION
55
+
56
+ # Changes the current working directory to the repository working directory
57
+ # for the duration of the block
58
+ #
59
+ # @example Write a file inside the repository working directory
60
+ # repo.chdir do |dir|
61
+ # File.write('hello.txt', 'Hello, world!')
62
+ # repo.add('hello.txt')
63
+ # end
64
+ #
65
+ # @return [Object] the value returned by the block
66
+ #
67
+ # @raise [ArgumentError] if the repository has no working directory (bare
68
+ # repository)
69
+ #
70
+ # @raise [Git::Error] if the working directory cannot be entered
71
+ #
72
+ # @yield [dir] the repository working directory
73
+ #
74
+ # @yieldparam dir [Pathname] the working directory path
75
+ #
76
+ # @yieldreturn [Object] returned as the method's return value
77
+ #
78
+ def chdir
79
+ raise ArgumentError, 'cannot chdir: repository has no working directory (bare repository)' if dir.nil?
80
+
81
+ context_helpers_chdir(dir.to_s) { yield dir }
82
+ end
83
+
84
+ # Yields a repository bound to `new_index` in place of the receiver's index
85
+ #
86
+ # Yields a second repository bound to `new_index`; its working directory
87
+ # and git directory are the receiver's. The receiver is not changed, so
88
+ # calls on it inside the block still use the original index.
89
+ #
90
+ # @example Read a tree into a custom index
91
+ # repo.with_index('/tmp/custom.index') do |indexed|
92
+ # indexed.read_tree('HEAD')
93
+ # end
94
+ #
95
+ # @param new_index [String, Pathname] path to the replacement index file
96
+ #
97
+ # @return [Object] the value returned by the block
98
+ #
99
+ # @raise [ArgumentError] if no block is given or the block declares no
100
+ # positional parameter
101
+ #
102
+ # @raise [Git::Error] if `new_index` cannot be expanded to an absolute path
103
+ #
104
+ # @yield [repo] the repository bound to `new_index`
105
+ #
106
+ # @yieldparam repo [Git::Repository] a new repository of the receiver's
107
+ # class bound to `new_index`
108
+ #
109
+ # @yieldreturn [Object] returned as the method's return value
110
+ #
111
+ def with_index(new_index, &block)
112
+ context_helpers_require_repository_block(block)
113
+ new_path = context_helpers_validate_path(new_index, false)
114
+ yield context_helpers_derived_repository(git_index_file: new_path.to_s)
115
+ end
116
+
117
+ # Yields a repository bound to a new temporary index file, then removes
118
+ # the file
119
+ #
120
+ # The temporary index file does not exist until git creates it on first
121
+ # write. A unique temporary directory is created to hold the index path,
122
+ # avoiding the risk of presenting an empty file to git (which git would
123
+ # reject as a corrupt index). The directory, and any files inside it, are
124
+ # removed unconditionally after the block exits, even if the block raises
125
+ # an exception. The yielded repository is bound as {#with_index} binds it.
126
+ #
127
+ # @example Write a tree from a temporary index
128
+ # tree_sha = repo.with_temp_index do |indexed|
129
+ # indexed.read_tree('HEAD')
130
+ # indexed.add('generated.txt')
131
+ # indexed.write_tree
132
+ # end
133
+ #
134
+ # @return [Object] the value returned by the block
135
+ #
136
+ # @raise [ArgumentError] if no block is given or the block declares no
137
+ # positional parameter
138
+ #
139
+ # @raise [Git::Error] if the temporary directory cannot be created
140
+ #
141
+ # @yield [repo] the repository bound to the temporary index
142
+ #
143
+ # @yieldparam repo [Git::Repository] a new repository of the receiver's
144
+ # class bound to an index file inside the temporary directory
145
+ #
146
+ # @yieldreturn [Object] returned as the method's return value
147
+ #
148
+ # @note The yielded repository stays bound to the temporary index path
149
+ # after the directory that held it is removed. Do not let it, or an
150
+ # object that holds it and later runs commands against the index,
151
+ # escape the block. Git treats the missing index file, even with its
152
+ # directory gone, as an empty index, so reads such as {Git::Repository::StatusOperations#ls_files}
153
+ # return nothing and {Git::Repository::StatusOperations#status_info}
154
+ # reports every tracked file both as deleted and as untracked; writes
155
+ # such as {Git::Repository::Staging#add} raise {Git::Error}. Reads from
156
+ # the object database, such as {Git::Object::AbstractObject#contents},
157
+ # still work.
158
+ #
159
+ def with_temp_index(&block)
160
+ context_helpers_require_repository_block(block)
161
+ # Use a unique temp directory so the index file path is collision-free
162
+ # and does not exist until git writes it. An existing empty file would
163
+ # be treated as a corrupt index by git.
164
+ temp_dir = context_helpers_mktmpdir('git-temp-index-')
165
+ begin
166
+ with_index(File.join(temp_dir, 'index'), &block)
167
+ ensure
168
+ FileUtils.remove_entry(temp_dir, true)
169
+ end
170
+ end
171
+
172
+ # Yields a repository bound to `work_dir` in place of the receiver's
173
+ # working directory
174
+ #
175
+ # Yields a second repository bound to `work_dir`. It shares the
176
+ # receiver's index and git directory, so staging through it changes what
177
+ # the receiver sees as staged. The process working directory is changed
178
+ # to `work_dir` via `Dir.chdir` for the duration of the block and changed
179
+ # back afterward. The receiver is not changed, so calls on it inside the
180
+ # block still use the original working directory.
181
+ #
182
+ # `Dir.chdir` is process-global, so this method is not safe to call from
183
+ # more than one thread at a time.
184
+ #
185
+ # @example Commit changes from a different worktree path
186
+ # repo.with_working('/path/to/worktree') do |worktree|
187
+ # worktree.add('.')
188
+ # worktree.commit('chore: automated update')
189
+ # end
190
+ #
191
+ # @param work_dir [String, Pathname] path to the replacement working
192
+ # directory
193
+ #
194
+ # @return [Object] the value returned by the block
195
+ #
196
+ # @raise [ArgumentError] if `work_dir` does not exist on disk, if no block
197
+ # is given, or if the block declares no positional parameter
198
+ #
199
+ # @raise [Git::Error] if `work_dir` cannot be expanded to an absolute path
200
+ # or cannot be entered
201
+ #
202
+ # @yield [repo] the repository bound to `work_dir`
203
+ #
204
+ # @yieldparam repo [Git::Repository] a new repository of the receiver's
205
+ # class bound to `work_dir`
206
+ #
207
+ # @yieldreturn [Object] returned as the method's return value
208
+ #
209
+ def with_working(work_dir, &block)
210
+ context_helpers_require_repository_block(block)
211
+ new_path = context_helpers_validate_path(work_dir, true)
212
+ repo = context_helpers_derived_repository(git_work_dir: new_path.to_s)
213
+ context_helpers_chdir(new_path.to_s) { yield repo }
214
+ end
215
+
216
+ # Yields a repository bound to a new temporary working directory, then
217
+ # removes the directory and its contents
218
+ #
219
+ # The process working directory is changed to the temporary directory for
220
+ # the duration of the block, as {#with_working} does, so this method is
221
+ # not safe to call from more than one thread at a time. The directory is
222
+ # removed unconditionally after the block exits, even if the block raises
223
+ # an exception. The yielded repository is bound as {#with_working} binds
224
+ # it.
225
+ #
226
+ # @example Write files in an isolated temporary working directory
227
+ # repo.with_temp_working do |scratch|
228
+ # File.write('scratch.txt', 'temporary content')
229
+ # scratch.untracked_files #=> ["scratch.txt"]
230
+ # end
231
+ #
232
+ # @return [Object] the value returned by the block
233
+ #
234
+ # @raise [ArgumentError] if no block is given or the block declares no
235
+ # positional parameter
236
+ #
237
+ # @raise [Git::Error] if the temporary directory cannot be created or
238
+ # removed
239
+ #
240
+ # @yield [repo] the repository bound to the temporary working directory
241
+ #
242
+ # @yieldparam repo [Git::Repository] a new repository of the receiver's
243
+ # class bound to the temporary directory
244
+ #
245
+ # @yieldreturn [Object] returned as the method's return value
246
+ #
247
+ # @note The yielded repository stays bound to the temporary working
248
+ # directory after it is removed. Do not let it, or an object that holds
249
+ # it and later runs commands against the working tree, escape the
250
+ # block: calls that read or write the working tree then raise
251
+ # {Git::Error}. Reads from the object database, such as
252
+ # {Git::Object::AbstractObject#contents}, still work.
253
+ #
254
+ def with_temp_working(&block)
255
+ context_helpers_require_repository_block(block)
256
+ Git::SystemCallGuard.call('Failed to create or remove a temporary directory') do |guard|
257
+ Dir.mktmpdir('temp-workdir') { |temp_dir| guard.unguarded { with_working(temp_dir, &block) } }
258
+ end
259
+ end
260
+
261
+ # Sets the git index to `index_file` and rebuilds the execution context
262
+ #
263
+ # By default raises if `index_file` does not exist. Pass `must_exist:
264
+ # false` to skip the existence check (useful when the index will be
265
+ # created by git later).
266
+ #
267
+ # Every call warns through {Git::Deprecation}; see {ContextHelpers}.
268
+ #
269
+ # @example Set the index to a custom path
270
+ # repo.set_index('/path/to/custom.index')
271
+ #
272
+ # @example Open a repository bound to the index instead
273
+ # repo = Git.open('/path/to/repo', index: '/path/to/custom.index')
274
+ #
275
+ # @example Open a bare repository bound to the index instead
276
+ # repo = Git.bare('/srv/repo.git', index: '/tmp/scratch.index')
277
+ #
278
+ # @param index_file [String, Pathname] path to the new index file
279
+ #
280
+ # @param must_exist [Boolean] when `true` (the default), raises
281
+ # `ArgumentError` if `index_file` does not exist on disk
282
+ #
283
+ # @return [void]
284
+ #
285
+ # @raise [ArgumentError] if `must_exist: true` (the default) and
286
+ # `index_file` does not exist
287
+ #
288
+ # @deprecated Use `Git.open(dir, index: path)` or
289
+ # `Git.bare(git_dir, index: path)` to open a repository bound to the
290
+ # index, or {#with_index} to bind a copy for the duration of a block.
291
+ # Will be removed in a future major release.
292
+ #
293
+ def set_index(index_file, must_exist: true)
294
+ Git::Deprecation.warn(SET_INDEX_DEPRECATION)
295
+ new_path = context_helpers_validate_path(index_file, must_exist)
296
+ @execution_context = @execution_context.dup_with(git_index_file: new_path.to_s)
297
+ nil
298
+ end
299
+
300
+ # Sets the git working directory to `work_dir` and rebuilds the execution
301
+ # context
302
+ #
303
+ # By default raises if `work_dir` does not exist. Pass `must_exist:
304
+ # false` to skip the existence check.
305
+ #
306
+ # Every call warns through {Git::Deprecation}; see {ContextHelpers}.
307
+ #
308
+ # `set_working` keeps the receiver's index. `Git.open` with `:repository`
309
+ # alone resolves the index to `<git_dir>/index`, so pass `:index` as well
310
+ # whenever the receiver's index was custom.
311
+ #
312
+ # @example Set the working directory to a custom path
313
+ # repo.set_working('/path/to/working')
314
+ #
315
+ # @example Open a repository bound to the working tree instead
316
+ # repo = Git.open('/path/to/working', repository: '/path/to/repo/.git')
317
+ #
318
+ # @example Open a repository bound to the working tree and a custom index
319
+ # repo = Git.open('/path/to/working', repository: '/path/to/repo/.git',
320
+ # index: '/path/to/custom.index')
321
+ #
322
+ # @param work_dir [String, Pathname] path to the new working directory
323
+ #
324
+ # @param must_exist [Boolean] when `true` (the default), raises
325
+ # `ArgumentError` if `work_dir` does not exist on disk
326
+ #
327
+ # @return [void]
328
+ #
329
+ # @raise [ArgumentError] if `must_exist: true` (the default) and
330
+ # `work_dir` does not exist
331
+ #
332
+ # @deprecated Use `Git.open(work_dir, repository: git_dir)` to open a
333
+ # repository bound to the working tree, adding `index:` when the
334
+ # receiver's index was custom, or {#with_working} to bind a copy for
335
+ # the duration of a block. Will be removed in a future major release.
336
+ #
337
+ def set_working(work_dir, must_exist: true)
338
+ Git::Deprecation.warn(SET_WORKING_DEPRECATION)
339
+ new_path = context_helpers_validate_path(work_dir, must_exist)
340
+ @execution_context = @execution_context.dup_with(git_work_dir: new_path.to_s)
341
+ nil
342
+ end
343
+
344
+ private
345
+
346
+ # Runs the block with the process working directory set to `path`
347
+ #
348
+ # A `SystemCallError` from entering or leaving `path` is raised as
349
+ # {Git::Error}. A `SystemCallError` raised by the block propagates
350
+ # unchanged.
351
+ #
352
+ # The message does not name a directory because `Dir.chdir` fails on
353
+ # either leg: entering `path`, or restoring the previous directory
354
+ # afterward. The underlying `SystemCallError` names the directory that
355
+ # actually failed.
356
+ #
357
+ # @param path [String] the directory to enter
358
+ #
359
+ # @return [Object] the value returned by the block
360
+ #
361
+ # @raise [Git::Error] if `path` cannot be entered
362
+ #
363
+ # @yield the code to run inside `path`
364
+ #
365
+ # @yieldreturn [Object] returned as the method's return value
366
+ #
367
+ # @api private
368
+ #
369
+ def context_helpers_chdir(path, &block)
370
+ Git::SystemCallGuard.call('Failed to change directory') do |guard|
371
+ Dir.chdir(path) { guard.unguarded(&block) }
372
+ end
373
+ end
374
+
375
+ # Raises unless `block` declares a positional parameter for the yielded
376
+ # repository
377
+ #
378
+ # A block with no positional parameter is the v5.x form that relied on
379
+ # the receiver being rebound; it fails fast rather than running against
380
+ # the original index or working directory. The check reads the block's
381
+ # parameter list rather than its arity because an optional parameter
382
+ # (`|repo = nil|`) gives a proc an arity of zero although it receives the
383
+ # repository, while keyword and block parameters cannot receive it.
384
+ #
385
+ # @param block [Proc, nil] the block passed to a `with_*` helper
386
+ #
387
+ # @return [void]
388
+ #
389
+ # @raise [ArgumentError] if `block` is nil or declares no positional
390
+ # parameter
391
+ #
392
+ # @api private
393
+ #
394
+ def context_helpers_require_repository_block(block)
395
+ return if block&.parameters&.any? { |type, _name| CONTEXT_HELPERS_POSITIONAL_PARAMETERS.include?(type) }
396
+
397
+ raise ArgumentError, 'a block that accepts the yielded repository is required'
398
+ end
399
+
400
+ # Creates a temporary directory, raising {Git::Error} on failure
401
+ #
402
+ # @param prefix [String] the directory name prefix
403
+ #
404
+ # @return [String] the path of the new directory
405
+ #
406
+ # @raise [Git::Error] if the directory cannot be created
407
+ #
408
+ # @api private
409
+ #
410
+ def context_helpers_mktmpdir(prefix)
411
+ Git::SystemCallGuard.call('Failed to create a temporary directory') { Dir.mktmpdir(prefix) }
412
+ end
413
+
414
+ # Expands `path` and validates existence when required
415
+ #
416
+ # @param path [String, Pathname] path to normalize and validate
417
+ #
418
+ # @param must_exist [Boolean] whether the expanded path must already exist
419
+ #
420
+ # @return [Pathname] the expanded absolute path
421
+ #
422
+ # @raise [ArgumentError] if `must_exist` is `true` and the path does not exist
423
+ #
424
+ # @raise [Git::Error] if the path cannot be expanded, which happens when
425
+ # `path` is relative and the process working directory has been removed
426
+ #
427
+ def context_helpers_validate_path(path, must_exist)
428
+ expanded = Git::SystemCallGuard.call('Failed to expand the path') { File.expand_path(path.to_s) }
429
+
430
+ Pathname.new(expanded).tap do |expanded_path|
431
+ raise ArgumentError, "path does not exist: #{expanded_path}" if must_exist && !expanded_path.exist?
432
+ end
433
+ end
434
+
435
+ # Builds a repository of the receiver's class bound to a copy of this
436
+ # execution context with selected overrides, leaving the receiver untouched
437
+ #
438
+ # @param overrides [Hash] execution-context attributes to override
439
+ #
440
+ # @option overrides [String, nil] :git_index_file replacement index file path
441
+ #
442
+ # @option overrides [String, nil] :git_work_dir replacement working directory
443
+ # path
444
+ #
445
+ # @return [Git::Repository] a new repository built from the derived context
446
+ #
447
+ # @api private
448
+ #
449
+ def context_helpers_derived_repository(**overrides)
450
+ self.class.new(execution_context: @execution_context.dup_with(**overrides))
451
+ end
452
+ end
453
+ end
454
+ end