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,619 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/rev_parse'
4
+ require 'git/commands/stash'
5
+ require 'git/parsers/stash'
6
+ require 'git/repository/shared_private'
7
+
8
+ module Git
9
+ class Repository
10
+ # Facade methods for stash operations
11
+ #
12
+ # Each method maps onto a `git stash` subcommand. Methods that identify or
13
+ # create a stash entry ({#stash_list}, {#stash_push}, {#stash_store}) return
14
+ # {Git::StashInfo} values; methods that only change or display the stash
15
+ # return git's stdout. Every method that takes a stash ({#stash_apply},
16
+ # {#stash_pop}, {#stash_drop}, {#stash_show}, {#stash_branch}) accepts a
17
+ # {Git::StashInfo}, a `stash@{N}` name, an Integer index (`0` is the most
18
+ # recent entry), or `nil` for the most recent entry. Methods that take
19
+ # options accept them as a trailing positional Hash, so
20
+ # `repo.stash_apply(index: true)` and `repo.stash_apply(nil, opts)` with a
21
+ # stored `opts` Hash both work.
22
+ #
23
+ # Included by {Git::Repository}.
24
+ #
25
+ # @api private
26
+ #
27
+ module Stashing
28
+ # Returns every stash entry as a {Git::StashInfo}, newest first
29
+ #
30
+ # The order and indices match `git stash list`: the first element is
31
+ # `stash@{0}`, the most recent entry.
32
+ #
33
+ # @example List stash entries (newest first)
34
+ # repo.stash_list.map(&:name) #=> ["stash@{0}", "stash@{1}"]
35
+ #
36
+ # @example Apply the oldest entry
37
+ # repo.stash_apply(repo.stash_list.last)
38
+ #
39
+ # @return [Array<Git::StashInfo>] the stash entries, newest first; empty
40
+ # when there are none
41
+ #
42
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
43
+ #
44
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
45
+ #
46
+ def stash_list
47
+ result = Git::Commands::Stash::List.new(@execution_context).call
48
+ Git::Parsers::Stash.parse_list(result.stdout)
49
+ end
50
+
51
+ # Alias for {#stash_list}
52
+ #
53
+ # @see #stash_list
54
+ alias stash_infos stash_list
55
+
56
+ # Option keys accepted by {#stash_push}
57
+ STASH_PUSH_ALLOWED_OPTS = %i[
58
+ patch p staged S keep_index k no_keep_index quiet q include_untracked u all a
59
+ message m pathspec_from_file pathspec_file_nul
60
+ ].freeze
61
+ private_constant :STASH_PUSH_ALLOWED_OPTS
62
+
63
+ # Save the working tree and index state to a new stash entry
64
+ #
65
+ # The stash list is read before and after the push and the entry counts are
66
+ # compared, so the return value is `nil` whenever git created no entry. This
67
+ # holds with `quiet: true`, which suppresses git's "No local changes to
68
+ # save" message.
69
+ #
70
+ # @overload stash_push(*pathspec, options = {})
71
+ #
72
+ # @example Stash all changes with a message
73
+ # info = repo.stash_push(message: 'WIP: feature work')
74
+ # info.name #=> "stash@{0}"
75
+ # info.message #=> "On main: WIP: feature work"
76
+ #
77
+ # @example Stash only specific paths
78
+ # repo.stash_push('src/a.rb', 'src/b.rb', message: 'partial work')
79
+ #
80
+ # @example Nothing to stash
81
+ # repo.stash_push #=> nil
82
+ #
83
+ # @param pathspec [Array<String>] paths that limit what gets stashed; when
84
+ # empty, all changes are stashed
85
+ #
86
+ # @param options [Hash] options for the push
87
+ #
88
+ # @option options [Boolean, nil] :patch (nil) interactively select hunks to
89
+ # stash (alias: `:p`)
90
+ #
91
+ # @option options [Boolean, nil] :p (nil) alias for `:patch`
92
+ #
93
+ # @option options [Boolean, nil] :staged (nil) stash only the staged changes
94
+ # (alias: `:S`)
95
+ #
96
+ # @option options [Boolean, nil] :S (nil) alias for `:staged`
97
+ #
98
+ # @option options [Boolean, nil] :keep_index (nil) keep the staged changes
99
+ # in the index (alias: `:k`)
100
+ #
101
+ # @option options [Boolean, nil] :k (nil) alias for `:keep_index`
102
+ #
103
+ # @option options [Boolean, nil] :no_keep_index (nil) do not keep the staged
104
+ # changes in the index
105
+ #
106
+ # @option options [Boolean, nil] :quiet (nil) suppress informational
107
+ # messages (alias: `:q`)
108
+ #
109
+ # @option options [Boolean, nil] :q (nil) alias for `:quiet`
110
+ #
111
+ # @option options [Boolean, nil] :include_untracked (nil) include untracked
112
+ # files in the stash (alias: `:u`)
113
+ #
114
+ # @option options [Boolean, nil] :u (nil) alias for `:include_untracked`
115
+ #
116
+ # @option options [Boolean, nil] :all (nil) include untracked and ignored
117
+ # files in the stash (alias: `:a`)
118
+ #
119
+ # @option options [Boolean, nil] :a (nil) alias for `:all`
120
+ #
121
+ # @option options [String] :message (nil) the stash message (alias: `:m`)
122
+ #
123
+ # @option options [String] :m (nil) alias for `:message`
124
+ #
125
+ # @option options [String] :pathspec_from_file (nil) read pathspecs from the
126
+ # given file; pass `-` to read from standard input
127
+ #
128
+ # @option options [Boolean, nil] :pathspec_file_nul (nil) when used with
129
+ # `:pathspec_from_file`, pathspecs are NUL-separated
130
+ #
131
+ # @return [Git::StashInfo, nil] the new entry, or `nil` when there were no
132
+ # local changes to save
133
+ #
134
+ # @raise [ArgumentError] if unsupported options are provided
135
+ #
136
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
137
+ #
138
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
139
+ #
140
+ def stash_push(*pathspec)
141
+ pathspec, opts = Private.split_pathspec_and_opts(pathspec)
142
+ SharedPrivate.assert_valid_opts!(STASH_PUSH_ALLOWED_OPTS, **opts)
143
+ previous_count = stash_list.size
144
+ Git::Commands::Stash::Push.new(@execution_context).call(*pathspec, **opts)
145
+ entries = stash_list
146
+ entries.first if entries.size > previous_count
147
+ end
148
+
149
+ # Option keys accepted by {#stash_apply}
150
+ STASH_APPLY_ALLOWED_OPTS = %i[index quiet q].freeze
151
+ private_constant :STASH_APPLY_ALLOWED_OPTS
152
+
153
+ # Apply a stash entry to the working tree, keeping it in the stash list
154
+ #
155
+ # @example Apply the most recent entry
156
+ # repo.stash_apply #=> "On branch main\nChanges not staged for commit:..."
157
+ #
158
+ # @example Apply an entry from {#stash_list}
159
+ # repo.stash_apply(repo.stash_list.last)
160
+ #
161
+ # @example Apply an entry by name and restore the index too
162
+ # repo.stash_apply('stash@{1}', index: true)
163
+ #
164
+ # @param stash [Git::StashInfo, String, Integer, nil] the entry to apply: a
165
+ # {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the most
166
+ # recent entry), or `nil` for the most recent entry
167
+ #
168
+ # @param opts [Hash] options for the apply
169
+ #
170
+ # @option opts [Boolean, nil] :index (nil) restore the index state as
171
+ # well as the working tree
172
+ #
173
+ # @option opts [Boolean, nil] :quiet (nil) suppress informational
174
+ # messages (alias: `:q`)
175
+ #
176
+ # @option opts [Boolean, nil] :q (nil) alias for `:quiet`
177
+ #
178
+ # @return [String] git's stdout from the apply
179
+ #
180
+ # @raise [ArgumentError] if unsupported options are provided
181
+ #
182
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
183
+ #
184
+ # @note If git exits non-zero, nothing is unwound: whatever git applied stays
185
+ # in the working tree and index, including untracked files restored from
186
+ # the entry even when git refused to touch the tracked files, and on a
187
+ # conflict the conflicted paths are left for the caller to resolve.
188
+ #
189
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
190
+ #
191
+ def stash_apply(stash = nil, opts = {})
192
+ stash, opts = Private.split_stash_and_opts(stash, opts)
193
+ SharedPrivate.assert_valid_opts!(STASH_APPLY_ALLOWED_OPTS, **opts)
194
+ Git::Commands::Stash::Apply.new(@execution_context).call(stash, **opts).stdout
195
+ end
196
+
197
+ # Option keys accepted by {#stash_pop}
198
+ STASH_POP_ALLOWED_OPTS = %i[index quiet q].freeze
199
+ private_constant :STASH_POP_ALLOWED_OPTS
200
+
201
+ # Apply a stash entry to the working tree and remove it from the stash list
202
+ #
203
+ # @example Pop the most recent entry
204
+ # repo.stash_pop #=> "On branch main\n...Dropped refs/stash@{0} (abc1234...)"
205
+ #
206
+ # @example Pop an entry from {#stash_list}
207
+ # repo.stash_pop(repo.stash_list.last)
208
+ #
209
+ # @param stash [Git::StashInfo, String, Integer, nil] the entry to pop: a
210
+ # {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the most
211
+ # recent entry), or `nil` for the most recent entry
212
+ #
213
+ # @param opts [Hash] options for the pop
214
+ #
215
+ # @option opts [Boolean, nil] :index (nil) restore the index state as
216
+ # well as the working tree
217
+ #
218
+ # @option opts [Boolean, nil] :quiet (nil) suppress informational
219
+ # messages (alias: `:q`)
220
+ #
221
+ # @option opts [Boolean, nil] :q (nil) alias for `:quiet`
222
+ #
223
+ # @return [String] git's stdout from the pop
224
+ #
225
+ # @raise [ArgumentError] if unsupported options are provided
226
+ #
227
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
228
+ #
229
+ # @note If git exits non-zero, nothing is unwound, as described at
230
+ # {#stash_apply}, and the entry is kept in the stash list rather than
231
+ # dropped.
232
+ #
233
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
234
+ #
235
+ def stash_pop(stash = nil, opts = {})
236
+ stash, opts = Private.split_stash_and_opts(stash, opts)
237
+ SharedPrivate.assert_valid_opts!(STASH_POP_ALLOWED_OPTS, **opts)
238
+ Git::Commands::Stash::Pop.new(@execution_context).call(stash, **opts).stdout
239
+ end
240
+
241
+ # Option keys accepted by {#stash_drop}
242
+ STASH_DROP_ALLOWED_OPTS = %i[quiet q].freeze
243
+ private_constant :STASH_DROP_ALLOWED_OPTS
244
+
245
+ # Remove a single stash entry from the stash list
246
+ #
247
+ # @example Drop the most recent entry
248
+ # repo.stash_drop #=> "Dropped refs/stash@{0} (abc1234...)"
249
+ #
250
+ # @example Drop an entry from {#stash_list}
251
+ # repo.stash_drop(repo.stash_list.last)
252
+ #
253
+ # @param stash [Git::StashInfo, String, Integer, nil] the entry to drop: a
254
+ # {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the most
255
+ # recent entry), or `nil` for the most recent entry
256
+ #
257
+ # @param opts [Hash] options for the drop
258
+ #
259
+ # @option opts [Boolean, nil] :quiet (nil) suppress informational
260
+ # messages (alias: `:q`)
261
+ #
262
+ # @option opts [Boolean, nil] :q (nil) alias for `:quiet`
263
+ #
264
+ # @return [String] git's stdout from the drop
265
+ #
266
+ # @raise [ArgumentError] if unsupported options are provided
267
+ #
268
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
269
+ #
270
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
271
+ #
272
+ def stash_drop(stash = nil, opts = {})
273
+ stash, opts = Private.split_stash_and_opts(stash, opts)
274
+ SharedPrivate.assert_valid_opts!(STASH_DROP_ALLOWED_OPTS, **opts)
275
+ Git::Commands::Stash::Drop.new(@execution_context).call(stash, **opts).stdout
276
+ end
277
+
278
+ # Option keys accepted by {#stash_show}
279
+ STASH_SHOW_ALLOWED_OPTS = %i[
280
+ patch numstat raw shortstat unified U include_untracked u no_include_untracked
281
+ only_untracked find_renames M find_copies C find_copies_harder inter_hunk_context dirstat
282
+ ].freeze
283
+ private_constant :STASH_SHOW_ALLOWED_OPTS
284
+
285
+ # Show the changes recorded in a stash entry as a diff
286
+ #
287
+ # Without options, git prints a diffstat. The output is returned as git
288
+ # prints it.
289
+ #
290
+ # @example Show the diffstat of the most recent entry
291
+ # repo.stash_show #=> " file.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)"
292
+ #
293
+ # @example Show the full patch of an entry from {#stash_list}
294
+ # repo.stash_show(repo.stash_list.last, patch: true)
295
+ #
296
+ # @param stash [Git::StashInfo, String, Integer, nil] the entry to show: a
297
+ # {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the most
298
+ # recent entry), or `nil` for the most recent entry
299
+ #
300
+ # @param opts [Hash] options for the show
301
+ #
302
+ # @option opts [Boolean, nil] :patch (nil) show the diff as a patch
303
+ #
304
+ # @option opts [Boolean, nil] :numstat (nil) show per-file insertion and
305
+ # deletion counts
306
+ #
307
+ # @option opts [Boolean, nil] :raw (nil) show per-file mode, object id,
308
+ # and status metadata
309
+ #
310
+ # @option opts [Boolean, nil] :shortstat (nil) show only the summary line
311
+ #
312
+ # @option opts [Integer, String] :unified (nil) number of context lines
313
+ # in the patch (alias: `:U`)
314
+ #
315
+ # @option opts [Integer, String] :U (nil) alias for `:unified`
316
+ #
317
+ # @option opts [Boolean, nil] :include_untracked (nil) include the
318
+ # untracked files recorded in the entry (alias: `:u`)
319
+ #
320
+ # @option opts [Boolean, nil] :u (nil) alias for `:include_untracked`
321
+ #
322
+ # @option opts [Boolean, nil] :no_include_untracked (nil) exclude the
323
+ # untracked files recorded in the entry
324
+ #
325
+ # @option opts [Boolean, nil] :only_untracked (nil) show only the
326
+ # untracked files recorded in the entry
327
+ #
328
+ # @option opts [Boolean, Integer, nil] :find_renames (nil) detect
329
+ # renames, optionally with a similarity threshold (alias: `:M`)
330
+ #
331
+ # @option opts [Boolean, Integer, nil] :M (nil) alias for `:find_renames`
332
+ #
333
+ # @option opts [Boolean, Integer, nil] :find_copies (nil) detect copies
334
+ # as well as renames, optionally with a similarity threshold (alias: `:C`)
335
+ #
336
+ # @option opts [Boolean, Integer, nil] :C (nil) alias for `:find_copies`
337
+ #
338
+ # @option opts [Boolean, nil] :find_copies_harder (nil) inspect unmodified
339
+ # files as copy sources
340
+ #
341
+ # @option opts [Integer, String] :inter_hunk_context (nil) number of
342
+ # context lines between hunks before they are merged
343
+ #
344
+ # @option opts [Boolean, String, nil] :dirstat (nil) include directory
345
+ # statistics, optionally with parameters
346
+ #
347
+ # @return [String] git's stdout from the show
348
+ #
349
+ # @raise [ArgumentError] if unsupported options are provided
350
+ #
351
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
352
+ #
353
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
354
+ #
355
+ def stash_show(stash = nil, opts = {})
356
+ stash, opts = Private.split_stash_and_opts(stash, opts)
357
+ SharedPrivate.assert_valid_opts!(STASH_SHOW_ALLOWED_OPTS, **opts)
358
+ Git::Commands::Stash::Show.new(@execution_context).call(stash, **opts).stdout
359
+ end
360
+
361
+ # Create and check out a branch from the commit a stash entry was based on
362
+ #
363
+ # Applies the entry on the new branch and, when that succeeds, drops the
364
+ # entry from the stash list.
365
+ #
366
+ # @example Branch from the most recent entry
367
+ # repo.stash_branch('feature') #=> "Switched to a new branch 'feature'\n..."
368
+ #
369
+ # @example Branch from an entry from {#stash_list}
370
+ # repo.stash_branch('feature', repo.stash_list.last)
371
+ #
372
+ # @param branch_name [String] the name of the branch to create
373
+ #
374
+ # @param stash [Git::StashInfo, String, Integer, nil] the entry to branch
375
+ # from: a {Git::StashInfo}, a `stash@{N}` name, an Integer `N` (`0` is the
376
+ # most recent entry), or `nil` for the most recent entry
377
+ #
378
+ # @return [String] git's stdout from the branch command
379
+ #
380
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
381
+ #
382
+ # @note If applying the entry fails, `branch_name` has already been created
383
+ # and checked out, so the repository is left on it with whatever git could
384
+ # apply in the working tree, and the entry stays in the stash list.
385
+ #
386
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
387
+ #
388
+ def stash_branch(branch_name, stash = nil)
389
+ Git::Commands::Stash::Branch.new(@execution_context).call(branch_name, stash).stdout
390
+ end
391
+
392
+ # Create a stash commit without adding it to the stash list
393
+ #
394
+ # The working tree and index are left unchanged. Pass the returned object
395
+ # id to {#stash_store} to add it to the stash list later.
396
+ #
397
+ # @example Create a stash commit
398
+ # repo.stash_create('WIP') #=> "3f8b2d9c..." (the full object id)
399
+ #
400
+ # @example Nothing to stash
401
+ # repo.stash_create #=> nil
402
+ #
403
+ # @param message [String, nil] the message for the stash commit; `nil` for
404
+ # git's default message
405
+ #
406
+ # @return [String, nil] the object id of the stash commit, or `nil` when
407
+ # there were no local changes
408
+ #
409
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
410
+ #
411
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
412
+ #
413
+ def stash_create(message = nil)
414
+ oid = Git::Commands::Stash::Create.new(@execution_context).call(message).stdout.strip
415
+ oid.empty? ? nil : oid
416
+ end
417
+
418
+ # Option keys accepted by {#stash_store}
419
+ STASH_STORE_ALLOWED_OPTS = %i[message m quiet q].freeze
420
+ private_constant :STASH_STORE_ALLOWED_OPTS
421
+
422
+ # Add a stash commit created by {#stash_create} to the stash list
423
+ #
424
+ # `commit` is resolved to the full object id of the commit with
425
+ # `git rev-parse` and that id is what is stored, so an annotated tag stores
426
+ # the tagged commit rather than the tag object (which `git stash store`
427
+ # accepts but `git stash list` cannot show). Because the id is what git
428
+ # sees, a failure from `git stash store` names the resolved id rather than
429
+ # the revision as it was given. The stash list is read after the store and
430
+ # the entry whose object id equals that id is returned.
431
+ #
432
+ # @example Store a stash commit
433
+ # oid = repo.stash_create
434
+ # info = repo.stash_store(oid, message: 'saved for later')
435
+ # info.name #=> "stash@{0}"
436
+ # info.message #=> "saved for later"
437
+ #
438
+ # @example Store a stash commit named by a ref
439
+ # repo.stash_store('refs/tmp/wip').oid #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
440
+ #
441
+ # @param commit [String, #to_s] the stash commit to store, as any revision
442
+ # that resolves to it
443
+ #
444
+ # Full or abbreviated object ids, branch, tag, and other ref names,
445
+ # `stash@{N}`, and `:/<text>` searches all resolve with `git rev-parse`,
446
+ # and a {Git::StashInfo} resolves through its `#to_s`. A `:/<text>` search
447
+ # finds only commits reachable from a ref, so it cannot name a commit from
448
+ # {#stash_create} until that commit is stored or a ref points at it.
449
+ #
450
+ # @param opts [Hash] options for the store
451
+ #
452
+ # @option opts [String] :message (nil) the message for the stash entry
453
+ # (alias: `:m`)
454
+ #
455
+ # @option opts [String] :m (nil) alias for `:message`
456
+ #
457
+ # @option opts [Boolean, nil] :quiet (nil) suppress informational
458
+ # messages (alias: `:q`)
459
+ #
460
+ # @option opts [Boolean, nil] :q (nil) alias for `:quiet`
461
+ #
462
+ # @return [Git::StashInfo] the stored entry
463
+ #
464
+ # @raise [ArgumentError] if unsupported options are provided
465
+ #
466
+ # @raise [ArgumentError] if `commit` is `nil` or starts with a hyphen or a
467
+ # caret
468
+ #
469
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
470
+ #
471
+ # @raise [Git::UnexpectedResultError] if the stash listing cannot be parsed
472
+ # or does not contain the stored commit
473
+ #
474
+ # The entry is missing when another process dropped or cleared it between
475
+ # the store and the lookup.
476
+ #
477
+ # @note Storing the commit that is already at the top of the stash list
478
+ # adds no entry: `git stash store` writes nothing to the `refs/stash`
479
+ # reflog, any `:message` given is discarded, and the existing top entry
480
+ # is returned.
481
+ #
482
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
483
+ #
484
+ def stash_store(commit, opts = {})
485
+ SharedPrivate.assert_valid_opts!(STASH_STORE_ALLOWED_OPTS, **opts)
486
+ oid = Private.resolve_commit_oid(@execution_context, commit)
487
+ Git::Commands::Stash::Store.new(@execution_context).call(oid, **opts)
488
+ stash_list.find { |entry| entry.oid == oid } ||
489
+ raise(Git::UnexpectedResultError, "stash was stored but not found in the stash list: #{oid}")
490
+ end
491
+
492
+ # Remove all stash entries
493
+ #
494
+ # Removes all entries from the stash list. Use with caution as this
495
+ # operation cannot be undone.
496
+ #
497
+ # @example Clear all stashes
498
+ # repo.stash_clear #=> ""
499
+ #
500
+ # @return [String] the output from the git stash clear command
501
+ # (typically empty)
502
+ #
503
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
504
+ #
505
+ # @see https://git-scm.com/docs/git-stash git-stash documentation
506
+ #
507
+ def stash_clear
508
+ Git::Commands::Stash::Clear.new(@execution_context).call.stdout
509
+ end
510
+
511
+ # Private helpers local to {Git::Repository::Stashing}
512
+ #
513
+ # @api private
514
+ #
515
+ module Private
516
+ module_function
517
+
518
+ # Resolve a commit-ish to the full object id of the commit it names
519
+ #
520
+ # The revision is peeled with `git rev-parse --verify <commit>^{commit}`,
521
+ # so an annotated tag yields the tagged commit, an abbreviated or uppercase
522
+ # id yields the full lowercase id, and an id that names no object fails
523
+ # (a bare `--verify <id>` echoes a well-formed id back without looking it
524
+ # up). A `:/<text>` search consumes the rest of the revision string, so it
525
+ # is passed without the suffix; such a search only ever names a commit.
526
+ # {Git::Repository::ObjectOperations#rev_parse} is not used because it
527
+ # runs `--revs-only`, which prints both ends of a range and exits zero
528
+ # instead of failing.
529
+ #
530
+ # {Git::Commands::RevParse} places its operand after `--end-of-options`,
531
+ # so the arguments DSL does not reject a `nil` or option-like operand, and
532
+ # `--verify` accepts a negated revision such as `^HEAD` and prints the id
533
+ # back with its caret. This method raises `ArgumentError` for all three
534
+ # before running git.
535
+ #
536
+ # @example With an annotated tag
537
+ # Private.resolve_commit_oid(execution_context, 'v1.0.0')
538
+ # #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
539
+ #
540
+ # @example With a range
541
+ # Private.resolve_commit_oid(execution_context, 'main..topic')
542
+ # #=> raises Git::FailedError
543
+ #
544
+ # @param execution_context [Git::ExecutionContext] the context to run git in
545
+ #
546
+ # @param commit [String, #to_s] a revision that resolves to a commit or
547
+ # peels to one
548
+ #
549
+ # @return [String] the full object id of the commit
550
+ #
551
+ # @raise [ArgumentError] if `commit` is `nil` or starts with a hyphen or a
552
+ # caret
553
+ #
554
+ # @raise [Git::FailedError] when `commit` does not resolve to a single
555
+ # revision or does not peel to a commit
556
+ #
557
+ def resolve_commit_oid(execution_context, commit)
558
+ raise ArgumentError, 'commit is required' if commit.nil?
559
+
560
+ commit = commit.to_s
561
+ raise ArgumentError, "Invalid commit: '#{commit}'" if commit.start_with?('-', '^')
562
+
563
+ revision = commit.start_with?(':/') ? commit : "#{commit}^{commit}"
564
+ Git::Commands::RevParse.new(execution_context).call(revision, verify: true).stdout.strip
565
+ end
566
+
567
+ # Separate the stash operand from a positional options Hash
568
+ #
569
+ # The stash-taking facade methods are declared `(stash = nil, opts = {})`.
570
+ # When the caller omits the stash and passes only options
571
+ # (`repo.stash_apply(index: true)`), Ruby binds the Hash to `stash`; this
572
+ # moves it to `opts` so both call shapes reach the command the same way.
573
+ #
574
+ # @example Options passed without a stash
575
+ # Private.split_stash_and_opts({ index: true }, {}) #=> [nil, { index: true }]
576
+ #
577
+ # @example A stash and options
578
+ # Private.split_stash_and_opts('stash@{1}', { index: true }) #=> ["stash@{1}", { index: true }]
579
+ #
580
+ # @param stash [Git::StashInfo, String, Integer, Hash, nil] the stash
581
+ # operand, or the options Hash when the stash was omitted
582
+ #
583
+ # @param trailing [Hash] the second positional argument as bound by Ruby
584
+ #
585
+ # @return [Array(Object, Hash)] the stash operand and the options Hash
586
+ #
587
+ def split_stash_and_opts(stash, trailing)
588
+ return [nil, stash] if stash.is_a?(Hash) && trailing.empty?
589
+
590
+ [stash, trailing]
591
+ end
592
+
593
+ # Separate a trailing options Hash from a pathspec list
594
+ #
595
+ # {Git::Repository::Stashing#stash_push} takes a variadic pathspec, so
596
+ # its options arrive as the last positional argument when present.
597
+ #
598
+ # @example Pathspecs followed by options
599
+ # Private.split_pathspec_and_opts(['a.rb', { message: 'WIP' }])
600
+ # #=> [["a.rb"], { message: "WIP" }]
601
+ #
602
+ # @example Pathspecs only
603
+ # Private.split_pathspec_and_opts(['a.rb']) #=> [["a.rb"], {}]
604
+ #
605
+ # @param pathspec [Array<String, Hash>] the positional arguments, possibly
606
+ # ending in an options Hash
607
+ #
608
+ # @return [Array(Array<String>, Hash)] the pathspecs and the options Hash
609
+ #
610
+ def split_pathspec_and_opts(pathspec)
611
+ return [pathspec[0...-1], pathspec.last] if pathspec.last.is_a?(Hash)
612
+
613
+ [pathspec, {}]
614
+ end
615
+ end
616
+ private_constant :Private
617
+ end
618
+ end
619
+ end