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,1049 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/clone'
4
+ require 'git/commands/init'
5
+ require 'git/execution_context/global'
6
+ require 'git/execution_context/repository'
7
+ require 'git/path_resolver'
8
+ require 'git/repository'
9
+ require 'pathname'
10
+
11
+ module Git
12
+ # Implementation of the {Git} module factory entry points
13
+ #
14
+ # Provides `.open`, `.init`, `.clone`, and `.bare` — the four methods that
15
+ # construct a {Git::Repository}. Extended onto the {Git} module so that
16
+ # `Git.open(...)`, `Git.init(...)`, etc. resolve here.
17
+ #
18
+ # @api private
19
+ #
20
+ module Factories # rubocop:disable Metrics/ModuleLength
21
+ # Option keys {Git.open} accepts
22
+ #
23
+ # @return [Array<Symbol>]
24
+ #
25
+ # @api private
26
+ #
27
+ OPEN_ALLOWED_OPTS = %i[repository index log git_ssh binary_path].freeze
28
+ private_constant :OPEN_ALLOWED_OPTS
29
+
30
+ # Option keys {Git.bare} accepts
31
+ #
32
+ # @return [Array<Symbol>]
33
+ #
34
+ # @api private
35
+ #
36
+ BARE_ALLOWED_OPTS = %i[index log git_ssh binary_path].freeze
37
+ private_constant :BARE_ALLOWED_OPTS
38
+
39
+ # Option keys {Git.init} accepts
40
+ #
41
+ # @return [Array<Symbol>]
42
+ #
43
+ # @api private
44
+ #
45
+ INIT_ALLOWED_OPTS = %i[bare initial_branch repository separate_git_dir index log git_ssh binary_path].freeze
46
+ private_constant :INIT_ALLOWED_OPTS
47
+
48
+ # Clone a repository into a new directory
49
+ #
50
+ # @example Clone into the default directory
51
+ # repository = Git.clone('https://github.com/ruby-git/ruby-git.git')
52
+ #
53
+ # @example Clone into a specific directory
54
+ # repo_url = 'https://github.com/ruby-git/ruby-git.git'
55
+ # repository = Git.clone(repo_url, 'local')
56
+ #
57
+ # @example Clone a bare repository
58
+ # repo_url = 'https://github.com/ruby-git/ruby-git.git'
59
+ # repository = Git.clone(repo_url, nil, bare: true)
60
+ #
61
+ # @param repository_url [String, URI, Pathname] the URL or path of the repository to clone
62
+ #
63
+ # @param directory [String, Pathname, nil] the local directory name to clone into;
64
+ # git derives the name from the URL when `nil`
65
+ #
66
+ # Expanded before git runs, so `~` is the home directory and a relative
67
+ # path is relative to `:chdir` when given and to the process working
68
+ # directory otherwise. git creates the expanded directory, and the
69
+ # returned repository is bound to it.
70
+ #
71
+ # @param options [Hash] options that control cloning
72
+ #
73
+ # Some options configure the returned {Git::Repository} instance after
74
+ # the clone completes. Supported `git clone` options are forwarded.
75
+ #
76
+ # @option options [String, nil] :template template directory to use
77
+ #
78
+ # @option options [Boolean, nil] :local use the local clone optimization
79
+ #
80
+ # @option options [Boolean, nil] :no_local disable the local clone optimization
81
+ #
82
+ # @option options [Boolean, nil] :shared set up a shared clone
83
+ #
84
+ # @option options [Boolean, nil] :no_hardlinks copy files instead of hardlinks
85
+ #
86
+ # @option options [Boolean, nil] :quiet suppress progress output
87
+ #
88
+ # @option options [Boolean, nil] :verbose run verbosely
89
+ #
90
+ # @option options [Boolean, nil] :progress force progress output
91
+ #
92
+ # @option options [Boolean, nil] :no_checkout skip checking out `HEAD`
93
+ #
94
+ # @option options [Boolean, nil] :bare clone as a bare repository
95
+ #
96
+ # @option options [Boolean, nil] :mirror set up a mirror of the source
97
+ # (implies `:bare`)
98
+ #
99
+ # @option options [String, nil] :origin remote name to use instead of `origin`
100
+ #
101
+ # @option options [String, nil] :branch the branch or tag to check out after cloning
102
+ #
103
+ # @option options [String, nil] :revision revision to check out after cloning
104
+ #
105
+ # @option options [String, nil] :upload_pack remote `git-upload-pack` path
106
+ #
107
+ # @option options [String, Array<String>, nil] :reference reference repository
108
+ #
109
+ # @option options [String, Array<String>, nil] :reference_if_able
110
+ # optional reference repository
111
+ #
112
+ # @option options [Boolean, nil] :dissociate stop borrowing from references
113
+ #
114
+ # @option options [String, nil] :repository alternate git directory path
115
+ #
116
+ # Writes a gitfile in the working tree. Alias: `:separate_git_dir`.
117
+ # Expanded before git runs, like `directory`: `~` is the home directory
118
+ # and a relative path is relative to `:chdir` when given and to the
119
+ # process working directory otherwise.
120
+ #
121
+ # @option options [String, nil] :separate_git_dir alias for `:repository`
122
+ #
123
+ # @option options [String, Array<String>, nil] :server_option
124
+ # protocol-v2 server options
125
+ #
126
+ # @option options [Integer, String, nil] :depth create a shallow clone
127
+ #
128
+ # @option options [String, nil] :shallow_since create a shallow clone by date
129
+ #
130
+ # @option options [String, Array<String>, nil] :shallow_exclude
131
+ # exclude commits reachable from a ref
132
+ #
133
+ # @option options [Boolean, nil] :single_branch clone one branch's history
134
+ #
135
+ # @option options [Boolean, nil] :no_single_branch clone all branch history
136
+ #
137
+ # @option options [Boolean, nil] :tags include tags in the clone
138
+ #
139
+ # @option options [Boolean, nil] :no_tags exclude tags from the clone
140
+ #
141
+ # @option options [Boolean, String, Array<String>, nil] :recurse_submodules
142
+ # initialize submodules after cloning
143
+ #
144
+ # Pass `true` to initialize all submodules, or pass a pathspec string or
145
+ # array for a subset.
146
+ #
147
+ # @option options [Boolean, nil] :shallow_submodules use depth 1 for submodules
148
+ #
149
+ # @option options [Boolean, nil] :no_shallow_submodules use full submodule history
150
+ #
151
+ # @option options [Boolean, nil] :remote_submodules use submodule remote branches
152
+ #
153
+ # @option options [Boolean, nil] :no_remote_submodules use recorded submodule SHAs
154
+ #
155
+ # @option options [Integer, String, nil] :jobs submodule jobs to run concurrently
156
+ #
157
+ # @option options [Boolean, nil] :sparse enable sparse checkout
158
+ #
159
+ # @option options [Boolean, nil] :reject_shallow reject shallow source repositories
160
+ #
161
+ # @option options [Boolean, nil] :no_reject_shallow allow shallow sources
162
+ #
163
+ # @option options [String, nil] :filter specify a partial clone filter
164
+ #
165
+ # @option options [Boolean, nil] :also_filter_submodules filter submodules too
166
+ #
167
+ # @option options [String, Array<String>, nil] :config repository config entries
168
+ #
169
+ # @option options [String, nil] :bundle_uri bundle URI to prefetch
170
+ #
171
+ # @option options [String, nil] :ref_format ref storage format
172
+ #
173
+ # @option options [Numeric, nil] :timeout command timeout in seconds
174
+ #
175
+ # @option options [String, nil] :repository alternate git directory path
176
+ #
177
+ # Preferred facade spelling for `git clone --separate-git-dir`.
178
+ #
179
+ # @option options [String, nil, :use_global_config] :git_ssh path to a custom
180
+ # SSH executable
181
+ #
182
+ # Pass `:use_global_config` (the default) to use
183
+ # `Git.config.git_ssh`.
184
+ #
185
+ # @option options [String, :use_global_config] :binary_path path to the git
186
+ # binary
187
+ #
188
+ # Pass `:use_global_config` (the default) to use
189
+ # `Git.config.binary_path`.
190
+ #
191
+ # @option options [Logger, nil] :log logger used for git operations
192
+ #
193
+ # @option options [String, nil] :index a non-standard path to the index file
194
+ #
195
+ # Expanded before git runs, like `directory`: a relative path is expanded
196
+ # against `:chdir` when given, and against the process working directory
197
+ # otherwise.
198
+ #
199
+ # @option options [String, Pathname, nil] :chdir run `git clone` from within
200
+ # this directory
201
+ #
202
+ # Expanded before git runs, so `~` is the home directory and a relative
203
+ # path is relative to the process working directory. `directory`,
204
+ # `:repository`, and `:index` are expanded against the expanded value.
205
+ #
206
+ # @return [Git::Repository] a repository bound to the cloned working copy or
207
+ # bare repository
208
+ #
209
+ # @raise [ArgumentError] if unsupported options are provided, or if
210
+ # `directory`, `:repository`, `:index`, or `:chdir` begins with `~user`
211
+ # for a user that does not exist
212
+ #
213
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
214
+ #
215
+ # @raise [Git::Error] if a filesystem call made while resolving the paths
216
+ # fails
217
+ #
218
+ # @raise [Git::UnexpectedResultError] if the cloned directory cannot be
219
+ # determined from git's output
220
+ #
221
+ # @note If git fails before the transfer completes, git removes `directory`
222
+ # and the separate git directory it created, or empties `directory` when
223
+ # it existed before the call. A `:repository` path that already exists is
224
+ # refused before the transfer starts. If the transfer completes but the
225
+ # checkout fails, or the `:timeout` or the global timeout kills git, what
226
+ # git wrote is left in place. If {Git::UnexpectedResultError} is raised,
227
+ # the completed clone is left in place.
228
+ #
229
+ # @api public
230
+ #
231
+ def clone(repository_url, directory = nil, options = {})
232
+ opts, context_opts = prepare_clone_options(options)
233
+ directory = expand_directory(directory, bare: context_opts[:bare], base: opts[:chdir]) if directory
234
+ clone_result = run_clone_command(repository_url, directory, opts, context_opts)
235
+ paths = resolve_paths_from_clone_result(clone_result, directory, opts, context_opts)
236
+
237
+ from_paths(clone_repository_options(context_opts), paths)
238
+ end
239
+
240
+ # Create an empty Git repository or reinitialize an existing one
241
+ #
242
+ # @example Initialize in the current directory
243
+ # repository = Git.init
244
+ #
245
+ # @example Initialize in a specific directory
246
+ # repository = Git.init('/path/to/project')
247
+ #
248
+ # @example Initialize a bare repository
249
+ # repository = Git.init('/path/to/project.git', bare: true)
250
+ #
251
+ # @param directory [String] the directory to initialize; defaults to `'.'`
252
+ #
253
+ # Expanded before git runs, so `~` is the home directory and a relative
254
+ # path is relative to the process working directory. git creates the
255
+ # expanded directory, and the returned repository is bound to it.
256
+ #
257
+ # @param options [Hash] options that control initialization
258
+ #
259
+ # Some options configure the returned {Git::Repository} instance after
260
+ # the repository is initialized.
261
+ #
262
+ # @option options [Boolean, nil] :bare create a bare repository at `directory`
263
+ #
264
+ # @option options [String, nil] :initial_branch the name for the initial branch
265
+ #
266
+ # @option options [String, nil] :repository path for the `.git` directory
267
+ #
268
+ # Writes a gitfile in the working tree. Alias: `:separate_git_dir`.
269
+ # Expanded before git runs, like `directory`: `~` is the home directory
270
+ # and a relative path is relative to the process working directory.
271
+ #
272
+ # @option options [String, nil] :separate_git_dir alias for `:repository`
273
+ #
274
+ # @option options [String, nil, :use_global_config] :git_ssh path to a custom
275
+ # SSH executable
276
+ #
277
+ # Pass `:use_global_config` (the default) to use
278
+ # `Git.config.git_ssh`.
279
+ #
280
+ # @option options [String, :use_global_config] :binary_path path to the git
281
+ # binary
282
+ #
283
+ # Pass `:use_global_config` (the default) to use
284
+ # `Git.config.binary_path`.
285
+ #
286
+ # @option options [Logger, nil] :log logger used for git operations
287
+ #
288
+ # @option options [String, nil] :index custom index path for the returned
289
+ # repository
290
+ #
291
+ # Expanded before git runs, like `directory`: `~` is the home directory
292
+ # and a relative path is relative to the process working directory.
293
+ #
294
+ # @return [Git::Repository] a repository bound to the newly initialized repository
295
+ #
296
+ # @raise [ArgumentError] if `options` contains an unknown key
297
+ #
298
+ # @raise [ArgumentError] if `directory`, `:repository`, or `:index` begins
299
+ # with `~user` for a user that does not exist
300
+ #
301
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
302
+ #
303
+ # @raise [Git::Error] if a filesystem call made while resolving the paths
304
+ # fails
305
+ #
306
+ # @note If git exits non-zero after it starts writing, whatever it wrote is
307
+ # left in place: `directory` when git created it, and a git directory
308
+ # (`.git`, or the `:repository` path and the gitfile pointing at it) that
309
+ # git may not recognize as a repository. If git succeeds but the
310
+ # repository cannot be opened, the initialized repository is left in place.
311
+ #
312
+ # @api public
313
+ #
314
+ def init(directory = '.', options = {})
315
+ reject_unknown_option_keys!(options.keys, INIT_ALLOWED_OPTS)
316
+ options = normalize_init_options(options)
317
+ directory = expand_directory(directory, bare: options[:bare])
318
+
319
+ run_init_command(directory, options)
320
+ open_after_init(directory, options)
321
+ end
322
+
323
+ # Open a working copy at an existing path
324
+ #
325
+ # @example Open the working copy in the current directory
326
+ # repository = Git.open('.')
327
+ #
328
+ # @param working_dir [String] the path to the root of the working copy
329
+ #
330
+ # May be any path inside the working tree when `:repository` is not given.
331
+ # Expanded before use: `~` is the home directory and a relative path is
332
+ # relative to the process working directory.
333
+ #
334
+ # @param options [Hash] options that control how the repository is located
335
+ #
336
+ # @option options [String, nil] :repository a non-standard path to the
337
+ # `.git` directory
338
+ #
339
+ # When given, `working_dir` is used as-is (the working tree root is not
340
+ # auto-detected). A relative path is expanded against the process working
341
+ # directory, not against `working_dir`.
342
+ #
343
+ # @option options [String, nil] :index a non-standard path to the index file
344
+ #
345
+ # A relative path is expanded against the process working directory.
346
+ #
347
+ # @option options [Logger, nil] :log logger used for git operations
348
+ #
349
+ # @option options [String, nil, :use_global_config] :git_ssh
350
+ # path to a custom SSH executable
351
+ #
352
+ # Pass `:use_global_config` (the default) to use
353
+ # `Git.config.git_ssh`.
354
+ #
355
+ # @option options [String, :use_global_config] :binary_path
356
+ # path to the git binary
357
+ #
358
+ # Pass `:use_global_config` (the default) to use
359
+ # `Git.config.binary_path`.
360
+ #
361
+ # @return [Git::Repository] a repository bound to the resolved paths
362
+ #
363
+ # @raise [ArgumentError] if `options` contains an unknown key
364
+ #
365
+ # @raise [ArgumentError] if `working_dir` is not a directory or is not inside
366
+ # a git working tree, or if it begins with `~user` for a user that does not
367
+ # exist
368
+ #
369
+ # @raise [Git::Error] if the `.git` path is a gitdir pointer file that cannot
370
+ # be read, if the git binary cannot be found or fails to launch, or if a
371
+ # filesystem call made while resolving the paths fails
372
+ #
373
+ # @note This method opens working copies only. To open a bare repository, use
374
+ # `Git.bare`.
375
+ #
376
+ # @api public
377
+ #
378
+ def open(working_dir, options = {})
379
+ reject_unknown_option_keys!(options.keys, OPEN_ALLOWED_OPTS)
380
+ expanded_dir = PathResolver.expand_path(working_dir, PathResolver::WORKING_DIRECTORY_MESSAGE)
381
+ raise ArgumentError, "'#{working_dir}' is not a directory" unless Dir.exist?(expanded_dir)
382
+
383
+ working_dir = options[:repository] ? expanded_dir : resolve_open_working_dir(expanded_dir, options)
384
+
385
+ paths = resolve_repository_paths(
386
+ working_dir, bare: false, repository: options[:repository], index: options[:index]
387
+ )
388
+
389
+ from_paths(options, paths)
390
+ end
391
+
392
+ # Open an existing bare repository at `git_dir`
393
+ #
394
+ # @example Open a bare repository
395
+ # repository = Git.bare('/path/to/repo.git')
396
+ #
397
+ # @example Bind a bare repository to a scratch index
398
+ # repository = Git.bare('/srv/repo.git', index: '/tmp/scratch.index')
399
+ # repository.read_tree('HEAD')
400
+ # tree_sha = repository.write_tree
401
+ #
402
+ # @param git_dir [String] the path to the bare repository directory
403
+ #
404
+ # @param options [Hash] options used to configure the repository instance
405
+ #
406
+ # @option options [String, nil] :index a non-standard path to the index file
407
+ #
408
+ # A relative path is expanded against the process working directory.
409
+ #
410
+ # @option options [Logger, nil] :log logger used for git operations
411
+ #
412
+ # @option options [String, nil, :use_global_config] :git_ssh
413
+ # path to a custom SSH executable
414
+ #
415
+ # Pass `:use_global_config` (the default) to use
416
+ # `Git.config.git_ssh`.
417
+ #
418
+ # @option options [String, :use_global_config] :binary_path
419
+ # path to the git binary
420
+ #
421
+ # Pass `:use_global_config` (the default) to use
422
+ # `Git.config.binary_path`.
423
+ #
424
+ # @return [Git::Repository] a repository bound to the bare repository directory
425
+ #
426
+ # @raise [ArgumentError] if `options` contains an unknown key
427
+ #
428
+ # @raise [Git::Error] if `git_dir` is a gitdir pointer file that cannot be read
429
+ #
430
+ # @api public
431
+ #
432
+ def bare(git_dir, options = {})
433
+ reject_unknown_option_keys!(options.keys, BARE_ALLOWED_OPTS)
434
+ paths = resolve_repository_paths(git_dir, bare: true, index: options[:index])
435
+
436
+ from_paths(options, paths)
437
+ end
438
+
439
+ private
440
+
441
+ # Run the `git clone` command using a global execution context
442
+ #
443
+ # @param repository_url [String, URI, Pathname] the URL or path of the repository to clone
444
+ #
445
+ # @param directory [String, Pathname, nil] the local directory name to clone into
446
+ #
447
+ # @param opts [Hash] command-ready clone options
448
+ #
449
+ # @param context_opts [Hash] context options produced while preparing clone
450
+ # options
451
+ #
452
+ # @option opts [Boolean, nil] :bare clone as a bare repository
453
+ #
454
+ # @option context_opts [String, :use_global_config] :binary_path path to
455
+ # the git binary
456
+ #
457
+ # @option context_opts [String, nil, :use_global_config] :git_ssh path to
458
+ # a custom SSH executable
459
+ #
460
+ # @option context_opts [Logger, nil] :logger logger used for clone
461
+ # operations
462
+ #
463
+ # @return [Git::CommandLine::Result] the result of running `git clone`
464
+ #
465
+ # @raise [ArgumentError] if unsupported options are provided
466
+ #
467
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
468
+ #
469
+ # @api private
470
+ #
471
+ def run_clone_command(repository_url, directory, opts, context_opts)
472
+ context = Git::ExecutionContext::Global.new(
473
+ binary_path: context_opts[:binary_path],
474
+ git_ssh: context_opts[:git_ssh],
475
+ logger: context_opts[:logger]
476
+ )
477
+
478
+ Git::Commands::Clone.new(context).call(repository_url, directory, **opts)
479
+ end
480
+
481
+ # Resolve repository paths from a completed clone result
482
+ #
483
+ # When the caller gave a directory, it was expanded before git ran and is
484
+ # used as is. Only when git derived the name from the URL is the directory
485
+ # read from git's output, where it is a relative name under `:chdir`.
486
+ #
487
+ # @param clone_result [Git::CommandLine::Result] the completed clone result
488
+ #
489
+ # @param directory [String, nil] the expanded directory given to {.clone},
490
+ # or `nil` when git derived the name from the URL
491
+ #
492
+ # @param opts [Hash] command-ready clone options
493
+ #
494
+ # @param context_opts [Hash] context options produced while preparing clone
495
+ # options
496
+ #
497
+ # @option opts [String, Pathname, nil] :chdir run `git clone` from within
498
+ # this directory
499
+ #
500
+ # @option context_opts [Boolean] :bare whether `:bare` or `:mirror` was
501
+ # requested
502
+ #
503
+ # @option context_opts [String, nil] :index the already expanded custom
504
+ # index path for the returned repository
505
+ #
506
+ # @return [Hash{Symbol => (String, nil)}] resolved path hash
507
+ #
508
+ # @raise [Git::UnexpectedResultError] if no directory was given and the clone
509
+ # directory cannot be parsed from git's output
510
+ #
511
+ # @api private
512
+ #
513
+ def resolve_paths_from_clone_result(clone_result, directory, opts, context_opts)
514
+ clone_dir = directory || prefix_with_chdir(parse_clone_directory(clone_result.stderr), opts[:chdir])
515
+
516
+ bare = context_opts[:bare] || bare_clone?(clone_result.stderr)
517
+ resolve_repository_paths(clone_dir, bare: bare, index: context_opts[:index])
518
+ end
519
+
520
+ # Expand the directory given to {.init} or {.clone} before git sees it
521
+ #
522
+ # git does not expand `~` in a path on its command line, so the expansion
523
+ # happens here. The directory git creates is then the one the returned
524
+ # repository is bound to.
525
+ #
526
+ # @param directory [String, Pathname] the directory to initialize or clone
527
+ # into
528
+ #
529
+ # @param bare [Boolean, nil] whether the directory is the bare repository
530
+ # itself rather than a working directory; selects the error message
531
+ #
532
+ # @param base [String, Pathname, nil] the directory a relative path is
533
+ # expanded against, or `nil` for the process working directory
534
+ #
535
+ # @return [String] the absolute path
536
+ #
537
+ # @raise [ArgumentError] if the path begins with `~user` for a user that
538
+ # does not exist
539
+ #
540
+ # @raise [Git::Error] if the path cannot be expanded, which happens when the
541
+ # process working directory has been removed
542
+ #
543
+ # @api private
544
+ #
545
+ def expand_directory(directory, bare:, base: nil)
546
+ message = bare ? PathResolver::REPOSITORY_MESSAGE : PathResolver::WORKING_DIRECTORY_MESSAGE
547
+ PathResolver.expand_path(directory, message, base: base)
548
+ end
549
+
550
+ # Join the clone directory git reported onto the `:chdir` it ran in
551
+ #
552
+ # Used only when no directory was given to {.clone}: git derives a relative
553
+ # name from the URL and creates it under `chdir`. An absolute path, should
554
+ # git ever report one, passes through unchanged.
555
+ #
556
+ # @param path [String] the clone directory reported by `git clone`
557
+ #
558
+ # @param chdir [String, Pathname, nil] the directory git ran in, or `nil`
559
+ #
560
+ # @return [String] `path` prefixed with `chdir` when `chdir` is given and
561
+ # `path` is relative; otherwise `path` unchanged
562
+ #
563
+ # @api private
564
+ #
565
+ def prefix_with_chdir(path, chdir)
566
+ return path if chdir.nil? || Pathname.new(path).absolute?
567
+
568
+ File.join(chdir, path)
569
+ end
570
+
571
+ # Build repository construction options from clone context options
572
+ #
573
+ # @param context_opts [Hash] context options produced while preparing clone
574
+ # options
575
+ #
576
+ # @return [Hash{Symbol => Object}] repository construction options
577
+ #
578
+ # @api private
579
+ #
580
+ def clone_repository_options(context_opts)
581
+ {
582
+ git_ssh: context_opts[:git_ssh],
583
+ binary_path: context_opts[:binary_path],
584
+ log: context_opts[:logger]
585
+ }
586
+ end
587
+
588
+ # Build the `:binary_path` and `:git_ssh` execution-context defaults
589
+ #
590
+ # Reads the values from the caller-supplied options, falling back to the
591
+ # `:use_global_config` sentinel for any the caller did not provide so the
592
+ # value is resolved from `Git::Config.instance` at call time.
593
+ #
594
+ # @param options [Hash] the caller-supplied options hash
595
+ #
596
+ # @option options [String, :use_global_config] :binary_path path to the
597
+ # git binary
598
+ #
599
+ # @option options [String, nil, :use_global_config] :git_ssh path to a
600
+ # custom SSH executable
601
+ #
602
+ # @return [Hash] context defaults with two keys: `:binary_path`
603
+ # (`String` or `:use_global_config` — `nil` is not valid and raises
604
+ # `ArgumentError` in {Git::ExecutionContext#initialize}) and `:git_ssh`
605
+ # (`String`, `nil`, or `:use_global_config`)
606
+ #
607
+ # @api private
608
+ #
609
+ def context_defaults(options)
610
+ {
611
+ binary_path: options.fetch(:binary_path, :use_global_config),
612
+ git_ssh: options.fetch(:git_ssh, :use_global_config)
613
+ }
614
+ end
615
+
616
+ # Resolve the worktree root to use as the working directory for {.open}
617
+ #
618
+ # @param working_dir [String] a path inside the working tree
619
+ #
620
+ # @param options [Hash] the caller-supplied options hash from {.open}
621
+ #
622
+ # @option options [String, :use_global_config] :binary_path path to the
623
+ # git binary
624
+ #
625
+ # @option options [String, nil, :use_global_config] :git_ssh path to a
626
+ # custom SSH executable
627
+ #
628
+ # @return [String] the absolute path to the root of the working tree
629
+ #
630
+ # @raise [ArgumentError] if `working_dir` is not inside a git working tree
631
+ #
632
+ # @raise [Git::Error] if the git binary cannot be found or fails to launch, or
633
+ # if `working_dir` cannot be expanded to an absolute path
634
+ #
635
+ # @api private
636
+ #
637
+ def resolve_open_working_dir(working_dir, options)
638
+ PathResolver.root_of_worktree(working_dir, **context_defaults(options))
639
+ end
640
+
641
+ # Raise if `keys` contains a key outside `allowed`
642
+ #
643
+ # @param keys [Array<Symbol>] the keys of the caller-supplied options
644
+ #
645
+ # @param allowed [Array<Symbol>] the keys the factory accepts
646
+ #
647
+ # @return [void]
648
+ #
649
+ # @raise [ArgumentError] if `keys` contains an unknown key
650
+ #
651
+ # @api private
652
+ #
653
+ def reject_unknown_option_keys!(keys, allowed)
654
+ unknown = keys - allowed
655
+ raise ArgumentError, "Unknown options: #{unknown.join(', ')}" unless unknown.empty?
656
+ end
657
+
658
+ # Build a repository from caller options and resolved paths
659
+ #
660
+ # @param options [Hash] the caller-supplied options (`:git_ssh`,
661
+ # `:binary_path`, `:log`)
662
+ #
663
+ # @param paths [Hash{Symbol => (String, nil)}] the resolved paths
664
+ #
665
+ # @option options [String, nil, :use_global_config] :git_ssh path to a
666
+ # custom SSH executable
667
+ #
668
+ # @option options [String, :use_global_config] :binary_path path to the
669
+ # git binary
670
+ #
671
+ # @option options [Logger, nil] :log logger used for git operations
672
+ #
673
+ # @return [Git::Repository] the constructed repository
674
+ #
675
+ # @api private
676
+ #
677
+ def from_paths(options, paths)
678
+ Git::Repository.new(execution_context: Git::ExecutionContext::Repository.from_hash(
679
+ options.merge(paths), logger: options[:log]
680
+ ))
681
+ end
682
+
683
+ # Extract facade-level options from the raw clone options and return
684
+ # command-ready options
685
+ #
686
+ # Returns `[command_opts, context_opts]` where `command_opts` is the
687
+ # caller's options with facade-level keys removed. Remaining keys are
688
+ # forwarded to `Git::Commands::Clone`, which raises `ArgumentError` for
689
+ # unsupported ones. `context_opts` contains values used for the execution
690
+ # context and post-clone path resolution.
691
+ #
692
+ # @param options [Hash] raw caller-supplied options
693
+ #
694
+ # @option options [Boolean, nil] :bare clone as a bare repository
695
+ #
696
+ # @return [Array<Hash>] a two-element tuple `[command_opts, context_opts]`
697
+ #
698
+ # @api private
699
+ #
700
+ def prepare_clone_options(options)
701
+ opts = options.dup
702
+ context_opts = extract_clone_context_options!(opts)
703
+ expand_path_option!(opts, :chdir, PathResolver::CHDIR_MESSAGE)
704
+ normalize_clone_repository_option!(opts)
705
+ expand_path_option!(context_opts, :index, PathResolver::INDEX_MESSAGE, base: opts[:chdir])
706
+
707
+ [opts, context_opts]
708
+ end
709
+
710
+ # Expand a path option in place when it is present
711
+ #
712
+ # git does no tilde expansion and ruby-git starts it without a shell, so
713
+ # every path option is expanded here before git sees it. A path that cannot
714
+ # be expanded is rejected before git runs.
715
+ #
716
+ # @param hash [Hash] the options hash (mutated in place)
717
+ #
718
+ # @param key [Symbol] the option to expand; left alone when `nil` or absent
719
+ #
720
+ # @param message [String] the {Git::Error} message when expansion fails
721
+ #
722
+ # @param base [String, Pathname, nil] the directory a relative path is
723
+ # expanded against, or `nil` for the process working directory
724
+ #
725
+ # @return [void] mutates `hash` in place
726
+ #
727
+ # @raise [ArgumentError] if the path begins with `~user` for a user that
728
+ # does not exist
729
+ #
730
+ # @raise [Git::Error] if the path cannot be expanded, which happens when the
731
+ # process working directory has been removed
732
+ #
733
+ # @api private
734
+ #
735
+ def expand_path_option!(hash, key, message, base: nil)
736
+ return unless hash[key]
737
+
738
+ hash[key] = PathResolver.expand_path(hash[key], message, base: base)
739
+ end
740
+
741
+ # Extract clone context options from command-ready options
742
+ #
743
+ # @param opts [Hash] clone options (mutated in place)
744
+ #
745
+ # @option opts [Logger, nil] :log logger used for clone operations
746
+ #
747
+ # @option opts [String, nil, :use_global_config] :git_ssh path to a
748
+ # custom SSH executable
749
+ #
750
+ # @option opts [String, :use_global_config] :binary_path path to the git
751
+ # binary
752
+ #
753
+ # @option opts [String, nil] :index custom index path for the returned
754
+ # repository
755
+ #
756
+ # @option opts [Boolean, nil] :bare clone as a bare repository; left in
757
+ # `opts` for git
758
+ #
759
+ # @option opts [Boolean, nil] :mirror set up a mirror of the source; left in
760
+ # `opts` for git
761
+ #
762
+ # @return [Hash{Symbol => Object}] context options for clone setup, with
763
+ # `:bare` true when either `:bare` or `:mirror` was requested
764
+ #
765
+ # @api private
766
+ #
767
+ def extract_clone_context_options!(opts)
768
+ {
769
+ logger: opts.delete(:log),
770
+ git_ssh: opts.key?(:git_ssh) ? opts.delete(:git_ssh) : :use_global_config,
771
+ binary_path: opts.key?(:binary_path) ? opts.delete(:binary_path) : :use_global_config,
772
+ index: opts.delete(:index),
773
+ bare: opts[:bare] || opts[:mirror] || false
774
+ }
775
+ end
776
+
777
+ # Normalize the clone repository option for `git clone`
778
+ #
779
+ # Resolves the `:separate_git_dir` alias to `:repository`, then renames
780
+ # `:repository` to `:separate_git_dir` and expands it before git runs,
781
+ # against `:chdir` when given, like the clone directory. git does no tilde
782
+ # expansion, so a `~`-prefixed path handed to git would create a directory
783
+ # literally named `~`.
784
+ #
785
+ # @param opts [Hash] clone options (mutated in place)
786
+ #
787
+ # @option opts [String, nil] :repository alternate git directory path
788
+ #
789
+ # @option opts [String, nil] :separate_git_dir alias for `:repository`
790
+ #
791
+ # @option opts [String, Pathname, nil] :chdir the directory git runs in
792
+ #
793
+ # @return [void] mutates `opts` in place
794
+ #
795
+ # @raise [ArgumentError] if `:repository` begins with `~user` for a user
796
+ # that does not exist
797
+ #
798
+ # @raise [Git::Error] if the path cannot be expanded, which happens when the
799
+ # process working directory has been removed
800
+ #
801
+ # @api private
802
+ #
803
+ def normalize_clone_repository_option!(opts)
804
+ resolve_repository_alias!(opts)
805
+ repository_val = opts.delete(:repository)
806
+ return unless repository_val
807
+
808
+ opts[:separate_git_dir] =
809
+ PathResolver.expand_path(repository_val, PathResolver::REPOSITORY_MESSAGE, base: opts[:chdir])
810
+ end
811
+
812
+ # Resolve the repository, working directory, and index paths for a repository
813
+ #
814
+ # @param dir [String] the bare git directory, or the working directory of a
815
+ # non-bare repository
816
+ #
817
+ # @param bare [Boolean] whether the repository is bare
818
+ #
819
+ # @param index [String, nil] optional custom index path
820
+ #
821
+ # @param repository [String, nil] optional custom `.git` directory path;
822
+ # ignored when `bare` is `true`
823
+ #
824
+ # @return [Hash{Symbol => (String, nil)}] resolved path hash
825
+ #
826
+ # @api private
827
+ #
828
+ def resolve_repository_paths(dir, bare:, index:, repository: nil)
829
+ args = bare ? { repository: dir, bare: true } : { working_directory: dir, repository: repository }
830
+ PathResolver.resolve_paths(**args, index: index)
831
+ end
832
+
833
+ # Normalize the options given to {.init}
834
+ #
835
+ # Resolves the `:separate_git_dir` alias to `:repository` and expands
836
+ # `:repository` and `:index` before git runs, so the git directory git
837
+ # creates is the one the returned repository is bound to and a path that
838
+ # cannot be expanded is rejected before a repository is left on disk.
839
+ #
840
+ # @param options [Hash] the caller-supplied options hash
841
+ #
842
+ # @option options [String, nil] :repository path for the `.git` directory
843
+ #
844
+ # @option options [String, nil] :separate_git_dir alias for `:repository`
845
+ #
846
+ # @option options [String, nil] :index custom index path for the returned
847
+ # repository
848
+ #
849
+ # @return [Hash] a new options hash with `:repository` set and expanded when
850
+ # either spelling was given, and `:index` expanded when given
851
+ #
852
+ # @raise [ArgumentError] if `:repository` or `:index` begins with `~user`
853
+ # for a user that does not exist
854
+ #
855
+ # @raise [Git::Error] if a path cannot be expanded, which happens when the
856
+ # process working directory has been removed
857
+ #
858
+ # @api private
859
+ #
860
+ def normalize_init_options(options)
861
+ options = options.dup
862
+ resolve_repository_alias!(options)
863
+ expand_path_option!(options, :repository, PathResolver::REPOSITORY_MESSAGE)
864
+ expand_path_option!(options, :index, PathResolver::INDEX_MESSAGE)
865
+ options
866
+ end
867
+
868
+ # Resolve the `:separate_git_dir` alias onto `:repository`
869
+ #
870
+ # `:separate_git_dir` is removed. Its value becomes `:repository` unless
871
+ # `:repository` was given a non-nil value, which wins.
872
+ #
873
+ # @param options [Hash] factory options (mutated in place)
874
+ #
875
+ # @option options [String, nil] :repository path for the git directory
876
+ #
877
+ # @option options [String, nil] :separate_git_dir alias for `:repository`
878
+ #
879
+ # @return [void] mutates `options` in place
880
+ #
881
+ # @api private
882
+ #
883
+ def resolve_repository_alias!(options)
884
+ return unless options.key?(:separate_git_dir)
885
+
886
+ separate_git_dir = options.delete(:separate_git_dir)
887
+ options[:repository] = separate_git_dir if options[:repository].nil?
888
+ end
889
+
890
+ # Run the `git init` command using a global execution context
891
+ #
892
+ # @param directory [String] the absolute path of the directory to initialize
893
+ #
894
+ # @param options [Hash] the normalized options hash (after alias resolution)
895
+ #
896
+ # @option options [Boolean, nil] :bare create a bare repository at
897
+ # `directory`
898
+ #
899
+ # @option options [String, nil] :initial_branch the name for the initial
900
+ # branch
901
+ #
902
+ # @option options [String, nil] :repository path for the `.git` directory
903
+ #
904
+ # @option options [String, :use_global_config] :binary_path path to the
905
+ # git binary
906
+ #
907
+ # @option options [String, nil, :use_global_config] :git_ssh path to a
908
+ # custom SSH executable
909
+ #
910
+ # @option options [Logger, nil] :log logger used for git operations
911
+ #
912
+ # @return [Git::CommandLine::Result] the result of running `git init`
913
+ #
914
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
915
+ #
916
+ # @api private
917
+ #
918
+ def run_init_command(directory, options)
919
+ init_opts = options.slice(:bare, :initial_branch)
920
+ init_opts[:separate_git_dir] = options[:repository] if options.key?(:repository)
921
+
922
+ context = Git::ExecutionContext::Global.new(**context_defaults(options), logger: options[:log])
923
+ Git::Commands::Init.new(context).call(directory, **init_opts)
924
+ end
925
+
926
+ # Open the repository produced by `git init`
927
+ #
928
+ # @param directory [String] the initialized directory
929
+ #
930
+ # @param options [Hash] the normalized options hash
931
+ #
932
+ # @option options [Boolean, nil] :bare create a bare repository at
933
+ # `directory`
934
+ #
935
+ # @option options [String, nil] :repository path for the `.git` directory
936
+ #
937
+ # @option options [String, nil] :index custom index path for the returned
938
+ # repository
939
+ #
940
+ # @option options [String, :use_global_config] :binary_path path to the
941
+ # git binary
942
+ #
943
+ # @option options [String, nil, :use_global_config] :git_ssh path to a
944
+ # custom SSH executable
945
+ #
946
+ # @option options [Logger, nil] :log logger used for git operations
947
+ #
948
+ # @return [Git::Repository] the repository opened after initialization
949
+ #
950
+ # @api private
951
+ #
952
+ def open_after_init(directory, options)
953
+ return bare(options[:repository] || directory, base_open_options_after_init(options)) if options[:bare]
954
+
955
+ self.open(directory, worktree_open_options_after_init(options))
956
+ end
957
+
958
+ # Build common options for opening a repository after `git init`
959
+ #
960
+ # @param options [Hash] the normalized options hash
961
+ #
962
+ # @option options [String, nil, :use_global_config] :git_ssh path to a
963
+ # custom SSH executable
964
+ #
965
+ # @option options [String, :use_global_config] :binary_path path to the
966
+ # git binary
967
+ #
968
+ # @option options [Logger, nil] :log logger used for git operations
969
+ #
970
+ # @option options [String, nil] :index custom index path for the returned
971
+ # repository
972
+ #
973
+ # @return [Hash{Symbol => Object}] options accepted by {.open} and {.bare}
974
+ #
975
+ # @api private
976
+ #
977
+ def base_open_options_after_init(options)
978
+ {
979
+ git_ssh: options.fetch(:git_ssh, :use_global_config),
980
+ binary_path: options.fetch(:binary_path, :use_global_config)
981
+ }.tap do |open_opts|
982
+ open_opts[:log] = options[:log] if options[:log]
983
+ open_opts[:index] = options[:index] if options[:index]
984
+ end
985
+ end
986
+
987
+ # Build worktree options for opening a repository after `git init`
988
+ #
989
+ # @param options [Hash] the normalized options hash
990
+ #
991
+ # @option options [String, nil, :use_global_config] :git_ssh path to a
992
+ # custom SSH executable
993
+ #
994
+ # @option options [String, :use_global_config] :binary_path path to the
995
+ # git binary
996
+ #
997
+ # @option options [Logger, nil] :log logger used for git operations
998
+ #
999
+ # @option options [String, nil] :index custom index path for the returned
1000
+ # repository
1001
+ #
1002
+ # @option options [String, nil] :repository path for the `.git` directory
1003
+ #
1004
+ # @return [Hash{Symbol => Object}] options accepted by {.open}
1005
+ #
1006
+ # @api private
1007
+ #
1008
+ def worktree_open_options_after_init(options)
1009
+ base_open_options_after_init(options).tap do |open_opts|
1010
+ open_opts[:repository] = options[:repository] if options[:repository]
1011
+ end
1012
+ end
1013
+
1014
+ # Parse the directory git derived from the URL out of `git clone` stderr
1015
+ #
1016
+ # Only called when no directory was given to {.clone}. The name git derives
1017
+ # is a single path component, so it never spans a line.
1018
+ #
1019
+ # @param stderr [String] stderr output from `git clone`
1020
+ #
1021
+ # @return [String] the clone directory git reported
1022
+ #
1023
+ # @raise [Git::UnexpectedResultError] if the stderr output cannot be parsed
1024
+ #
1025
+ # @api private
1026
+ #
1027
+ def parse_clone_directory(stderr)
1028
+ match = stderr.match(/^Cloning into (?:bare repository )?'(.+)'\.\.\.$/)
1029
+ raise Git::UnexpectedResultError, "Unable to determine clone directory from: #{stderr}" unless match
1030
+
1031
+ match[1]
1032
+ end
1033
+
1034
+ # Whether `git clone` reported that it created a bare repository
1035
+ #
1036
+ # Matches only the fixed prefix of git's progress line, so a destination
1037
+ # that spans several lines does not affect the result.
1038
+ #
1039
+ # @param stderr [String] stderr output from `git clone`
1040
+ #
1041
+ # @return [Boolean] true when git reported a bare repository
1042
+ #
1043
+ # @api private
1044
+ #
1045
+ def bare_clone?(stderr)
1046
+ stderr.match?(/^Cloning into bare repository '/)
1047
+ end
1048
+ end
1049
+ end