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,796 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'pathname'
4
+ require 'git/branch_info'
5
+ require 'git/commands/branch/create'
6
+ require 'git/commands/branch/delete'
7
+ require 'git/commands/branch/list'
8
+ require 'git/commands/branch/show_current'
9
+ require 'git/commands/checkout/branch'
10
+ require 'git/commands/checkout/files'
11
+ require 'git/commands/checkout_index'
12
+ require 'git/commands/rev_parse'
13
+ require 'git/commands/update_ref/update'
14
+ require 'git/commands/symbolic_ref/update'
15
+ require 'git/parsers/branch'
16
+ require 'git/repository/shared_private'
17
+
18
+ module Git
19
+ class Repository
20
+ # Facade methods for branching operations: creating, checking out, querying,
21
+ # deleting, and updating branches
22
+ #
23
+ # Included by {Git::Repository}.
24
+ #
25
+ # @api private
26
+ #
27
+ module Branching # rubocop:disable Metrics/ModuleLength
28
+ # Represents the state of HEAD in a repository
29
+ #
30
+ # @api private
31
+ #
32
+ # @!attribute [r] state
33
+ # @return [Symbol] one of `:active`, `:unborn`, or `:detached`
34
+ #
35
+ # @!attribute [r] name
36
+ # @return [String] the branch name, or `'HEAD'` when detached
37
+ #
38
+ HeadState = Data.define(:state, :name)
39
+
40
+ # Option keys accepted by {#checkout}
41
+ #
42
+ CHECKOUT_ALLOWED_OPTS = %i[force f new_branch b start_point orphan].freeze
43
+ private_constant :CHECKOUT_ALLOWED_OPTS
44
+
45
+ # Option keys accepted by {#checkout_index}
46
+ #
47
+ CHECKOUT_INDEX_ALLOWED_OPTS = %i[prefix force all path_limiter].freeze
48
+ private_constant :CHECKOUT_INDEX_ALLOWED_OPTS
49
+
50
+ # Returns the name of the current branch
51
+ #
52
+ # @example Get the current branch name
53
+ # repo.current_branch # => "main"
54
+ #
55
+ # @example In detached HEAD state
56
+ # repo.current_branch # => "HEAD"
57
+ #
58
+ # @return [String] the current branch name, or `'HEAD'` when in detached
59
+ # HEAD state
60
+ #
61
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
62
+ #
63
+ def current_branch
64
+ result = Git::Commands::Branch::ShowCurrent.new(@execution_context).call
65
+ name = result.stdout.strip
66
+ name.empty? ? 'HEAD' : name
67
+ end
68
+
69
+ # Returns the current HEAD state as a structured value object
70
+ #
71
+ # HEAD can be in one of three states:
72
+ #
73
+ # - **`:active`** — HEAD points to a branch ref that has at least one commit.
74
+ # - **`:unborn`** — HEAD points to a branch ref that has been created but has
75
+ # no commits yet (e.g. immediately after `git init` before any commit).
76
+ # - **`:detached`** — HEAD points directly to a commit SHA rather than a branch.
77
+ #
78
+ # @example Active branch
79
+ # repo.current_branch_state
80
+ # # => #<data Git::Repository::Branching::HeadState state=:active, name="main">
81
+ #
82
+ # @example Unborn branch (no commits yet)
83
+ # repo.current_branch_state
84
+ # # => #<data Git::Repository::Branching::HeadState state=:unborn, name="main">
85
+ #
86
+ # @example Detached HEAD
87
+ # repo.current_branch_state
88
+ # # => #<data Git::Repository::Branching::HeadState state=:detached, name="HEAD">
89
+ #
90
+ # @return [Git::Repository::Branching::HeadState] the current HEAD state
91
+ #
92
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
93
+ #
94
+ def current_branch_state
95
+ branch_name = Git::Commands::Branch::ShowCurrent.new(@execution_context).call.stdout.strip
96
+ return HeadState.new(state: :detached, name: 'HEAD') if branch_name.empty?
97
+
98
+ state = Private.get_branch_state(@execution_context, branch_name)
99
+ HeadState.new(state: state, name: branch_name)
100
+ end
101
+
102
+ # Restore working tree files from a tree-ish
103
+ #
104
+ # @example Restore README.md to its HEAD state
105
+ # repo.checkout_file('HEAD', 'README.md')
106
+ #
107
+ # @param version [String] the tree-ish (branch, tag, commit SHA, etc.) to
108
+ # restore the file from
109
+ #
110
+ # @param file [String] the path to the file to restore
111
+ #
112
+ # @return [String] git's stdout from the checkout
113
+ #
114
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
115
+ #
116
+ def checkout_file(version, file)
117
+ Git::Commands::Checkout::Files.new(@execution_context).call(version, pathspec: [file]).stdout
118
+ end
119
+
120
+ # Switch branches or restore working tree files
121
+ #
122
+ # @example Check out an existing branch
123
+ # repo.checkout('main')
124
+ #
125
+ # @example Create and check out a new branch from main
126
+ # repo.checkout('new-feature', new_branch: true, start_point: 'main')
127
+ #
128
+ # @example Create a new branch with a name different from the start point
129
+ # repo.checkout('main', new_branch: 'new-feature')
130
+ #
131
+ # @example Create and check out an unborn branch with no history
132
+ # repo.checkout('gh-pages', orphan: true)
133
+ #
134
+ # @example Force checkout discarding local changes
135
+ # repo.checkout('main', force: true)
136
+ #
137
+ # @param branch [String, nil] the branch to check out; defaults to nil
138
+ # (i.e. restore HEAD state)
139
+ #
140
+ # @param opts [Hash] options for the checkout command
141
+ #
142
+ # @option opts [Boolean, nil] :force (nil) discard local changes when
143
+ # switching branches
144
+ #
145
+ # @option opts [Boolean, String, nil] :new_branch (nil) when `true`,
146
+ # creates a new branch named `branch` from `:start_point`
147
+ #
148
+ # When a `String`, creates a new branch with that name, using `branch`
149
+ # as the start point.
150
+ #
151
+ # @option opts [Boolean, String, nil] :b (nil) alias for `:new_branch`
152
+ #
153
+ # @option opts [Boolean, nil] :f (nil) alias for `:force`
154
+ #
155
+ # @option opts [Boolean, String, nil] :orphan (nil) when `true`, creates a
156
+ # new unborn branch named `branch` whose first commit has no parents
157
+ #
158
+ # When a `String`, creates an unborn branch with that name, using
159
+ # `branch` as the start point for the working tree and index.
160
+ #
161
+ # `false` and `nil` are both treated as unset. A blank branch name is
162
+ # rejected rather than ignored.
163
+ #
164
+ # @option opts [String, nil] :start_point (nil) the commit or branch to
165
+ # start the new branch from; used together with `new_branch: true` or
166
+ # `orphan: true`
167
+ #
168
+ # @return [String] git's stdout from the checkout
169
+ #
170
+ # @raise [ArgumentError] if unsupported options are provided
171
+ #
172
+ # @raise [ArgumentError] if `:orphan` is given a blank or missing branch name
173
+ #
174
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
175
+ #
176
+ # @note A refused checkout leaves HEAD, the index, and the working tree as
177
+ # they were, and the branch `:new_branch` or `:orphan` names is not
178
+ # created.
179
+ #
180
+ def checkout(branch = nil, opts = {})
181
+ if branch.is_a?(Hash) && opts.empty?
182
+ opts = branch
183
+ branch = nil
184
+ end
185
+
186
+ SharedPrivate.assert_valid_opts!(CHECKOUT_ALLOWED_OPTS, **opts)
187
+
188
+ target, translated_opts = Private.translate_checkout_opts(branch, opts)
189
+ Git::Commands::Checkout::Branch.new(@execution_context).call(target, **translated_opts).stdout
190
+ end
191
+
192
+ # Run a block with the given branch checked out, then restore the original branch
193
+ #
194
+ # Records the current branch (or the current commit when HEAD is detached),
195
+ # checks out `branch`, and yields to the block. If the block returns a truthy
196
+ # value, all pending changes are committed with `message` (see
197
+ # {#commit_all}); if it returns a falsy value, the index and working tree are
198
+ # hard-reset instead (see {#reset}). The original branch or commit is then
199
+ # checked out again. The hard reset discards changes to tracked files only;
200
+ # untracked files created by the block are left in place.
201
+ #
202
+ # This method does not create `branch`: it must be an existing local
203
+ # branch. Unlike {#checkout}, a commit SHA, tag, or remote-tracking branch
204
+ # is rejected before any checkout happens: those detach HEAD, and a commit
205
+ # made there would be left dangling once the original branch is restored.
206
+ # HEAD must be on a branch with at least one commit, or detached: an unborn
207
+ # branch (no commits yet) cannot be checked out again by name, so it is
208
+ # rejected before any checkout happens.
209
+ #
210
+ # @example Commit a new file on a feature branch
211
+ # repo.in_branch('feature', 'Add README') do
212
+ # File.write('README.md', '# Hello')
213
+ # repo.add('README.md')
214
+ # true # commit and return to the original branch
215
+ # end
216
+ #
217
+ # @example Discard experimental changes to a tracked file
218
+ # repo.in_branch('scratch') do
219
+ # File.write('README.md', '# Try something')
220
+ # false # hard-reset and return to the original branch
221
+ # end
222
+ #
223
+ # @param branch [String] the name of an existing local branch to check out
224
+ #
225
+ # @param message [String] the commit message used when the block returns a
226
+ # truthy value
227
+ #
228
+ # @return [String] git's stdout from the final checkout back to the original
229
+ # branch or commit
230
+ #
231
+ # @raise [ArgumentError] if `branch` is not an existing local branch
232
+ #
233
+ # @raise [Git::Error] if HEAD is on an unborn branch
234
+ #
235
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
236
+ #
237
+ # @yield executes the block with `branch` checked out
238
+ #
239
+ # @yieldreturn [Object] a truthy value to commit all changes, a falsy value to
240
+ # hard-reset
241
+ #
242
+ # @note If the block, the commit, the reset, or the restore checkout raises
243
+ # an exception, the repository is left checked out on `branch` rather than
244
+ # restored to the original branch. When the restore checkout is the step
245
+ # that fails, the commit or reset has already run.
246
+ #
247
+ def in_branch(branch, message = 'in branch work')
248
+ SharedPrivate.assert_local_branch!(self, branch)
249
+ restore_point = SharedPrivate.head_restore_point(self)
250
+ checkout(branch)
251
+ if yield
252
+ commit_all(message)
253
+ else
254
+ reset(nil, hard: true)
255
+ end
256
+ # Runs only on success. See ADR-0009.
257
+ checkout(restore_point)
258
+ end
259
+
260
+ # Populate the working tree from the index
261
+ #
262
+ # @example Check out all files from the index
263
+ # repo.checkout_index(all: true)
264
+ #
265
+ # @example Force check out a specific file
266
+ # repo.checkout_index(force: true, path_limiter: 'README.md')
267
+ #
268
+ # @example Check out files to a staging prefix
269
+ # repo.checkout_index(prefix: 'tmp/stage/', all: true)
270
+ #
271
+ # @param options [Hash] options for the checkout-index command
272
+ #
273
+ # @option options [Boolean, nil] :all (nil) check out all files in the index
274
+ #
275
+ # @option options [Boolean, nil] :force (nil) overwrite existing files
276
+ #
277
+ # @option options [String, nil] :prefix (nil) write files under this path prefix
278
+ # rather than the working directory root
279
+ #
280
+ # @option options [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
281
+ # limit the check out to the given path(s)
282
+ #
283
+ # @return [String] git's stdout from the checkout-index command
284
+ #
285
+ # @raise [ArgumentError] if unsupported options are provided
286
+ #
287
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
288
+ #
289
+ # @note git does not stop at the first path it cannot write, so a failure
290
+ # leaves the files it did write in place, under `:prefix` when one is
291
+ # given.
292
+ #
293
+ def checkout_index(options = {})
294
+ SharedPrivate.assert_valid_opts!(CHECKOUT_INDEX_ALLOWED_OPTS, **options)
295
+
296
+ paths = Private.normalize_pathspecs(options[:path_limiter], 'path_limiter')
297
+ keyword_opts = options.except(:path_limiter)
298
+ Git::Commands::CheckoutIndex.new(@execution_context).call(*paths.to_a, **keyword_opts).stdout
299
+ end
300
+
301
+ # Returns `true` if the named branch exists as a local branch
302
+ #
303
+ # @example Check whether main exists locally
304
+ # repo.local_branch?('main') # => true
305
+ #
306
+ # @param branch [String] the local branch name to look up
307
+ #
308
+ # @return [Boolean] `true` if the branch exists locally, `false` otherwise
309
+ #
310
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
311
+ #
312
+ def local_branch?(branch)
313
+ result = Git::Commands::Branch::List.new(@execution_context).call(branch, format: '%(refname:short)')
314
+ result.stdout.chomp == branch
315
+ end
316
+
317
+ # Returns `true` if the named branch exists as a remote-tracking branch
318
+ #
319
+ # The `branch` argument must be the **short branch name** (e.g. `'master'`),
320
+ # not the combined `remote/branch` form (e.g. `'origin/master'`).
321
+ #
322
+ # @example Check whether master exists on any remote
323
+ # repo.remote_branch?('master') # => true
324
+ #
325
+ # @param branch [String] the short branch name to look up across all remotes
326
+ #
327
+ # @return [Boolean] `true` if a remote-tracking branch with that short name
328
+ # exists, `false` otherwise
329
+ #
330
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
331
+ #
332
+ def remote_branch?(branch)
333
+ result = Git::Commands::Branch::List.new(@execution_context)
334
+ .call("*/#{branch}", remotes: true, format: '%(refname:lstrip=3)')
335
+ result.stdout.each_line.any? { |line| line.chomp == branch }
336
+ end
337
+
338
+ # Returns `true` if the named branch exists locally or as a remote-tracking branch
339
+ #
340
+ # @example Check whether main exists anywhere
341
+ # repo.branch?('main') # => true
342
+ #
343
+ # @param branch [String] the branch name to look up
344
+ #
345
+ # @return [Boolean] `true` if the branch exists locally or remotely,
346
+ # `false` otherwise
347
+ #
348
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
349
+ #
350
+ def branch?(branch)
351
+ local_branch?(branch) || remote_branch?(branch)
352
+ end
353
+
354
+ # Option keys accepted by {#branch_new}
355
+ #
356
+ BRANCH_NEW_ALLOWED_OPTS = %i[].freeze
357
+ private_constant :BRANCH_NEW_ALLOWED_OPTS
358
+
359
+ # Create a new branch
360
+ #
361
+ # @example Create a new branch from the current HEAD
362
+ # repo.branch_new('feature')
363
+ #
364
+ # @example Create a new branch from a specific commit or branch
365
+ # repo.branch_new('feature', 'main')
366
+ #
367
+ # @param branch [String] the name of the branch to create
368
+ #
369
+ # @param start_point [String, nil] the commit, branch, or tag to start the
370
+ # new branch from; defaults to the current HEAD when `nil`
371
+ #
372
+ # @param branch_options [Hash] reserved; must be empty — no options are currently
373
+ # supported
374
+ #
375
+ # @return [void]
376
+ #
377
+ # @raise [ArgumentError] if unsupported options are provided
378
+ #
379
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
380
+ #
381
+ def branch_new(branch, start_point = nil, branch_options = {})
382
+ if start_point.is_a?(Hash) && branch_options.empty?
383
+ branch_options = start_point
384
+ start_point = nil
385
+ end
386
+
387
+ SharedPrivate.assert_valid_opts!(BRANCH_NEW_ALLOWED_OPTS, **branch_options)
388
+ Git::Commands::Branch::Create.new(@execution_context).call(branch, start_point, **branch_options)
389
+
390
+ nil
391
+ end
392
+
393
+ # Option keys accepted by {#branch_delete}
394
+ #
395
+ BRANCH_DELETE_ALLOWED_OPTS = %i[force remotes].freeze
396
+ private_constant :BRANCH_DELETE_ALLOWED_OPTS
397
+
398
+ # Delete one or more local or remote-tracking branches
399
+ #
400
+ # @example Delete a single branch
401
+ # repo.branch_delete('feature') # => "Deleted branch feature (was abc1234)."
402
+ #
403
+ # @example Delete multiple branches at once
404
+ # repo.branch_delete('feature-1', 'feature-2')
405
+ #
406
+ # @example Force-delete an unmerged branch
407
+ # repo.branch_delete('unmerged-branch', force: true)
408
+ #
409
+ # @example Delete a remote-tracking branch
410
+ # repo.branch_delete('origin/feature', remotes: true)
411
+ #
412
+ # @param branches [Array<String>] the name(s) of the branch(es) to delete
413
+ #
414
+ # @param options [Hash] options for the delete command
415
+ #
416
+ # @option options [Boolean, nil] :force (true) allow deleting the branch
417
+ # irrespective of its merged status
418
+ #
419
+ # Defaults to `true` to match the 4.x behavior.
420
+ #
421
+ # @option options [Boolean, nil] :remotes (nil) delete remote-tracking
422
+ # branches
423
+ #
424
+ # Use together with a `remote/branch` name.
425
+ #
426
+ # @return [String] the stdout output from the delete command, e.g.
427
+ # `"Deleted branch feature (was abc1234)."`
428
+ #
429
+ # @raise [ArgumentError] if unsupported options are provided
430
+ #
431
+ # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
432
+ #
433
+ # @raise [Git::Error] if git reports a deletion failure
434
+ #
435
+ def branch_delete(*branches, **options)
436
+ options = { force: true }.merge(options)
437
+ SharedPrivate.assert_valid_opts!(BRANCH_DELETE_ALLOWED_OPTS, **options)
438
+
439
+ result = Git::Commands::Branch::Delete.new(@execution_context).call(*branches, **options)
440
+
441
+ raise Git::Error, result.stderr.strip unless result.status.success?
442
+
443
+ result.stdout.strip
444
+ end
445
+
446
+ # Writes the HEAD symbolic ref to point at the given branch
447
+ #
448
+ # Sets `HEAD` to `refs/heads/<branch_name>` via `git symbolic-ref`. This is
449
+ # equivalent to running `git symbolic-ref HEAD refs/heads/<branch_name>` on
450
+ # the command line and is the mechanism git uses internally for branch
451
+ # renaming and orphan-branch checkout.
452
+ #
453
+ # @example Change HEAD to point to an existing branch
454
+ # repo.change_head_branch('main')
455
+ #
456
+ # @example Initialize a repository with a custom default branch name (unborn-branch pattern)
457
+ # repo = Git.init('/path/to/repo')
458
+ # repo.change_head_branch('my-branch')
459
+ # # HEAD now points at refs/heads/my-branch before any commits exist
460
+ #
461
+ # @param branch_name [String] the branch name to point HEAD at
462
+ #
463
+ # @return [void]
464
+ #
465
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
466
+ #
467
+ # @note Pointing HEAD at a branch that does not yet exist places the
468
+ # repository in unborn-branch state. This is intentional for repository
469
+ # initialization workflows — for example, setting a custom default branch
470
+ # name before any commits land — but is unexpected if done by mistake.
471
+ # The repository will appear to have no commits until the first commit is
472
+ # made on the new branch.
473
+ #
474
+ def change_head_branch(branch_name)
475
+ Git::Commands::SymbolicRef::Update.new(@execution_context).call('HEAD', "refs/heads/#{branch_name}")
476
+ nil
477
+ end
478
+
479
+ # Returns the `git branch --list --contains` stdout for a given commit
480
+ #
481
+ # The output format is the human-readable `git branch` listing: each
482
+ # matching branch name appears on its own line, prefixed with two spaces,
483
+ # or `* ` if it is the currently checked-out branch. This is the same
484
+ # format returned by `Git::Lib#branch_contains` in the 4.x gem series.
485
+ #
486
+ # @example List all branches that contain a commit
487
+ # repo.branch_contains('abc1234')
488
+ # # => " main\n"
489
+ #
490
+ # @example The current branch is marked with an asterisk
491
+ # repo.branch_contains('abc1234')
492
+ # # => "* main\n feature\n"
493
+ #
494
+ # @example Limit the search to branches matching a shell wildcard pattern
495
+ # repo.branch_contains('abc1234', 'feature/*')
496
+ #
497
+ # @example Typical usage: check whether any branch contains the commit
498
+ # repo.branch_contains('abc1234').empty? # => false
499
+ #
500
+ # @param commit [String] the commit SHA or ref to look up
501
+ #
502
+ # @param branch_name [String, nil] a shell wildcard pattern to limit which
503
+ # branches are searched
504
+ #
505
+ # When empty or `nil`, all local branches are searched.
506
+ #
507
+ # @return [String] the `git branch --list --contains` stdout
508
+ #
509
+ # Each matching branch appears on its own line, prefixed with two
510
+ # spaces, or `* ` for the currently checked-out branch. Returns an
511
+ # empty string when no matching branch contains the commit.
512
+ #
513
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
514
+ #
515
+ def branch_contains(commit, branch_name = '')
516
+ branch_name = branch_name.to_s
517
+ pattern = branch_name.empty? ? nil : branch_name
518
+ Git::Commands::Branch::List.new(@execution_context)
519
+ .call(*[pattern].compact, contains: commit, no_color: true)
520
+ .stdout
521
+ end
522
+
523
+ # Returns all local and remote-tracking branches as structured objects
524
+ #
525
+ # @example List all branches
526
+ # repo.branch_list
527
+ # # => [#<data Git::BranchInfo refname="refs/heads/main", current=true, ...>,
528
+ # # #<data Git::BranchInfo refname="refs/remotes/origin/main", current=false, ...>]
529
+ #
530
+ # @example Find the currently checked-out branch
531
+ # repo.branch_list.find(&:current)
532
+ #
533
+ # @example List only local branches
534
+ # repo.branch_list.reject(&:remote?)
535
+ #
536
+ # @example Filter to an exact branch name
537
+ # repo.branch_list('feature/auth')
538
+ #
539
+ # @example Filter using glob patterns
540
+ # repo.branch_list('feature/*', 'hotfix/*')
541
+ #
542
+ # @param patterns [Array<String>] optional shell wildcard patterns passed
543
+ # directly to `git branch --list`; when empty (the default) all branches
544
+ # are returned. Pattern matching follows git's own rules; behavior may
545
+ # differ between local and remote-tracking branches.
546
+ #
547
+ # @param remote_names [Array<String>, nil] configured remote names used to
548
+ # resolve remote-tracking refs
549
+ #
550
+ # Especially useful for remotes whose remote names contain slashes. When
551
+ # omitted, the repository's configured remote names are fetched automatically.
552
+ #
553
+ # @return [Array<Git::BranchInfo>] parsed branch information for every
554
+ # local and remote-tracking branch matching the pattern
555
+ #
556
+ # Returns an empty array when the repository has no branches or no branches
557
+ # match the given pattern.
558
+ #
559
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
560
+ #
561
+ def branch_list(*patterns, remote_names: nil)
562
+ remote_names ||= self.remote_names
563
+ result = Git::Commands::Branch::List.new(@execution_context).call(
564
+ *patterns, all: true, format: Git::Parsers::Branch::FORMAT_STRING
565
+ )
566
+ Git::Parsers::Branch.parse_list(result.stdout, remote_names:)
567
+ end
568
+
569
+ # Update a branch ref to point to a new commit
570
+ #
571
+ # Derives the full ref from the `branch` argument:
572
+ #
573
+ # - `remotes/<remote>/<name>` or `refs/remotes/<remote>/<name>` →
574
+ # writes to `refs/remotes/<remote>/<name>` (remote-tracking branch)
575
+ # - Any other value → writes to `refs/heads/<branch>` (local branch)
576
+ #
577
+ # @example Advance a local branch to the current HEAD
578
+ # repo.update_ref('feature', repo.rev_parse('HEAD'))
579
+ #
580
+ # @example Reset a local branch to an older commit
581
+ # repo.update_ref('main', 'abc1234def5678')
582
+ #
583
+ # @example Update a remote-tracking branch ref
584
+ # repo.update_ref('remotes/origin/main', 'abc1234def5678')
585
+ #
586
+ # @param branch [String] a local or remote-tracking branch name
587
+ #
588
+ # Short local names (e.g. `'main'`) resolve to `refs/heads/<branch>`.
589
+ # Remote-tracking names with a `remotes/<remote>/` or
590
+ # `refs/remotes/<remote>/` prefix (e.g. `'remotes/origin/main'`)
591
+ # resolve to `refs/remotes/<remote>/<name>`.
592
+ #
593
+ # @param commit [String] the commit SHA to point the branch at
594
+ #
595
+ # @return [Git::CommandLine::Result] the result of calling `git update-ref`
596
+ #
597
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
598
+ #
599
+ def update_ref(branch, commit)
600
+ ref = Private.build_update_ref(branch)
601
+ Git::Commands::UpdateRef::Update.new(@execution_context).call(ref, commit)
602
+ end
603
+
604
+ # Private helpers local to {Git::Repository::Branching}
605
+ #
606
+ # @api private
607
+ module Private
608
+ module_function
609
+
610
+ # Determines whether the given branch ref points to an existing commit
611
+ #
612
+ # Returns `:active` when the branch ref resolves successfully. Returns
613
+ # `:unborn` when the branch ref exists but has no commits yet (exit
614
+ # status 1 with empty stderr from `git rev-parse --verify --quiet`).
615
+ # Re-raises for any other failure.
616
+ #
617
+ # @param execution_context [Git::ExecutionContext::Repository] the
618
+ # execution context for git commands
619
+ #
620
+ # The full `refs/heads/<name>` ref is verified rather than the bare name.
621
+ # A bare name follows the gitrevisions search order, in which
622
+ # `refs/tags/<name>` is tried before `refs/heads/<name>`, so an unborn
623
+ # branch that shares its name with a tag would be reported as `:active`.
624
+ #
625
+ # @param branch_name [String] the branch name to verify
626
+ #
627
+ # @return [:active, :unborn] the branch ref state
628
+ #
629
+ # @raise [Git::FailedError] if git exits with a failure unrelated to an
630
+ # unborn branch
631
+ #
632
+ # @api private
633
+ #
634
+ def get_branch_state(execution_context, branch_name)
635
+ Git::Commands::RevParse.new(execution_context).call("refs/heads/#{branch_name}", verify: true, quiet: true)
636
+ :active
637
+ rescue Git::FailedError => e
638
+ raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
639
+
640
+ :unborn
641
+ end
642
+
643
+ # Translates {#checkout} options to the new command interface
644
+ #
645
+ # Legacy callers passed combinations like:
646
+ # checkout('branch', new_branch: true, start_point: 'main')
647
+ # which should map to:
648
+ # checkout('main', b: 'branch')
649
+ #
650
+ # `orphan: true` follows the same shape, naming the unborn branch:
651
+ # checkout('branch', orphan: true, start_point: 'main')
652
+ # maps to:
653
+ # checkout('main', orphan: 'branch')
654
+ #
655
+ # @param branch [String, nil] the branch argument passed to {#checkout}
656
+ #
657
+ # @param checkout_options [Hash] the raw options passed to {#checkout}
658
+ #
659
+ # @return [Array((String, nil), Hash)] a two-element tuple
660
+ # `[target, options]` containing the translated checkout arguments
661
+ #
662
+ # `target` (`String` or `nil`) is the branch or commit to check out.
663
+ # `options` is a `Hash` of keyword arguments for
664
+ # `Git::Commands::Checkout::Branch#call`
665
+ #
666
+ # @api private
667
+ #
668
+ def translate_checkout_opts(branch, checkout_options)
669
+ checkout_options = normalize_orphan_option(checkout_options)
670
+
671
+ if checkout_options[:new_branch] == true || checkout_options[:b] == true
672
+ [checkout_options[:start_point], checkout_options.except(:new_branch, :b, :start_point).merge(b: branch)]
673
+ elsif checkout_options[:new_branch].is_a?(String)
674
+ [branch, checkout_options.except(:new_branch).merge(b: checkout_options[:new_branch])]
675
+ elsif checkout_options[:orphan] == true
676
+ translate_orphan_opts(branch, checkout_options)
677
+ else
678
+ [branch, checkout_options]
679
+ end
680
+ end
681
+
682
+ # Normalizes the `:orphan` option, rejecting names that git would never see
683
+ #
684
+ # `:orphan` is a value option on the underlying command, so a literal
685
+ # `false` would be emitted as `--orphan false` and create a branch named
686
+ # "false". Flag options such as `:force` already ignore `false`; this
687
+ # gives `:orphan` the same behavior.
688
+ #
689
+ # A blank name is rejected rather than dropped: the argument DSL omits
690
+ # empty values, so `orphan: ''` would otherwise degrade silently into a
691
+ # plain checkout.
692
+ #
693
+ # @param checkout_options [Hash] the raw options passed to {#checkout}
694
+ #
695
+ # @return [Hash] the options with a `false` `:orphan` key removed
696
+ #
697
+ # @raise [ArgumentError] if `:orphan` is given a blank branch name
698
+ #
699
+ # @api private
700
+ #
701
+ def normalize_orphan_option(checkout_options)
702
+ orphan = checkout_options[:orphan]
703
+ return checkout_options.except(:orphan) if orphan == false
704
+ raise ArgumentError, 'orphan requires a non-empty branch name' if orphan.is_a?(String) && orphan.strip.empty?
705
+
706
+ checkout_options
707
+ end
708
+
709
+ # Translates `orphan: true` into the command's `:orphan` value option
710
+ #
711
+ # `orphan: true` names the unborn branch from the positional argument and
712
+ # takes its start point from `:start_point`, mirroring `new_branch: true`.
713
+ #
714
+ # @param branch [String, nil] the branch argument passed to {#checkout}
715
+ #
716
+ # @param checkout_options [Hash] the raw options passed to {#checkout}
717
+ #
718
+ # @return [Array((String, nil), Hash)] a two-element tuple
719
+ # `[target, options]` containing the translated checkout arguments
720
+ #
721
+ # @raise [ArgumentError] if `branch` is blank (`nil`, empty, or whitespace
722
+ # only), since the unborn branch would otherwise have no name
723
+ #
724
+ # @api private
725
+ #
726
+ def translate_orphan_opts(branch, checkout_options)
727
+ raise ArgumentError, 'orphan: true requires a branch name' if branch.to_s.strip.empty?
728
+
729
+ [checkout_options[:start_point], checkout_options.except(:start_point).merge(orphan: branch)]
730
+ end
731
+
732
+ # Normalizes path specifications for Git commands
733
+ #
734
+ # @param pathspecs [String, Pathname, Array<String, Pathname>, nil]
735
+ # the path(s) to normalize
736
+ #
737
+ # @param arg_name [String] the argument name used in error messages
738
+ #
739
+ # @return [Array<String>, nil] the normalized paths, or `nil` if none are valid
740
+ #
741
+ # @raise [ArgumentError] when any path is not a `String` or `Pathname`
742
+ #
743
+ # @api private
744
+ #
745
+ def normalize_pathspecs(pathspecs, arg_name)
746
+ return nil unless pathspecs
747
+
748
+ normalized = Array(pathspecs)
749
+ validate_pathspec_types(normalized, arg_name)
750
+
751
+ normalized = normalized.map(&:to_s).reject(&:empty?)
752
+ return nil if normalized.empty?
753
+
754
+ normalized
755
+ end
756
+
757
+ # Raises an error if any element of `pathspecs` is not a `String` or `Pathname`
758
+ #
759
+ # @param pathspecs [Array] the path elements to validate
760
+ #
761
+ # @param arg_name [String] the argument name used in error messages
762
+ #
763
+ # @return [void]
764
+ #
765
+ # @raise [ArgumentError] when any element is not a `String` or `Pathname`
766
+ #
767
+ # @api private
768
+ #
769
+ def validate_pathspec_types(pathspecs, arg_name)
770
+ return if pathspecs.all? { |path| path.is_a?(String) || path.is_a?(Pathname) }
771
+
772
+ raise ArgumentError, "Invalid #{arg_name}: must be a String, Pathname, or Array of Strings/Pathnames"
773
+ end
774
+
775
+ # Builds the full git ref string from a branch name argument
776
+ #
777
+ # - `remotes/<remote>/<name>` or `refs/remotes/<remote>/<name>` →
778
+ # `refs/remotes/<remote>/<name>`
779
+ # - Any other value → `refs/heads/<branch>`
780
+ #
781
+ # @param branch [String] a short local branch name or a remote-tracking
782
+ # branch name with a `remotes/` or `refs/remotes/` prefix
783
+ #
784
+ # @return [String] the full git ref string
785
+ #
786
+ # @api private
787
+ #
788
+ def build_update_ref(branch)
789
+ match = branch.match(%r{\A(?:refs/)?remotes/([^/]+)/(.+)\z})
790
+ match ? "refs/remotes/#{match[1]}/#{match[2]}" : "refs/heads/#{branch}"
791
+ end
792
+ end
793
+ private_constant :Private
794
+ end
795
+ end
796
+ end