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,1334 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'fileutils'
4
+ require 'git/commands/archive'
5
+ require 'git/object'
6
+ require 'git/commands/cat_file/raw'
7
+ require 'git/commands/grep'
8
+ require 'git/commands/ls_tree'
9
+ require 'git/commands/name_rev'
10
+ require 'git/commands/rev_parse'
11
+ require 'git/commands/show_ref/list'
12
+ require 'git/commands/tag/create'
13
+ require 'git/commands/tag/delete'
14
+ require 'git/commands/tag/list'
15
+ require 'git/parsers/cat_file'
16
+ require 'git/parsers/grep'
17
+ require 'git/parsers/ls_tree'
18
+ require 'git/parsers/tag'
19
+ require 'git/repository/shared_private'
20
+ require 'git/system_call_guard'
21
+ require 'git/escaped_path'
22
+ require 'tempfile'
23
+ require 'zlib'
24
+
25
+ module Git
26
+ class Repository
27
+ # Facade methods for raw git object store queries
28
+ #
29
+ # Included by {Git::Repository}.
30
+ #
31
+ # @api private
32
+ #
33
+ module ObjectOperations # rubocop:disable Metrics/ModuleLength
34
+ # Returns the raw content of a git object, or streams it into a tempfile
35
+ #
36
+ # Without a block, the full content is buffered in memory and returned as a
37
+ # `String`. With a block, git output is streamed directly to disk without
38
+ # memory buffering — safe for large blobs.
39
+ #
40
+ # @overload cat_file_contents(object)
41
+ # Returns the object's raw content as a string
42
+ #
43
+ # @example Get the contents of a blob
44
+ # repo.cat_file_contents('HEAD:README.md') # => "This is a README file\n"
45
+ #
46
+ # @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
47
+ #
48
+ # @return [String] the raw content of the object
49
+ #
50
+ # @overload cat_file_contents(object, &block)
51
+ # Streams the object's raw content to a temporary file and yields it
52
+ #
53
+ # Git output is written directly to a file on disk without being buffered in
54
+ # memory first, then the file is rewound and yielded to the block. The return
55
+ # value is whatever the block returns.
56
+ #
57
+ # @example Read a large blob without buffering it in memory
58
+ # repo.cat_file_contents('HEAD:large_file.bin') { |f| process(f) }
59
+ #
60
+ # @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
61
+ #
62
+ # @yield [file] the temporary file containing the streamed content,
63
+ # positioned at the start
64
+ #
65
+ # @yieldparam file [File] readable `IO` object positioned at the beginning
66
+ # of the content
67
+ #
68
+ # @yieldreturn [Object] the value to return from this method
69
+ #
70
+ # @return [Object] the value returned by the block
71
+ #
72
+ # @raise [ArgumentError] if `object` starts with a hyphen
73
+ #
74
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
75
+ #
76
+ # @raise [Git::Error] if a block is given and the object content cannot be
77
+ # written to a temporary file
78
+ #
79
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
80
+ #
81
+ def cat_file_contents(object, &block)
82
+ raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
83
+
84
+ return Git::Commands::CatFile::Raw.new(@execution_context).call(object, p: true).stdout unless block_given?
85
+
86
+ # Stream git output directly to a tempfile to avoid buffering large
87
+ # object content in memory when a block is given.
88
+ Git::SystemCallGuard.call('Failed to write the object content to a temporary file') do |guard|
89
+ Tempfile.create do |file|
90
+ file.binmode
91
+ Git::Commands::CatFile::Raw.new(@execution_context).call(object, p: true, out: file)
92
+ file.rewind
93
+ guard.unguarded { block.call(file) }
94
+ end
95
+ end
96
+ end
97
+
98
+ # Alias for {#cat_file_contents}; kept as a legacy name and not scheduled
99
+ # for removal
100
+ #
101
+ # @see #cat_file_contents
102
+ alias cat_file cat_file_contents
103
+
104
+ # Returns the size of a git object in bytes
105
+ #
106
+ # @example Get the size of a commit object
107
+ # repo.cat_file_size('HEAD') #=> 265
108
+ #
109
+ # @example Get the size of a blob by treeish path
110
+ # repo.cat_file_size('HEAD:README.md') #=> 14
111
+ #
112
+ # @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
113
+ #
114
+ # @return [Integer] the object size in bytes
115
+ #
116
+ # @raise [ArgumentError] if `object` starts with a hyphen
117
+ #
118
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
119
+ #
120
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
121
+ #
122
+ def cat_file_size(object)
123
+ raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
124
+
125
+ Git::Commands::CatFile::Raw.new(@execution_context).call(object, s: true).stdout.chomp.to_i
126
+ end
127
+
128
+ # Returns the type of a git object
129
+ #
130
+ # @example Get the type of a commit reference
131
+ # repo.cat_file_type('HEAD') #=> "commit"
132
+ #
133
+ # @example Get the type of a blob via treeish path
134
+ # repo.cat_file_type('HEAD:README.md') #=> "blob"
135
+ #
136
+ # @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
137
+ #
138
+ # @return [String] the object type — one of `"blob"`, `"commit"`,
139
+ # `"tag"`, or `"tree"`
140
+ #
141
+ # @raise [ArgumentError] if `object` starts with a hyphen
142
+ #
143
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
144
+ #
145
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
146
+ #
147
+ def cat_file_type(object)
148
+ raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
149
+
150
+ Git::Commands::CatFile::Raw.new(@execution_context).call(object, t: true).stdout.chomp
151
+ end
152
+
153
+ # Returns parsed commit data for the given git object
154
+ #
155
+ # @example Get commit data for HEAD
156
+ # repo.cat_file_commit('HEAD')
157
+ # # => {
158
+ # # 'sha' => 'HEAD',
159
+ # # 'tree' => 'def5678...',
160
+ # # 'parent' => ['ghi9012...'],
161
+ # # 'author' => 'A U Thor <author@example.com> 1234567890 +0000',
162
+ # # 'committer' => 'A U Thor <author@example.com> 1234567890 +0000',
163
+ # # 'message' => "Initial commit\n"
164
+ # # }
165
+ #
166
+ # @param object [String] the object name (SHA, ref, `HEAD`, etc.)
167
+ #
168
+ # @return [Hash] commit data
169
+ #
170
+ # String-keyed hash with the following keys:
171
+ #
172
+ # * `tree` — the tree SHA
173
+ # * `parent` — Array of parent SHAs (empty for the root commit)
174
+ # * `author` — author identity string and timestamp
175
+ # * `committer` — committer identity string and timestamp
176
+ # * `message` — the commit message (includes trailing newline)
177
+ # * `gpgsig` — the cryptographic signature (signed commits only)
178
+ # * `sha` — the `object` argument as passed by the caller
179
+ #
180
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
181
+ #
182
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
183
+ #
184
+ def cat_file_commit(object)
185
+ result = Git::Commands::CatFile::Raw.new(@execution_context).call('commit', object)
186
+ Git::Parsers::CatFile.parse_commit(result.stdout.split("\n"), object)
187
+ end
188
+
189
+ # Returns parsed tag data for the given annotated tag object
190
+ #
191
+ # Does not work with lightweight tags. To list all annotated tags in a
192
+ # repository:
193
+ #
194
+ # ```sh
195
+ # git for-each-ref --format='%(refname:strip=2)' refs/tags | \
196
+ # while read tag; do
197
+ # git cat-file tag "$tag" >/dev/null 2>&1 && echo "$tag"
198
+ # done
199
+ # ```
200
+ #
201
+ # @example Get tag data for an annotated tag
202
+ # repo.cat_file_tag('v1.0')
203
+ # # => {
204
+ # # 'name' => 'v1.0',
205
+ # # 'object' => 'abc1234...',
206
+ # # 'type' => 'commit',
207
+ # # 'tag' => 'v1.0',
208
+ # # 'tagger' => 'A U Thor <author@example.com> 1234567890 +0000',
209
+ # # 'message' => "Release v1.0\n"
210
+ # # }
211
+ #
212
+ # @param object [String] the annotated tag name or SHA
213
+ #
214
+ # @return [Hash] tag data
215
+ #
216
+ # String-keyed hash with the following keys:
217
+ #
218
+ # * `name` — the `object` argument as passed by the caller
219
+ # * `object` — the SHA of the tagged object
220
+ # * `type` — the type of the tagged object (usually `"commit"`)
221
+ # * `tag` — the tag name
222
+ # * `tagger` — tagger identity string and timestamp
223
+ # * `message` — the tag message (includes trailing newline)
224
+ #
225
+ # @raise [ArgumentError] if `object` starts with a hyphen
226
+ #
227
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
228
+ #
229
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
230
+ #
231
+ def cat_file_tag(object)
232
+ raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
233
+
234
+ tdata = Git::Commands::CatFile::Raw.new(@execution_context).call('tag', object).stdout.split("\n")
235
+ Git::Parsers::CatFile.parse_tag(tdata, object)
236
+ end
237
+
238
+ # Resolve a revision specifier to its full object ID
239
+ #
240
+ # Passes the given revision specifier to `git rev-parse` and returns the
241
+ # full object ID.
242
+ #
243
+ # @example Resolve HEAD to its full object ID
244
+ # repo.rev_parse('HEAD') #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
245
+ #
246
+ # @example Resolve an abbreviated SHA
247
+ # repo.rev_parse('9b9b31e') #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
248
+ #
249
+ # @example Resolve a tree object via rev-parse syntax
250
+ # repo.rev_parse('HEAD^{tree}') #=> "94c827875e2cadb8bc8d4cdd900f19aa9e8634c7"
251
+ #
252
+ # @param objectish [String] the revision specifier to resolve (branch name,
253
+ # tag, abbreviated SHA, refspec, etc.)
254
+ #
255
+ # @return [String] the full object ID of the resolved object
256
+ #
257
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
258
+ #
259
+ # @see https://git-scm.com/docs/git-rev-parse git-rev-parse documentation
260
+ #
261
+ # @see https://git-scm.com/docs/git-rev-parse#_specifying_revisions Valid ways to specify revisions
262
+ #
263
+ def rev_parse(objectish)
264
+ Git::Commands::RevParse.new(@execution_context).call(objectish, '--', revs_only: true).stdout
265
+ end
266
+
267
+ # Returns the SHA of a named tag
268
+ #
269
+ # Returns an empty string when the tag does not exist.
270
+ #
271
+ # Reads the loose ref file under `refs/tags` directly when it exists and
272
+ # falls back to `git show-ref` otherwise, including when the file cannot
273
+ # be read.
274
+ #
275
+ # @example Get the SHA of an existing tag
276
+ # repo.tag_sha('v1.0')
277
+ # #=> "abc1234567890abcdef1234567890abcdef123456"
278
+ #
279
+ # @example Get the SHA of a non-existent tag
280
+ # repo.tag_sha('nonexistent') #=> ""
281
+ #
282
+ # @param tag_name [String] the tag name to look up
283
+ #
284
+ # @return [String] the SHA of the named tag, or an empty string if the
285
+ # tag does not exist
286
+ #
287
+ # @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
288
+ #
289
+ def tag_sha(tag_name)
290
+ tags_dir = File.expand_path(File.join(@execution_context.git_dir, 'refs', 'tags'))
291
+ head = File.expand_path(File.join(tags_dir, tag_name))
292
+ Private.loose_tag_sha(tags_dir, head) || Private.show_ref_tag_sha(@execution_context, tag_name)
293
+ end
294
+
295
+ # Returns all recursive entries for a given tree object
296
+ #
297
+ # Equivalent to running `git ls-tree -r <objectish>` and splitting the
298
+ # output on newlines. Each returned line describes a single entry in the
299
+ # tree in the format produced by `git ls-tree`: `<mode> <type> <object>\t<file>`.
300
+ #
301
+ # @example List all files in the tree rooted at HEAD
302
+ # repo.full_tree('HEAD^{tree}')
303
+ # # => [
304
+ # # "100644 blob e69de29bb2d1d6434b8b29ae775ad8c2e48c5391\tex_dir/ex.txt",
305
+ # # "100644 blob abc1234...\tlib/git.rb"
306
+ # # ]
307
+ #
308
+ # @param objectish [String] the tree SHA or tree-ish specifier to recurse
309
+ # into
310
+ #
311
+ # @return [Array<String>] one entry per path, in the format
312
+ # `<mode> <type> <object>\t<file>`
313
+ #
314
+ # Returns an empty array for an empty tree.
315
+ #
316
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
317
+ #
318
+ # @see https://git-scm.com/docs/git-ls-tree git-ls-tree documentation
319
+ #
320
+ def full_tree(objectish)
321
+ Git::Commands::LsTree.new(@execution_context).call(objectish, r: true).stdout.split("\n")
322
+ end
323
+
324
+ # Returns the number of entries in a tree
325
+ #
326
+ # Runs `git ls-tree -r <objectish>` and counts output lines.
327
+ # This matches `Git::Lib#tree_depth` behavior in the 4.x branch.
328
+ #
329
+ # @example Count entries in the tree rooted at HEAD
330
+ # repo.tree_depth('HEAD^{tree}') #=> 42
331
+ #
332
+ # @param objectish [String] the tree SHA or tree-ish specifier to recurse
333
+ # into
334
+ #
335
+ # @return [Integer] the number of entries in the recursive tree listing
336
+ #
337
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
338
+ #
339
+ # @see https://git-scm.com/docs/git-ls-tree git-ls-tree documentation
340
+ #
341
+ def tree_depth(objectish)
342
+ Git::Commands::LsTree.new(@execution_context).call(objectish, r: true).stdout.each_line.count
343
+ end
344
+
345
+ # Find the first symbolic name for a commit-ish
346
+ #
347
+ # @example Find the symbolic name for a commit
348
+ # repo.name_rev('abc123') #=> "main~5"
349
+ #
350
+ # @example Find the symbolic name for HEAD
351
+ # repo.name_rev('HEAD') #=> "main"
352
+ #
353
+ # @param commit_ish [String] the commit-ish to find the symbolic name of
354
+ #
355
+ # @return [String, nil] the first symbolic name, or nil if stdout contains
356
+ # fewer than two words
357
+ #
358
+ # @raise [ArgumentError] if commit_ish starts with a hyphen
359
+ #
360
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
361
+ #
362
+ # @see https://git-scm.com/docs/git-name-rev git-name-rev documentation
363
+ #
364
+ def name_rev(commit_ish)
365
+ raise ArgumentError, "Invalid commit_ish: '#{commit_ish}'" if commit_ish&.start_with?('-')
366
+
367
+ Git::Commands::NameRev.new(@execution_context).call(commit_ish).stdout.split[1]
368
+ end
369
+
370
+ # Option keys accepted by {#ls_tree}
371
+ LS_TREE_ALLOWED_OPTS = %i[recursive path].freeze
372
+ private_constant :LS_TREE_ALLOWED_OPTS
373
+
374
+ # List the objects in a git tree
375
+ #
376
+ # Runs `git ls-tree` against the given sha and returns a Hash of tree
377
+ # entries organised by object type.
378
+ #
379
+ # @example List the top-level tree
380
+ # repo.ls_tree('HEAD')
381
+ # # => { 'blob' => { 'README.md' => { mode: '100644', sha: 'abc...' } },
382
+ # # 'tree' => { 'lib' => { mode: '040000', sha: 'def...' } },
383
+ # # 'commit' => {} }
384
+ #
385
+ # @example List the tree recursively
386
+ # repo.ls_tree('HEAD', recursive: true)
387
+ # # => { 'blob' => { 'lib/git.rb' => { mode: '100644', sha: '...' } }, ... }
388
+ #
389
+ # @example Limit the listing to a path
390
+ # repo.ls_tree('HEAD', path: 'lib/')
391
+ #
392
+ # @param objectish [String] the tree-ish object to list
393
+ #
394
+ # @param opts [Hash] additional options
395
+ #
396
+ # @option opts [Boolean, nil] :recursive (nil) recurse into subtrees
397
+ #
398
+ # @option opts [String, Array<String>] :path (nil) path or array of paths
399
+ # to limit the listing to
400
+ #
401
+ # @return [Hash<String, Hash<String, Hash>>] a three-level Hash keyed by
402
+ # object type (`'blob'`, `'tree'`, `'commit'`), then by filename, then
403
+ # holding `:mode` and `:sha` values
404
+ #
405
+ # @raise [ArgumentError] when unsupported options are provided
406
+ #
407
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
408
+ #
409
+ # @see https://git-scm.com/docs/git-ls-tree git-ls-tree documentation
410
+ #
411
+ def ls_tree(objectish, opts = {})
412
+ SharedPrivate.assert_valid_opts!(LS_TREE_ALLOWED_OPTS, **opts)
413
+ paths = Array(opts[:path]).compact
414
+ r_value = opts[:recursive]
415
+ safe_options = {}
416
+ safe_options[:r] = r_value unless r_value.nil?
417
+ result = Git::Commands::LsTree.new(@execution_context).call(objectish, *paths, **safe_options)
418
+ Git::Parsers::LsTree.parse(result.stdout)
419
+ end
420
+
421
+ # Option keys accepted by {#grep}
422
+ GREP_ALLOWED_OPTS = %i[ignore_case i invert_match v extended_regexp E perl_regexp P object].freeze
423
+ private_constant :GREP_ALLOWED_OPTS
424
+
425
+ # Search tracked file contents in a git tree for a pattern
426
+ #
427
+ # Runs `git grep` against the given tree-ish and returns every match as a
428
+ # filename-keyed hash of `[line_number, text]` pairs.
429
+ #
430
+ # @example Search HEAD for a pattern
431
+ # repo.grep('TODO')
432
+ # # => { "HEAD:src/foo.rb" => [[12, "# TODO: fix this"]], ... }
433
+ #
434
+ # @example Limit the search to a path
435
+ # repo.grep('TODO', 'src/')
436
+ #
437
+ # @example Search a specific commit
438
+ # repo.grep('TODO', nil, object: 'abc1234')
439
+ #
440
+ # @example Case-insensitive search
441
+ # repo.grep('todo', nil, ignore_case: true)
442
+ #
443
+ # @example Match a metacharacter against a non-ASCII character on Git for Windows
444
+ # repo.grep('^.PFEL', nil, perl_regexp: true)
445
+ #
446
+ # @param pattern [String] the pattern to search for
447
+ #
448
+ # @param path_limiter [String, Pathname, Array<String, Pathname>, nil]
449
+ # a path or array of paths to limit the search to, or `nil` for no limit
450
+ #
451
+ # @param opts [Hash] additional options for the grep command
452
+ #
453
+ # @option opts [String] :object ('HEAD') the tree-ish to search
454
+ #
455
+ # @option opts [Boolean, nil] :ignore_case (nil) ignore case
456
+ # distinctions in both the pattern and the file contents
457
+ #
458
+ # Alias: :i
459
+ #
460
+ # @option opts [Boolean, nil] :invert_match (nil) select non-matching
461
+ # lines
462
+ #
463
+ # Alias: :v
464
+ #
465
+ # @option opts [Boolean, nil] :extended_regexp (nil) use POSIX extended
466
+ # regular expressions for the pattern
467
+ #
468
+ # Alias: :E
469
+ #
470
+ # @option opts [Boolean, nil] :perl_regexp (nil) use Perl-compatible regular
471
+ # expressions (PCRE) for the pattern
472
+ #
473
+ # Requires a git built with PCRE support; git otherwise fails with
474
+ # "cannot use Perl-compatible regexes...".
475
+ #
476
+ # Alias: :P
477
+ #
478
+ # @return [Hash<String, Array<Array(Integer, String)>>] a hash mapping
479
+ # each `"treeish:filename"` key to an array of `[line_number, text]`
480
+ # pairs; returns an empty hash when no lines match
481
+ #
482
+ # @raise [ArgumentError] if unsupported options are provided
483
+ #
484
+ # @raise [Git::FailedError] if git exits with a non-zero status and
485
+ # stderr is non-empty (e.g. bad object reference)
486
+ #
487
+ # @note On Git for Windows, git's default regex engine matches *bytes* rather
488
+ # than characters, so a metacharacter such as `.` or a POSIX class such as
489
+ # `[[:alpha:]]` never matches a whole multi-byte character. The failure is
490
+ # silent: nothing raises, and the empty hash returned is indistinguishable
491
+ # from a pattern that genuinely does not occur in the tree. Pass
492
+ # `perl_regexp: true` to select PCRE, which does match characters. PCRE is a
493
+ # different dialect than git's default POSIX basic/extended regular
494
+ # expressions, so this is a deliberate choice by the caller rather than a
495
+ # transparent substitution, and it requires a git built with PCRE support.
496
+ #
497
+ # @see https://git-scm.com/docs/git-grep git-grep documentation
498
+ #
499
+ def grep(pattern, path_limiter = nil, opts = {})
500
+ SharedPrivate.assert_valid_opts!(GREP_ALLOWED_OPTS, **opts)
501
+ opts = opts.dup
502
+ object = opts.delete(:object) || 'HEAD'
503
+ opts[:pathspec] = Array(path_limiter).map(&:to_s) if path_limiter
504
+ result = Git::Commands::Grep.new(@execution_context).call(
505
+ object, pattern:, **opts, no_color: true, line_number: true, null: true
506
+ )
507
+ Private.parse_grep_result(result)
508
+ end
509
+
510
+ # Option keys accepted by {#archive}
511
+ ARCHIVE_ALLOWED_OPTS = %i[prefix remote path format add_gzip].freeze
512
+ private_constant :ARCHIVE_ALLOWED_OPTS
513
+
514
+ # Create an archive of the repository tree and write it to a file
515
+ #
516
+ # Writes the archive content to a file and returns the file path. The
517
+ # default format is `zip`. Pass `format: 'tar'` for an uncompressed tar
518
+ # archive, or `format: 'tgz'` for a gzip-compressed tar archive
519
+ # (equivalent to `format: 'tar'` with `add_gzip: true`).
520
+ #
521
+ # When no `file` path is given, a temporary file is created and its path
522
+ # is returned.
523
+ #
524
+ # **File replacement behavior when `file` is given:**
525
+ #
526
+ # The archive is first written to a staging file in the same directory as
527
+ # `file`. This means write permission is required on the parent directory
528
+ # of `file`, not just on `file` itself. Once the archive is fully written,
529
+ # the staging file atomically replaces `file` via rename.
530
+ #
531
+ # If `file` already exists, only its numeric permission bits are applied to
532
+ # the new archive; ownership, ACLs, and extended attributes are not
533
+ # transferred. If `file` does not exist, the archive receives the standard
534
+ # file creation mode (`0666 & ~umask`). On Windows, `File.chmod` has no
535
+ # effect, so the archive always receives the default creation mode
536
+ # regardless of whether `file` already exists.
537
+ #
538
+ # If `file` is a symlink that does not point to a directory, the symlink
539
+ # itself is replaced by the new archive file rather than writing through
540
+ # the link to its target. A symlink that points to a directory is treated
541
+ # as a directory and rejected with `ArgumentError`.
542
+ #
543
+ # @example Archive HEAD as a zip file
544
+ # repo.archive('HEAD', '/tmp/release.zip') #=> "/tmp/release.zip"
545
+ #
546
+ # @example Archive a tag as a tar file
547
+ # repo.archive('v1.0', '/tmp/release.tar', format: 'tar') #=> "/tmp/release.tar"
548
+ #
549
+ # @example Archive with a path prefix applied to every entry
550
+ # repo.archive('HEAD', '/tmp/out.tar', format: 'tar', prefix: 'myproject/')
551
+ # #=> "/tmp/out.tar"
552
+ #
553
+ # @example Archive a subdirectory only
554
+ # repo.archive('HEAD', '/tmp/src.tar', format: 'tar', path: 'src/')
555
+ # #=> "/tmp/src.tar"
556
+ #
557
+ # @param treeish [String] tree-ish to archive — commit SHA, tag, branch
558
+ # name, or tree SHA
559
+ #
560
+ # @param file [String, nil] (nil) destination file path; when `nil`, a
561
+ # unique temporary file is created and its path is returned
562
+ #
563
+ # @param opts [Hash] archive options
564
+ #
565
+ # @option opts [String] :format ('zip') archive format — `'tar'`, `'zip'`,
566
+ # or `'tgz'`; `'tgz'` is internally converted to `'tar'` with gzip
567
+ # post-processing
568
+ #
569
+ # @option opts [String] :prefix (nil) prefix prepended to every filename
570
+ # in the archive; typically ends with `/`
571
+ #
572
+ # @option opts [String] :path (nil) path within the tree to include in the
573
+ # archive; when given, only files under that path are archived
574
+ #
575
+ # @option opts [String] :remote (nil) retrieve the archive from a remote
576
+ # repository rather than the local one
577
+ #
578
+ # @option opts [Boolean, nil] :add_gzip (nil) apply gzip compression after
579
+ # writing the archive; set automatically when `format: 'tgz'` is given
580
+ #
581
+ # @return [String] path to the written archive file
582
+ #
583
+ # @raise [ArgumentError] if unsupported options are provided
584
+ #
585
+ # @raise [ArgumentError] if `file` is an existing directory
586
+ #
587
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
588
+ #
589
+ # @raise [Git::Error] if the archive file cannot be written or gzip
590
+ # compression fails
591
+ #
592
+ # @note A failure leaves nothing behind: the staging and temporary files
593
+ # are removed and an existing `file` is not replaced.
594
+ #
595
+ # @see https://git-scm.com/docs/git-archive git-archive documentation
596
+ #
597
+ def archive(treeish, file = nil, opts = {})
598
+ SharedPrivate.assert_valid_opts!(ARCHIVE_ALLOWED_OPTS, **opts)
599
+ raise ArgumentError, "#{file.inspect} is a directory" if file && File.directory?(file)
600
+
601
+ Git::SystemCallGuard.call('Failed to write the archive') do
602
+ Private.write_archive(@execution_context, treeish, file, opts)
603
+ end
604
+ end
605
+
606
+ # Returns a blob object for the given object reference
607
+ #
608
+ # The returned object is lazy: no git command is invoked until a property
609
+ # (e.g. {Git::Object::AbstractObject#sha}, {Git::Object::AbstractObject#contents})
610
+ # is accessed on the result.
611
+ #
612
+ # @example Get a blob from a treeish path
613
+ # repo.gblob('HEAD:README.md')
614
+ # #=> #<Git::Object::Blob ...>
615
+ #
616
+ # @param objectish [String] the object name (SHA, treeish path, ref, etc.)
617
+ #
618
+ # @return [Git::Object::Blob] the blob object
619
+ #
620
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
621
+ #
622
+ def gblob(objectish)
623
+ Git::Object.new(self, objectish, 'blob')
624
+ end
625
+
626
+ # Returns a commit object for the given object reference
627
+ #
628
+ # The returned object is lazy: no git command is invoked until a property
629
+ # (e.g. {Git::Object::AbstractObject#sha}, {Git::Object::Commit#message})
630
+ # is accessed on the result.
631
+ #
632
+ # @example Get a commit by symbolic ref
633
+ # repo.gcommit('HEAD')
634
+ # #=> #<Git::Object::Commit ...>
635
+ #
636
+ # @example Get a commit by abbreviated SHA
637
+ # repo.gcommit('abc1234')
638
+ # #=> #<Git::Object::Commit ...>
639
+ #
640
+ # @param objectish [String] the object name (SHA, branch, tag, refspec, etc.)
641
+ #
642
+ # @return [Git::Object::Commit] the commit object
643
+ #
644
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
645
+ #
646
+ def gcommit(objectish)
647
+ Git::Object.new(self, objectish, 'commit')
648
+ end
649
+
650
+ # Returns a tree object for the given object reference
651
+ #
652
+ # The returned object is lazy: no git command is invoked until a property
653
+ # (e.g. {Git::Object::AbstractObject#sha}, {Git::Object::Tree#children})
654
+ # is accessed on the result.
655
+ #
656
+ # @example Get the root tree for the current HEAD
657
+ # repo.gtree('HEAD^{tree}')
658
+ # #=> #<Git::Object::Tree ...>
659
+ #
660
+ # @param objectish [String] the object name (SHA, treeish specifier, etc.)
661
+ #
662
+ # @return [Git::Object::Tree] the tree object
663
+ #
664
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
665
+ #
666
+ def gtree(objectish)
667
+ Git::Object.new(self, objectish, 'tree')
668
+ end
669
+
670
+ # Returns the appropriate git object for the given object reference
671
+ #
672
+ # Runs `git cat-file -t` to determine the object type, then constructs
673
+ # and returns the corresponding `Git::Object::*` subclass instance.
674
+ #
675
+ # @example Get a commit object from HEAD
676
+ # repo.object('HEAD')
677
+ # #=> #<Git::Object::Commit ...>
678
+ #
679
+ # @example Get a blob from a treeish path
680
+ # repo.object('HEAD:README.md')
681
+ # #=> #<Git::Object::Blob ...>
682
+ #
683
+ # @param objectish [String] the object name (SHA, ref, treeish path, etc.)
684
+ #
685
+ # @return [Git::Object::Blob, Git::Object::Commit, Git::Object::Tree] the
686
+ # git object for the given reference
687
+ #
688
+ # @raise [ArgumentError] if `objectish` starts with a hyphen
689
+ #
690
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
691
+ #
692
+ # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
693
+ #
694
+ def object(objectish)
695
+ Git::Object.new(self, objectish)
696
+ end
697
+
698
+ # Returns the tags in the repository as structured objects
699
+ #
700
+ # @example List all tags
701
+ # repo.tag_list
702
+ # # => [#<data Git::TagInfo name="v1.0.0", oid=nil, target_oid="abc123...", ...>,
703
+ # # #<data Git::TagInfo name="v2.0.0", oid="def456...", target_oid="789abc...", ...>]
704
+ #
705
+ # @example Look up a single tag by name
706
+ # repo.tag_list('v1.0.0').first
707
+ # # => #<data Git::TagInfo name="v1.0.0", ...>
708
+ #
709
+ # @example Look up a tag that does not exist
710
+ # repo.tag_list('nonexistent').first #=> nil
711
+ #
712
+ # @example Filter using glob patterns
713
+ # repo.tag_list('v1.*', 'v2.*')
714
+ #
715
+ # @example List only annotated tags
716
+ # repo.tag_list.select(&:annotated?)
717
+ #
718
+ # @param patterns [Array<String>] optional shell wildcard patterns passed
719
+ # directly to `git tag --list`; when empty (the default) all tags are
720
+ # returned
721
+ #
722
+ # @return [Array<Git::TagInfo>] parsed tag information for every tag
723
+ # matching the patterns, in the order `git tag --list` reports them
724
+ #
725
+ # Returns an empty array when the repository has no tags or no tag
726
+ # matches the given patterns.
727
+ #
728
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
729
+ #
730
+ # @see https://git-scm.com/docs/git-tag git-tag
731
+ #
732
+ def tag_list(*patterns)
733
+ result = Git::Commands::Tag::List.new(@execution_context).call(
734
+ *patterns, format: Git::Parsers::Tag::FORMAT_STRING
735
+ )
736
+ Git::Parsers::Tag.parse_list(result.stdout)
737
+ end
738
+
739
+ # Option keys accepted by {#tag_create}
740
+ TAG_CREATE_ALLOWED_OPTS = %i[
741
+ annotate a sign s no_sign local_user u force f message m file F
742
+ edit e no_edit trailer cleanup create_reflog
743
+ ].freeze
744
+ private_constant :TAG_CREATE_ALLOWED_OPTS
745
+
746
+ # Create a new tag and return its metadata
747
+ #
748
+ # @overload tag_create(name, options = {})
749
+ #
750
+ # @example Create a lightweight tag on HEAD
751
+ # repo.tag_create('v1.0.0')
752
+ # # => #<data Git::TagInfo name="v1.0.0", oid=nil, target_oid="abc123...", ...>
753
+ #
754
+ # @example Create an annotated tag on HEAD
755
+ # repo.tag_create('v1.0.0', annotate: true, message: 'Release 1.0.0')
756
+ # # => #<data Git::TagInfo name="v1.0.0", oid="def456...", message="Release 1.0.0", ...>
757
+ #
758
+ # @example Replace an existing tag on HEAD
759
+ # repo.tag_create('v1.0.0', force: true)
760
+ #
761
+ # @param name [String] the name of the tag to create
762
+ #
763
+ # @param options [Hash] options for creating the tag
764
+ #
765
+ # @option options [Boolean, nil] :annotate (nil) make an unsigned,
766
+ # annotated tag object; requires `:message` or `:file` (alias: `:a`)
767
+ #
768
+ # @option options [Boolean, nil] :a (nil) alias for `:annotate`
769
+ #
770
+ # @option options [Boolean, nil] :sign (nil) make a GPG-signed tag;
771
+ # requires `:message` or `:file` (alias: `:s`)
772
+ #
773
+ # @option options [Boolean, nil] :s (nil) alias for `:sign`
774
+ #
775
+ # @option options [Boolean, nil] :no_sign (nil) override `tag.gpgSign`
776
+ # config to disable signing
777
+ #
778
+ # @option options [String] :local_user (nil) make a signed tag using the
779
+ # given key (alias: `:u`)
780
+ #
781
+ # @option options [String] :u (nil) alias for `:local_user`
782
+ #
783
+ # @option options [Boolean, nil] :force (nil) replace an existing tag with
784
+ # the given name instead of failing (alias: `:f`)
785
+ #
786
+ # @option options [Boolean, nil] :f (nil) alias for `:force`
787
+ #
788
+ # @option options [String] :message (nil) use the given message as the tag
789
+ # message (alias: `:m`)
790
+ #
791
+ # @option options [String] :m (nil) alias for `:message`
792
+ #
793
+ # @option options [String] :file (nil) take the tag message from the given
794
+ # file; use `-` to read from standard input (alias: `:F`)
795
+ #
796
+ # @option options [String] :F (nil) alias for `:file`
797
+ #
798
+ # @option options [Boolean, nil] :edit (nil) open an editor to further edit
799
+ # the tag message (alias: `:e`)
800
+ #
801
+ # @option options [Boolean, nil] :e (nil) alias for `:edit`
802
+ #
803
+ # @option options [Boolean, nil] :no_edit (nil) suppress the editor
804
+ #
805
+ # @option options [Hash, Array<Array>] :trailer (nil) add trailers to the
806
+ # tag message
807
+ #
808
+ # @option options [String] :cleanup (nil) set how the tag message is
809
+ # cleaned up; one of `verbatim`, `whitespace`, or `strip`
810
+ #
811
+ # @option options [Boolean, nil] :create_reflog (nil) create a reflog for
812
+ # the tag
813
+ #
814
+ # @return [Git::TagInfo] the newly created tag
815
+ #
816
+ # @overload tag_create(name, target, options = {})
817
+ #
818
+ # @example Create a lightweight tag on a specific commit
819
+ # repo.tag_create('v1.0.0', 'abc123')
820
+ #
821
+ # @example Create an annotated tag on a specific commit
822
+ # repo.tag_create('v1.0.0', 'abc123', annotate: true, message: 'Release 1.0.0')
823
+ #
824
+ # @param name [String] the name of the tag to create
825
+ #
826
+ # @param target [String] the object to tag (commit SHA, branch name, etc.)
827
+ #
828
+ # @param options [Hash] options for creating the tag (same keys as the
829
+ # first overload)
830
+ #
831
+ # @return [Git::TagInfo] the newly created tag
832
+ #
833
+ # @raise [ArgumentError] if unsupported options are provided, including the
834
+ # `:d` and `:delete` keys; use {#tag_delete} to delete a tag
835
+ #
836
+ # @raise [ArgumentError] if an annotated or signed tag is requested without
837
+ # a message
838
+ #
839
+ # @raise [ArgumentError] if more than one positional argument follows the
840
+ # name (before any options hash)
841
+ #
842
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
843
+ #
844
+ # @raise [Git::UnexpectedResultError] if the tag listing cannot be parsed
845
+ # or does not contain the new tag (for example, it was deleted by another
846
+ # process before the lookup)
847
+ #
848
+ # @see https://git-scm.com/docs/git-tag git-tag
849
+ #
850
+ def tag_create(name, *args)
851
+ target, options = Private.tag_target_and_options(args)
852
+ SharedPrivate.assert_valid_opts!(TAG_CREATE_ALLOWED_OPTS, **options)
853
+ Private.create_tag(@execution_context, name, target, options)
854
+ tag_list(name).first ||
855
+ raise(Git::UnexpectedResultError, "tag was created but not found in the tag list: #{name}")
856
+ end
857
+
858
+ # Delete a tag
859
+ #
860
+ # @example Delete a tag
861
+ # repo.tag_delete('v1.0.0')
862
+ #
863
+ # @param name [String] the name of the tag to delete
864
+ #
865
+ # @return [String] git's stdout from the delete
866
+ #
867
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
868
+ #
869
+ def tag_delete(name)
870
+ result = Git::Commands::Tag::Delete.new(@execution_context).call(name)
871
+ raise Git::FailedError, result if result.status.exitstatus.positive?
872
+
873
+ result.stdout
874
+ end
875
+
876
+ # Private helpers
877
+ #
878
+ # @api private
879
+ #
880
+ module Private # rubocop:disable Metrics/ModuleLength
881
+ module_function
882
+
883
+ # Splits the variadic `*args` of {ObjectOperations#tag_create} into the
884
+ # target and the options hash
885
+ #
886
+ # `tag_create` accepts `(name, opts = {})` and `(name, target, opts = {})`,
887
+ # so a trailing `Hash` is the options and anything before it is the
888
+ # target.
889
+ #
890
+ # @param args [Array] the arguments after the tag name
891
+ #
892
+ # @return [Array((String, nil), Hash)] the two-element tuple
893
+ # `[target, options]`; `target` is `nil` when only options were given
894
+ #
895
+ # @raise [ArgumentError] if more than one positional argument precedes
896
+ # the options hash
897
+ #
898
+ # @api private
899
+ #
900
+ def tag_target_and_options(args)
901
+ args = args.dup
902
+ options = args.last.is_a?(Hash) ? args.pop : {}
903
+ if args.size > 1
904
+ raise ArgumentError,
905
+ "Expected at most one target before the options, got #{args.size}: #{args.inspect}"
906
+ end
907
+
908
+ [args.first, options]
909
+ end
910
+
911
+ # Validates the tag-creation options and runs `git tag`
912
+ #
913
+ # @param execution_context [Git::ExecutionContext::Repository] the
914
+ # execution context for git commands
915
+ #
916
+ # @param name [String] the name of the tag to create
917
+ #
918
+ # @param target [String, nil] the object to tag, or `nil` for HEAD
919
+ #
920
+ # @param options [Hash] the tag-creation options, already checked
921
+ # against the allowed keys (see {ObjectOperations#tag_create} for the
922
+ # full list)
923
+ #
924
+ # @option options [Boolean, nil] :annotate (nil) make an annotated tag;
925
+ # requires a message (alias: `:a`)
926
+ #
927
+ # @option options [Boolean, nil] :sign (nil) make a signed tag; requires
928
+ # a message (alias: `:s`)
929
+ #
930
+ # @option options [String] :local_user (nil) sign with the given key;
931
+ # requires a message (alias: `:u`)
932
+ #
933
+ # @option options [String] :message (nil) the tag message (alias: `:m`)
934
+ #
935
+ # @option options [String] :file (nil) a file to read the tag message
936
+ # from (alias: `:F`)
937
+ #
938
+ # @option options [Boolean, nil] :force (nil) replace an existing tag
939
+ # (alias: `:f`)
940
+ #
941
+ # @return [void]
942
+ #
943
+ # @raise [ArgumentError] when an annotated or signed tag is requested
944
+ # without a message
945
+ #
946
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
947
+ #
948
+ # @api private
949
+ #
950
+ def create_tag(execution_context, name, target, options)
951
+ validate_tag_options!(options)
952
+ Git::Commands::Tag::Create.new(execution_context).call(name, target, **options)
953
+ end
954
+
955
+ # Validate that a message is present when an annotated or signed tag is
956
+ # requested
957
+ #
958
+ # @param opts [Hash] the tag-creation options
959
+ #
960
+ # @option opts [Boolean, nil] :annotate request an annotated tag
961
+ #
962
+ # @option opts [Boolean, nil] :a alias for `:annotate`
963
+ #
964
+ # @option opts [Boolean, nil] :sign request a signed tag
965
+ #
966
+ # @option opts [Boolean, nil] :s alias for `:sign`
967
+ #
968
+ # @option opts [String] :local_user key id used when signing
969
+ #
970
+ # @option opts [String] :u alias for `:local_user`
971
+ #
972
+ # @option opts [String] :message tag message text
973
+ #
974
+ # @option opts [String] :m alias for `:message`
975
+ #
976
+ # @option opts [String] :file path to a tag message file
977
+ #
978
+ # @option opts [String] :F alias for `:file`
979
+ #
980
+ # @return [void]
981
+ #
982
+ # @raise [ArgumentError] when an annotated or signed tag is requested
983
+ # without a `:message`/`:m`/`:file`/`:F` value
984
+ #
985
+ def validate_tag_options!(opts)
986
+ needs_message = %i[a annotate s sign u local_user].any? { |k| opts[k] }
987
+ has_message = opts[:m] || opts[:message] || opts[:F] || opts[:file]
988
+
989
+ return unless needs_message && !has_message
990
+
991
+ raise ArgumentError, 'Cannot create an annotated or signed tag without a message.'
992
+ end
993
+
994
+ # Read the SHA from a loose tag ref file without forking git
995
+ #
996
+ # Returns `nil` when the ref is not a loose file under `tags_dir` or when
997
+ # the file cannot be read, so the caller falls back to `git show-ref`.
998
+ #
999
+ # @param tags_dir [String] absolute path of the `refs/tags` directory
1000
+ #
1001
+ # @param head [String] absolute path of the candidate loose ref file
1002
+ #
1003
+ # @return [String, nil] the SHA in the file, or `nil` to fall back to git
1004
+ #
1005
+ # @api private
1006
+ #
1007
+ def loose_tag_sha(tags_dir, head)
1008
+ return nil unless head.start_with?("#{tags_dir}#{File::SEPARATOR}") && File.file?(head)
1009
+
1010
+ File.read(head).chomp
1011
+ rescue SystemCallError
1012
+ nil
1013
+ end
1014
+
1015
+ # Returns the direct SHA for a tag reference
1016
+ #
1017
+ # Returns the hash from `refs/tags/<name>` only. Returns an empty string
1018
+ # when the ref does not exist.
1019
+ #
1020
+ # @param execution_context [Git::ExecutionContext] for running
1021
+ # `git show-ref`
1022
+ #
1023
+ # @param tag_name [String] tag name without the `refs/tags/` prefix
1024
+ #
1025
+ # @return [String] direct ref SHA or an empty string when missing
1026
+ #
1027
+ # @api private
1028
+ #
1029
+ def show_ref_tag_sha(execution_context, tag_name)
1030
+ ref = "refs/tags/#{tag_name}"
1031
+ result = Git::Commands::ShowRef::List.new(execution_context).call(ref)
1032
+ return '' if result.status.exitstatus == 1
1033
+
1034
+ line = result.stdout.lines.find { |l| l.split[1] == ref }
1035
+ line ? line.split[0] : ''
1036
+ end
1037
+
1038
+ # Parses the result of a git grep command
1039
+ #
1040
+ # @param result [Git::CommandLine::Result] the result of a git grep command
1041
+ #
1042
+ # @return [Hash<String, Array<Array(Integer, String)>>] hash mapping "treeish:filename"
1043
+ # keys to arrays of [line_number, text] pairs
1044
+ #
1045
+ def parse_grep_result(result)
1046
+ exitstatus = result.status.exitstatus
1047
+ return {} if exitstatus == 1 && result.stderr.empty?
1048
+ raise Git::FailedError, result if exitstatus == 1
1049
+
1050
+ Git::Parsers::Grep.parse(result.stdout)
1051
+ end
1052
+
1053
+ # Resolve the staging directory for a git archive temp file
1054
+ #
1055
+ # Always returns `Dir.tmpdir` when `file` is nil, or the parent
1056
+ # directory of `file` otherwise. Staging the temp file in the same
1057
+ # directory as the destination keeps both paths on the same filesystem
1058
+ # so that {#atomic_replace} can use an atomic rename that
1059
+ # requires no extra disk space.
1060
+ #
1061
+ # @param file [String, nil] the explicit destination path, or nil
1062
+ #
1063
+ # @return [String] directory path to pass to `Tempfile.create`
1064
+ #
1065
+ # @api private
1066
+ #
1067
+ def staging_dir_for(file)
1068
+ return Dir.tmpdir unless file
1069
+
1070
+ File.dirname(File.expand_path(file))
1071
+ end
1072
+
1073
+ # Write a git archive, staging it in a temporary file first
1074
+ #
1075
+ # @param execution_context [Git::ExecutionContext] the execution context
1076
+ #
1077
+ # @param treeish [String] tree-ish to archive
1078
+ #
1079
+ # @param file [String, nil] destination path, or `nil` to keep the
1080
+ # temporary file
1081
+ #
1082
+ # @param opts [Hash] caller-supplied options (read-only)
1083
+ #
1084
+ # @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
1085
+ # or `'tgz'`)
1086
+ #
1087
+ # @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
1088
+ # to the generated archive
1089
+ #
1090
+ # @option opts [String] :prefix (nil) prefix for entries in the archive
1091
+ #
1092
+ # @option opts [String] :path (nil) path within `treeish` to archive
1093
+ #
1094
+ # @option opts [String] :remote (nil) remote repository from which to
1095
+ # retrieve the archive
1096
+ #
1097
+ # @return [String] path to the written archive file
1098
+ #
1099
+ # @api private
1100
+ #
1101
+ def write_archive(execution_context, treeish, file, opts)
1102
+ tmp = write_archive_tmp(execution_context, treeish, opts, dest_dir: staging_dir_for(file))
1103
+ return tmp unless file
1104
+
1105
+ atomic_replace(tmp, file)
1106
+ file
1107
+ rescue StandardError
1108
+ FileUtils.rm_f(tmp) if tmp
1109
+ raise
1110
+ end
1111
+
1112
+ # Write a git archive to a fresh temporary file and return its path
1113
+ #
1114
+ # Always writes to a new temporary file so that on error the caller's
1115
+ # destination file is never truncated. Format and gzip post-processing
1116
+ # are determined from `opts` via {#parse_archive_format_options}.
1117
+ #
1118
+ # @param execution_context [Git::ExecutionContext] for the git command
1119
+ #
1120
+ # @param treeish [String] tree-ish passed to `git archive`
1121
+ #
1122
+ # @param dest_dir [String] directory for the staging temp file; use
1123
+ # {#staging_dir_for} to select the optimal directory for the destination
1124
+ #
1125
+ # @param opts [Hash] caller-supplied options (read-only)
1126
+ #
1127
+ # @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
1128
+ # or `'tgz'`)
1129
+ #
1130
+ # @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
1131
+ # to the generated archive
1132
+ #
1133
+ # @option opts [String] :prefix (nil) prefix for entries in the archive
1134
+ #
1135
+ # @option opts [String] :path (nil) path within `treeish` to archive
1136
+ #
1137
+ # @option opts [String] :remote (nil) remote repository from which to
1138
+ # retrieve the archive
1139
+ #
1140
+ # @return [String] path to the populated temporary file
1141
+ #
1142
+ # @api private
1143
+ #
1144
+ def write_archive_tmp(execution_context, treeish, opts, dest_dir: Dir.tmpdir)
1145
+ format, gzip = parse_archive_format_options(opts)
1146
+ tmp_file = create_archive_tempfile(execution_context, treeish, opts, format, dest_dir)
1147
+ apply_gzip(tmp_file.path) if gzip
1148
+ tmp_file.path
1149
+ rescue StandardError
1150
+ tmp_file.close unless tmp_file.nil? || tmp_file.closed?
1151
+ FileUtils.rm_f(tmp_file.path) if tmp_file
1152
+ raise
1153
+ end
1154
+
1155
+ # Create a staging file, write the archive into it, close it, and return it
1156
+ #
1157
+ # Uses `Tempfile.create` (not `Tempfile.new`) so that no GC finalizer is
1158
+ # registered on the returned object — the file path remains valid after this
1159
+ # method returns and after the caller stores only the path string.
1160
+ #
1161
+ # @param execution_context [Git::ExecutionContext] for the git command
1162
+ #
1163
+ # @param treeish [String] tree-ish passed to `git archive`
1164
+ #
1165
+ # @param format [String] archive format string (e.g. `'zip'` or `'tar'`)
1166
+ #
1167
+ # @param dest_dir [String] directory in which to create the temp file
1168
+ #
1169
+ # @param opts [Hash] caller-supplied options (read-only; used for :prefix,
1170
+ # :remote, and :path)
1171
+ #
1172
+ # @option opts [String] :prefix (nil) prefix for entries in the archive
1173
+ #
1174
+ # @option opts [String] :path (nil) path within `treeish` to archive
1175
+ #
1176
+ # @option opts [String] :remote (nil) remote repository from which to
1177
+ # retrieve the archive
1178
+ #
1179
+ # @return [File] the closed file containing the archive
1180
+ #
1181
+ # @api private
1182
+ #
1183
+ def create_archive_tempfile(execution_context, treeish, opts, format, dest_dir)
1184
+ tmp_file = Tempfile.create('archive', dest_dir).tap(&:binmode)
1185
+ run_archive_command(execution_context, treeish, opts, format, tmp_file)
1186
+ tmp_file.close
1187
+ tmp_file
1188
+ rescue StandardError
1189
+ tmp_file&.close
1190
+ FileUtils.rm_f(tmp_file.path) if tmp_file
1191
+ raise
1192
+ end
1193
+
1194
+ # Invoke `git archive` and stream output into `tmp_file`
1195
+ #
1196
+ # @param execution_context [Git::ExecutionContext] for the git command
1197
+ #
1198
+ # @param treeish [String] tree-ish passed to `git archive`
1199
+ #
1200
+ # @param format [String] archive format to pass to `git archive --format`
1201
+ #
1202
+ # @param tmp_file [File] open, binary-mode IO to write archive data to
1203
+ #
1204
+ # @param opts [Hash] caller-supplied options (read-only; used for :prefix,
1205
+ # :remote, and :path)
1206
+ #
1207
+ # @option opts [String] :prefix (nil) prefix for entries in the archive
1208
+ #
1209
+ # @option opts [String] :path (nil) path within `treeish` to archive
1210
+ #
1211
+ # @option opts [String] :remote (nil) remote repository from which to
1212
+ # retrieve the archive
1213
+ #
1214
+ # @return [Git::CommandLine::Result] the result of the git command
1215
+ #
1216
+ # @api private
1217
+ #
1218
+ def run_archive_command(execution_context, treeish, opts, format, tmp_file)
1219
+ command_opts = opts.slice(:prefix, :remote).merge(format: format)
1220
+ path_args = opts[:path] ? [opts[:path]] : []
1221
+ Git::Commands::Archive.new(execution_context).call(treeish, *path_args, **command_opts, out: tmp_file)
1222
+ end
1223
+
1224
+ # Atomically rename the staging file `src` to `dest`, replacing any
1225
+ # existing file at `dest`. Both paths must be on the same filesystem
1226
+ # (guaranteed when `src` is created by {#staging_dir_for}).
1227
+ #
1228
+ # Before the rename, the staging file's permissions are set to the
1229
+ # existing file's numeric mode (if `dest` already existed) or to
1230
+ # `0666 & ~umask` (standard creation mode) for new files. The chmod
1231
+ # is applied to `src` before the rename so that, if chmod fails, `src`
1232
+ # is still present and can be cleaned up by the rescue. Only the
1233
+ # numeric permission bits are carried over; ownership, ACLs, and
1234
+ # extended attributes from an existing `dest` are not preserved.
1235
+ #
1236
+ # If `dest` is a symlink, the symlink itself is replaced by the renamed
1237
+ # staging file rather than writing through the link to its target.
1238
+ #
1239
+ # @param src [String] staging file path to rename; removed on success
1240
+ #
1241
+ # @param dest [String] destination file path
1242
+ #
1243
+ # @return [void]
1244
+ #
1245
+ # @api private
1246
+ #
1247
+ def atomic_replace(src, dest)
1248
+ mode = File.exist?(dest) ? (File.stat(dest).mode & 0o777) : (0o666 & ~File.umask)
1249
+ File.chmod(mode, src)
1250
+ File.rename(src, dest)
1251
+ rescue StandardError
1252
+ FileUtils.rm_f(src)
1253
+ raise
1254
+ end
1255
+
1256
+ # Determine the archive format and whether to apply gzip post-processing
1257
+ #
1258
+ # The `tgz` pseudo-format is not understood by `git archive` directly;
1259
+ # it is converted to `tar` and the gzip flag is set so that {#archive}
1260
+ # applies gzip compression after the archive is written.
1261
+ #
1262
+ # @param opts [Hash] caller-supplied options hash (read-only)
1263
+ #
1264
+ # @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
1265
+ # or `'tgz'`)
1266
+ #
1267
+ # @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
1268
+ # after archive generation
1269
+ #
1270
+ # @return [Array(String, Boolean)] a two-element array `[format, gzip]`
1271
+ #
1272
+ # `format` is the string to pass to `git archive --format`; `gzip` is
1273
+ # `true` when the caller should apply gzip post-processing after writing
1274
+ # the archive.
1275
+ #
1276
+ # @api private
1277
+ #
1278
+ def parse_archive_format_options(opts)
1279
+ format = opts[:format] || 'zip'
1280
+ gzip = opts[:add_gzip] == true || format == 'tgz'
1281
+ [format == 'tgz' ? 'tar' : format, gzip]
1282
+ end
1283
+
1284
+ # Apply gzip compression to the given file in place
1285
+ #
1286
+ # Streams from the source file through a {Zlib::GzipWriter} into a sibling
1287
+ # temporary file, then replaces the original. Peak memory is proportional
1288
+ # to the stream buffer rather than the full archive size.
1289
+ #
1290
+ # @param file [String] path to the file to compress in place
1291
+ #
1292
+ # @return [void]
1293
+ #
1294
+ # @raise [Git::Error] if zlib fails during compression, with the
1295
+ # `Zlib::Error` as `cause`
1296
+ #
1297
+ # @api private
1298
+ #
1299
+ def apply_gzip(file)
1300
+ gz_tmp = Tempfile.create('archive_gz', File.dirname(file)).tap(&:close).path
1301
+ gzip_file(file, gz_tmp)
1302
+ FileUtils.rm_f(file)
1303
+ File.rename(gz_tmp, file)
1304
+ rescue StandardError
1305
+ FileUtils.rm_f(gz_tmp) if gz_tmp
1306
+ raise
1307
+ end
1308
+
1309
+ # Stream `src` through a {Zlib::GzipWriter} into `dest`
1310
+ #
1311
+ # A `Zlib::Error` is not a `SystemCallError`, so {Git::SystemCallGuard}
1312
+ # does not convert it; this method does, per ADR-0008.
1313
+ #
1314
+ # @param src [String] path to the file to compress
1315
+ #
1316
+ # @param dest [String] path to write the gzip stream to
1317
+ #
1318
+ # @return [void]
1319
+ #
1320
+ # @raise [Git::Error] if zlib fails during compression, with the
1321
+ # `Zlib::Error` as `cause`
1322
+ #
1323
+ # @api private
1324
+ #
1325
+ def gzip_file(src, dest)
1326
+ Zlib::GzipWriter.open(dest) { |gz| File.open(src, 'rb') { |f| IO.copy_stream(f, gz) } }
1327
+ rescue Zlib::Error => e
1328
+ raise Git::Error, "Failed to gzip the archive: #{e.message}"
1329
+ end
1330
+ end
1331
+ private_constant :Private
1332
+ end
1333
+ end
1334
+ end