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,120 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Git
4
+ class Repository
5
+ # Internal helpers shared by `Git::Repository::*` topic modules
6
+ #
7
+ # Methods defined here use `module_function` so they are callable as
8
+ # `SharedPrivate.foo(...)` from any topic module within `Git::Repository`
9
+ # without being added to `Git::Repository`'s instance namespace via `include`.
10
+ #
11
+ # The constant is declared `private_constant` so it is inaccessible from
12
+ # outside the `Git::Repository` class body; callers inside topic modules use
13
+ # the short unqualified form `SharedPrivate.foo(...)`.
14
+ #
15
+ # @api private
16
+ #
17
+ module SharedPrivate
18
+ module_function
19
+
20
+ # Validate that candidate option keys are listed in `allowed`
21
+ #
22
+ # Used by facade methods to enforce that only documented options (those
23
+ # named in `@option` tags) are accepted, even when the underlying command
24
+ # class would accept more keys. This prevents silent expansion of the
25
+ # facade's public contract.
26
+ #
27
+ # @example Reject an undocumented option
28
+ # ADD_ALLOWED_OPTS = %i[all force].freeze
29
+ #
30
+ # SharedPrivate.assert_valid_opts!(ADD_ALLOWED_OPTS, bogus: true)
31
+ # #=> raises ArgumentError: Unknown options: bogus
32
+ #
33
+ # @param allowed [Array<Symbol>] the keys permitted by the facade method
34
+ #
35
+ # @param candidate_keywords [Hash<Symbol, Object>] the keywords to validate
36
+ #
37
+ # @option candidate_keywords [Object] key_name a candidate keyword value
38
+ #
39
+ # @return [void]
40
+ #
41
+ # @raise [ArgumentError] when any candidate key is not in `allowed`
42
+ #
43
+ def assert_valid_opts!(allowed, **candidate_keywords)
44
+ unknown = candidate_keywords.keys - allowed
45
+ return if unknown.empty?
46
+
47
+ raise ArgumentError, "Unknown options: #{unknown.join(', ')}"
48
+ end
49
+
50
+ # Raise unless `branch` names an existing local branch
51
+ #
52
+ # Used by facade methods that check out a branch, do work on it, and switch
53
+ # back. {Git::Repository#checkout} also accepts commit SHAs, tags, and
54
+ # remote-tracking branches, all of which detach HEAD; work committed there
55
+ # would be left dangling once the original branch is restored, and git has
56
+ # no way to report that.
57
+ #
58
+ # @example With an existing local branch
59
+ # SharedPrivate.assert_local_branch!(repo, 'feature') #=> nil
60
+ #
61
+ # @example With a tag
62
+ # SharedPrivate.assert_local_branch!(repo, 'v1.0.0')
63
+ # #=> raises ArgumentError: 'v1.0.0' is not an existing local branch
64
+ #
65
+ # @param repository [Git::Repository] the repository to check
66
+ #
67
+ # @param branch [String] the branch name to verify
68
+ #
69
+ # @return [void]
70
+ #
71
+ # @raise [ArgumentError] when `branch` is not an existing local branch
72
+ #
73
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
74
+ #
75
+ def assert_local_branch!(repository, branch)
76
+ return if repository.local_branch?(branch)
77
+
78
+ raise ArgumentError, "'#{branch}' is not an existing local branch"
79
+ end
80
+
81
+ # Returns a revision that restores the current HEAD after switching branches
82
+ #
83
+ # Used by facade methods that temporarily check out another branch and
84
+ # then switch back. On a branch, the branch name is enough. When HEAD is
85
+ # detached, {Git::Repository#current_branch} reports `'HEAD'`, which after
86
+ # a checkout resolves to the new branch rather than the original commit,
87
+ # so the commit SHA is captured instead. An unborn branch (one with no
88
+ # commits yet) has no ref to check out by name, so it is rejected here,
89
+ # before the caller switches away from it.
90
+ #
91
+ # @example On a branch
92
+ # SharedPrivate.head_restore_point(repo) #=> "main"
93
+ #
94
+ # @example With a detached HEAD
95
+ # SharedPrivate.head_restore_point(repo) #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
96
+ #
97
+ # @param repository [Git::Repository] the repository whose HEAD to record
98
+ #
99
+ # @return [String] the current branch name, or the full HEAD commit SHA
100
+ # when HEAD is detached
101
+ #
102
+ # @raise [Git::Error] when HEAD is on an unborn branch
103
+ #
104
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
105
+ #
106
+ def head_restore_point(repository)
107
+ head = repository.current_branch_state
108
+ case head.state
109
+ when :detached then repository.rev_parse('HEAD').strip
110
+ when :unborn
111
+ raise Git::Error, "HEAD is on the unborn branch '#{head.name}', which cannot be restored " \
112
+ 'after switching branches; make a commit on it first'
113
+ else head.name
114
+ end
115
+ end
116
+ end
117
+
118
+ private_constant :SharedPrivate
119
+ end
120
+ end
@@ -0,0 +1,409 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/add'
4
+ require 'git/commands/am/apply'
5
+ require 'git/commands/apply'
6
+ require 'git/commands/clean'
7
+ require 'git/commands/ls_files'
8
+ require 'git/commands/mv'
9
+ require 'git/commands/read_tree'
10
+ require 'git/commands/reset'
11
+ require 'git/commands/rm'
12
+ require 'git/escaped_path'
13
+ require 'git/repository/shared_private'
14
+
15
+ module Git
16
+ class Repository
17
+ # Facade methods for staging-area operations: adding, resetting, moving,
18
+ # removing, and cleaning files
19
+ #
20
+ # Included by {Git::Repository}.
21
+ #
22
+ # @api private
23
+ #
24
+ module Staging
25
+ # Option keys accepted by {#add}
26
+ ADD_ALLOWED_OPTS = %i[all force].freeze
27
+ private_constant :ADD_ALLOWED_OPTS
28
+
29
+ # Update the index with the current content found in the working tree
30
+ #
31
+ # @overload add(paths = '.', **options)
32
+ #
33
+ # @example Stage all changed files
34
+ # repo.add
35
+ #
36
+ # @example Stage a specific file
37
+ # repo.add('README.md')
38
+ #
39
+ # @example Stage all changes including deletions
40
+ # repo.add(all: true)
41
+ #
42
+ # @param paths [String, Array<String>] a file or files to add (relative to
43
+ # the worktree root); defaults to `'.'` (all files)
44
+ #
45
+ # @param options [Hash] options for the add command
46
+ #
47
+ # @option options [Boolean, nil] :all (nil) add, modify, and remove index
48
+ # entries to match the worktree
49
+ #
50
+ # @option options [Boolean, nil] :force (nil) allow adding otherwise ignored
51
+ # files
52
+ #
53
+ # @return [String] git's stdout from the add
54
+ #
55
+ # @raise [ArgumentError] when unsupported options are provided
56
+ #
57
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
58
+ #
59
+ def add(paths = '.', **)
60
+ SharedPrivate.assert_valid_opts!(ADD_ALLOWED_OPTS, **)
61
+ Git::Commands::Add.new(@execution_context).call(*Array(paths), **).stdout
62
+ end
63
+
64
+ # Option keys accepted by {#reset}
65
+ RESET_ALLOWED_OPTS = %i[hard].freeze
66
+ private_constant :RESET_ALLOWED_OPTS
67
+
68
+ # Reset the current HEAD to a specified state
69
+ #
70
+ # @example Reset the index and working tree to HEAD
71
+ # repo.reset
72
+ #
73
+ # @example Hard reset to a specific commit
74
+ # repo.reset('HEAD~1', hard: true)
75
+ #
76
+ # @param commitish [String, nil] the commit or tree-ish to reset to;
77
+ # defaults to HEAD when `nil`
78
+ #
79
+ # @param opts [Hash] options for the reset command
80
+ #
81
+ # @option opts [Boolean, nil] :hard (nil) reset the index and working
82
+ # tree; discards all tracked changes
83
+ #
84
+ # @return [String] git's stdout from the reset
85
+ #
86
+ # @raise [ArgumentError] when unsupported options are provided
87
+ #
88
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
89
+ #
90
+ def reset(commitish = nil, opts = {})
91
+ SharedPrivate.assert_valid_opts!(RESET_ALLOWED_OPTS, **opts)
92
+ Git::Commands::Reset.new(@execution_context).call(commitish, **opts).stdout
93
+ end
94
+
95
+ # Apply a patch file to the working tree
96
+ #
97
+ # Reads the unified diff in `file` and applies it to the working tree via
98
+ # `git apply`. If `file` does not exist, the method returns `nil` without
99
+ # calling git — preserving the 4.x `Git::Base#apply` no-op contract.
100
+ #
101
+ # @example Apply a patch to the working tree
102
+ # repo.apply('fix.patch')
103
+ #
104
+ # @param file [String] path to the patch file to apply
105
+ #
106
+ # @return [String] git's stdout (usually empty on success)
107
+ #
108
+ # @return [nil] when `file` does not exist
109
+ #
110
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
111
+ #
112
+ def apply(file)
113
+ return unless File.exist?(file)
114
+
115
+ Git::Commands::Apply.new(@execution_context).call(file, chdir: @execution_context.git_work_dir).stdout
116
+ end
117
+
118
+ # Apply a series of patches from a mailbox file to the current branch
119
+ #
120
+ # Reads the mbox-format file in `file` and applies the patches via
121
+ # `git am`. If `file` does not exist, the method returns `nil` without
122
+ # calling git — preserving the 4.x `Git::Base#apply_mail` no-op contract.
123
+ #
124
+ # @example Apply patches from a mailbox
125
+ # repo.apply_mail('patches.mbox')
126
+ #
127
+ # @param file [String] path to the mbox patch file to apply
128
+ #
129
+ # @return [String] git's stdout (usually empty on success)
130
+ #
131
+ # @return [nil] when `file` does not exist
132
+ #
133
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
134
+ #
135
+ # @note If a patch fails to apply, the `git am` session is left in progress
136
+ # until the caller continues, skips, or aborts it. The patches applied
137
+ # before it are already committed on the current branch; aborting the
138
+ # session removes them again.
139
+ #
140
+ def apply_mail(file)
141
+ return unless File.exist?(file)
142
+
143
+ Git::Commands::Am::Apply.new(@execution_context).call(file, chdir: @execution_context.git_work_dir).stdout
144
+ end
145
+
146
+ # Option keys accepted by {#read_tree}
147
+ READ_TREE_ALLOWED_OPTS = %i[prefix].freeze
148
+ private_constant :READ_TREE_ALLOWED_OPTS
149
+
150
+ # Read tree information into the index
151
+ #
152
+ # Reads the named tree object into the index. This is a low-level plumbing
153
+ # operation used to stage the contents of a tree without updating the
154
+ # working tree. Typically called before {#checkout_index} or as part of
155
+ # custom merge flows.
156
+ #
157
+ # @example Read HEAD into the index
158
+ # repo.read_tree('HEAD')
159
+ #
160
+ # @example Read a tree under a prefix directory
161
+ # repo.read_tree('HEAD', { prefix: 'subdir/' })
162
+ #
163
+ # @param treeish [String] the tree-ish to read into the index
164
+ #
165
+ # @param opts [Hash] options for the read-tree command
166
+ #
167
+ # @option opts [String] :prefix (nil) keep the current index contents and
168
+ # read the named tree-ish under the directory at the given prefix
169
+ # (`--prefix=<prefix>`)
170
+ #
171
+ # @return [String] git's stdout (usually empty on success)
172
+ #
173
+ # @raise [ArgumentError] when unsupported options are provided
174
+ #
175
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
176
+ #
177
+ def read_tree(treeish, opts = {})
178
+ SharedPrivate.assert_valid_opts!(READ_TREE_ALLOWED_OPTS, **opts)
179
+ Git::Commands::ReadTree.new(@execution_context).call(treeish, **opts).stdout
180
+ end
181
+
182
+ # Option keys accepted by {#rm}
183
+ RM_ALLOWED_OPTS = %i[
184
+ force f dry_run n r cached ignore_unmatch sparse quiet q
185
+ pathspec_from_file pathspec_file_nul
186
+ ].freeze
187
+ private_constant :RM_ALLOWED_OPTS
188
+
189
+ # Remove file(s) from the working tree and the index
190
+ #
191
+ # @example Remove a single file
192
+ # repo.rm('obsolete.txt', { force: true })
193
+ #
194
+ # @example Remove a directory recursively
195
+ # repo.rm('build', { r: true })
196
+ #
197
+ # @example Remove from the index only, keeping the working tree copy
198
+ # repo.rm('keep_me.txt', { cached: true })
199
+ #
200
+ # @param path [String, Array<String>] a file or files to remove (relative to
201
+ # the worktree root); defaults to `'.'` (all files)
202
+ #
203
+ # @param opts [Hash] options for the rm command
204
+ #
205
+ # @option opts [Boolean, nil] :force (nil) override the up-to-date check and
206
+ # remove files with local modifications (alias: `:f`)
207
+ #
208
+ # @option opts [Boolean, nil] :f (nil) alias for `:force`
209
+ #
210
+ # @option opts [Boolean, nil] :dry_run (nil) do not actually remove any files;
211
+ # only show what would be removed (alias: `:n`)
212
+ #
213
+ # @option opts [Boolean, nil] :n (nil) alias for `:dry_run`
214
+ #
215
+ # @option opts [Boolean, nil] :r (nil) allow recursive removal when a leading
216
+ # directory name is given
217
+ #
218
+ # @option opts [Boolean, nil] :cached (nil) only remove from the index, keeping
219
+ # the working tree files
220
+ #
221
+ # @option opts [Boolean, nil] :ignore_unmatch (nil) exit with a zero status even
222
+ # if no files matched
223
+ #
224
+ # @option opts [Boolean, nil] :sparse (nil) allow updating index entries outside
225
+ # of the sparse-checkout cone
226
+ #
227
+ # @option opts [Boolean, nil] :quiet (nil) suppress the one-line-per-file output
228
+ # (alias: `:q`)
229
+ #
230
+ # @option opts [Boolean, nil] :q (nil) alias for `:quiet`
231
+ #
232
+ # @option opts [String] :pathspec_from_file (nil) read pathspec from the given
233
+ # file, one pathspec element per line; pass `-` to read from standard input
234
+ #
235
+ # @option opts [Boolean, nil] :pathspec_file_nul (nil) when used with
236
+ # `:pathspec_from_file`, separate pathspec elements with NUL instead of newlines
237
+ #
238
+ # @return [String] git's stdout from the rm
239
+ #
240
+ # @raise [ArgumentError] when unsupported options are provided
241
+ #
242
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
243
+ #
244
+ def rm(path = '.', opts = {})
245
+ SharedPrivate.assert_valid_opts!(RM_ALLOWED_OPTS, **opts)
246
+ Git::Commands::Rm.new(@execution_context).call(*Array(path), **opts).stdout
247
+ end
248
+
249
+ alias remove rm
250
+
251
+ # Option keys accepted by {#mv}
252
+ MV_ALLOWED_OPTS = %i[force f dry_run n k].freeze
253
+ private_constant :MV_ALLOWED_OPTS
254
+
255
+ # Move or rename a file, directory, or symlink in the working tree
256
+ #
257
+ # Updates the index after successful completion, but the change must still
258
+ # be committed.
259
+ #
260
+ # @example Move a single file
261
+ # repo.mv('old.rb', 'new.rb')
262
+ #
263
+ # @example Move multiple files to a directory
264
+ # repo.mv(['file1.rb', 'file2.rb'], 'destination_dir/')
265
+ #
266
+ # @example Force overwrite if destination exists
267
+ # repo.mv('source.rb', 'dest.rb', force: true)
268
+ #
269
+ # @param source [String, Array<String>] one or more source file(s),
270
+ # directory(ies), or symlink(s) to move (relative to the worktree root)
271
+ #
272
+ # @param destination [String] the destination file or directory
273
+ #
274
+ # @param options [Hash] options for the mv command
275
+ #
276
+ # @option options [Boolean, nil] :force (nil) force renaming or moving even
277
+ # if the destination exists (alias: `:f`)
278
+ #
279
+ # @option options [Boolean, nil] :f (nil) alias for `:force`
280
+ #
281
+ # @option options [Boolean, nil] :dry_run (nil) do not actually move any
282
+ # files; only show what would happen (alias: `:n`)
283
+ #
284
+ # @option options [Boolean, nil] :n (nil) alias for `:dry_run`
285
+ #
286
+ # @option options [Boolean, nil] :k (nil) skip move or rename actions which
287
+ # would lead to an error
288
+ #
289
+ # @return [String] git's stdout from the mv command
290
+ #
291
+ # @raise [ArgumentError] when unsupported options are provided
292
+ #
293
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
294
+ #
295
+ def mv(source, destination, options = {})
296
+ SharedPrivate.assert_valid_opts!(MV_ALLOWED_OPTS, **options)
297
+ Git::Commands::Mv.new(@execution_context).call(*Array(source), destination, verbose: true, **options).stdout
298
+ end
299
+
300
+ # Option keys accepted by {#clean}
301
+ CLEAN_ALLOWED_OPTS = %i[d force f dry_run n quiet q exclude e x X pathspec].freeze
302
+ private_constant :CLEAN_ALLOWED_OPTS
303
+
304
+ # Remove untracked files from the working tree
305
+ #
306
+ # @example Remove untracked files
307
+ # repo.clean({ force: true })
308
+ #
309
+ # @example Remove untracked files and directories
310
+ # repo.clean({ force: true, d: true })
311
+ #
312
+ # @example Remove untracked and ignored files
313
+ # repo.clean({ force: true, x: true })
314
+ #
315
+ # @param opts [Hash] options for the clean command
316
+ #
317
+ # @option opts [Boolean, nil] :d (nil) recurse into untracked directories
318
+ #
319
+ # @option opts [Boolean, Integer, nil] :force (nil) force the removal of
320
+ # untracked files; pass `2` to also remove untracked nested git repositories
321
+ # (alias: `:f`)
322
+ #
323
+ # @option opts [Boolean, Integer, nil] :f (nil) alias for `:force`
324
+ #
325
+ # @option opts [Boolean, nil] :dry_run (nil) do not actually remove anything,
326
+ # just show what would be done (alias: `:n`)
327
+ #
328
+ # @option opts [Boolean, nil] :n (nil) alias for `:dry_run`
329
+ #
330
+ # @option opts [Boolean, nil] :quiet (nil) be quiet, only report errors
331
+ # (alias: `:q`)
332
+ #
333
+ # @option opts [Boolean, nil] :q (nil) alias for `:quiet`
334
+ #
335
+ # @option opts [String, Array<String>] :exclude (nil) use the given exclude
336
+ # pattern in addition to the standard ignore rules (alias: `:e`)
337
+ #
338
+ # @option opts [String, Array<String>] :e (nil) alias for `:exclude`
339
+ #
340
+ # @option opts [Boolean, nil] :x (nil) don't use the standard ignore rules
341
+ #
342
+ # @option opts [Boolean, nil] :X (nil) remove only files ignored by git
343
+ #
344
+ # @option opts [String, Array<String>] :pathspec (nil) limit cleaning to files
345
+ # matching the given pathspec(s)
346
+ #
347
+ # @return [String] git's stdout from the clean
348
+ #
349
+ # @raise [ArgumentError] when unsupported options are provided
350
+ #
351
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
352
+ #
353
+ def clean(opts = {})
354
+ SharedPrivate.assert_valid_opts!(CLEAN_ALLOWED_OPTS, **opts)
355
+ Git::Commands::Clean.new(@execution_context).call(**opts).stdout
356
+ end
357
+
358
+ # List the files in the working tree that are ignored by git
359
+ #
360
+ # Runs `git ls-files --others --ignored --exclude-standard` and returns the
361
+ # ignored files as repository-relative paths.
362
+ #
363
+ # @example List ignored files
364
+ # repo.ignored_files #=> ["coverage/index.html", "tmp/cache.db"]
365
+ #
366
+ # @example No ignored files
367
+ # repo.ignored_files #=> []
368
+ #
369
+ # @return [Array<String>] repository-relative paths of ignored files; empty
370
+ # when there are none
371
+ #
372
+ # @raise [Git::FailedError] when git exits with a non-zero exit status
373
+ #
374
+ def ignored_files
375
+ Git::Commands::LsFiles.new(@execution_context).call(
376
+ others: true, ignored: true, exclude_standard: true
377
+ ).stdout.split("\n").map { |f| Private.unescape_quoted_path(f) }
378
+ end
379
+
380
+ # Private helpers local to {Git::Repository::Staging}
381
+ #
382
+ # @api private
383
+ #
384
+ module Private
385
+ module_function
386
+
387
+ # Unescape a git-quoted path
388
+ #
389
+ # Git wraps paths containing non-ASCII or special characters in
390
+ # double-quotes and octal-escapes each byte. This method strips the
391
+ # surrounding quotes and delegates unescaping to {Git::EscapedPath}.
392
+ #
393
+ # @param path [String] the path as it appears in git output
394
+ #
395
+ # @return [String] the unescaped path
396
+ #
397
+ def unescape_quoted_path(path)
398
+ if path.start_with?('"') && path.end_with?('"')
399
+ Git::EscapedPath.new(path[1..-2]).unescape
400
+ else
401
+ path
402
+ end
403
+ end
404
+ end
405
+
406
+ private_constant :Private
407
+ end
408
+ end
409
+ end