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,196 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/ls_files'
4
+ require 'git/commands/rev_parse'
5
+ require 'git/commands/status'
6
+ require 'git/escaped_path'
7
+ require 'git/parsers/status'
8
+ require 'git/status_info'
9
+
10
+ module Git
11
+ class Repository
12
+ # Facade methods for repository-status operations
13
+ #
14
+ # Provides methods for querying the state of the repository: checking
15
+ # whether any commits exist, listing untracked working-tree files, and
16
+ # listing files tracked in the index.
17
+ #
18
+ # Included by {Git::Repository}.
19
+ #
20
+ # @api private
21
+ #
22
+ module StatusOperations
23
+ # Returns `true` if the repository has no commits yet
24
+ #
25
+ # Checks whether `HEAD` can be resolved to a commit object. A brand-new
26
+ # repository (or one created with `git checkout --orphan`) where no commit
27
+ # has been made yet will have no commits.
28
+ #
29
+ # @example Check whether a repository is empty
30
+ # repo.no_commits? #=> true # freshly initialized, no commits yet
31
+ # repo.no_commits? #=> false # at least one commit exists
32
+ #
33
+ # @return [Boolean] `true` when the repository has no commits, `false` otherwise
34
+ #
35
+ # @raise [Git::FailedError] if git exits with a non-zero exit status other
36
+ # than when the repository has no commits
37
+ #
38
+ def no_commits?
39
+ Git::Commands::RevParse.new(@execution_context).call('HEAD', verify: true)
40
+ false
41
+ rescue Git::FailedError => e
42
+ raise unless e.result.status.exitstatus == 128 &&
43
+ e.result.stderr == 'fatal: Needed a single revision'
44
+
45
+ true
46
+ end
47
+
48
+ # List all files in the working tree that are not tracked by git
49
+ #
50
+ # Runs `git ls-files --others --exclude-standard` from the working tree
51
+ # root and returns an array of repository-relative file paths. Files that
52
+ # match `.gitignore` or other standard exclusion rules are omitted.
53
+ #
54
+ # @example Get untracked files
55
+ # repo.untracked_files #=> ["new_feature.rb", "tmp/debug.log"]
56
+ #
57
+ # @example No untracked files
58
+ # repo.untracked_files #=> []
59
+ #
60
+ # @return [Array<String>] repository-relative paths of untracked,
61
+ # non-ignored files; empty when there are none
62
+ #
63
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
64
+ #
65
+ def untracked_files
66
+ Git::Commands::LsFiles.new(@execution_context).call(
67
+ others: true, exclude_standard: true, chdir: @execution_context.git_work_dir
68
+ ).stdout.split("\n").map { |f| Private.unescape_quoted_path(f) }
69
+ end
70
+
71
+ # Returns a {Git::StatusInfo} describing the index and working tree state
72
+ #
73
+ # Runs `git status` in porcelain v2 format with NUL-separated entries and
74
+ # every untracked file listed individually, then reads `core.ignoreCase`
75
+ # as a boolean so that the path predicates on the result compare paths the
76
+ # way git does in this repository. Every entry type git reports is
77
+ # represented, including renames, copies, and merge conflicts. Clean
78
+ # tracked paths are not reported by `git status`, so they are absent from
79
+ # the result; {#ls_files} lists them.
80
+ #
81
+ # @example Check which files are modified
82
+ # repo.status_info.changed
83
+ # #=> { "lib/foo.rb" => #<data Git::StatusFileInfo path="lib/foo.rb", ...> }
84
+ #
85
+ # @example Check for untracked files
86
+ # repo.status_info.untracked.keys #=> ["new_file.rb"]
87
+ #
88
+ # @example Check one path
89
+ # repo.status_info.changed?('lib/foo.rb') #=> true
90
+ #
91
+ # @example Iterate over every entry
92
+ # repo.status_info.files.each do |file|
93
+ # puts "#{file.index_status}#{file.worktree_status} #{file.path}"
94
+ # end
95
+ #
96
+ # @return [Git::StatusInfo] the status of the repository
97
+ #
98
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
99
+ #
100
+ # @see https://git-scm.com/docs/git-status git-status
101
+ #
102
+ def status_info
103
+ result = Git::Commands::Status.new(@execution_context).call(
104
+ porcelain: 'v2', z: true, untracked_files: 'all'
105
+ )
106
+ files = Git::Parsers::Status.parse(result.stdout)
107
+ ignore_case = config_get('core.ignoreCase', type: 'bool')&.value == 'true'
108
+ Git::StatusInfo.new(files: files, ignore_case: ignore_case)
109
+ end
110
+
111
+ # List all files tracked in the index
112
+ #
113
+ # Runs `git ls-files --stage` under the given `location` and returns a
114
+ # hash keyed by file path with per-file index metadata.
115
+ #
116
+ # @example List all indexed files in the working tree
117
+ # repo.ls_files
118
+ # #=> { "README.md" => { path: "README.md", mode_index: "100644",
119
+ # #=> sha_index: "abc123...", stage: "0" }, ... }
120
+ #
121
+ # @example List indexed files under a specific directory
122
+ # repo.ls_files('lib/')
123
+ # #=> { "lib/git.rb" => { path: "lib/git.rb", ... }, ... }
124
+ #
125
+ # @param location [String, nil] the path to restrict the listing to;
126
+ # defaults to `'.'` (all tracked files) when `nil`
127
+ #
128
+ # @return [Hash{String => Hash}] a hash of index entries keyed by file path
129
+ #
130
+ # Each value is a Hash with the following keys:
131
+ # * `:path` [String] the file path
132
+ # * `:mode_index` [String] the file's index mode (e.g. `"100644"`)
133
+ # * `:sha_index` [String] the file's index SHA
134
+ # * `:stage` [String] the merge stage (`"0"` for normal entries)
135
+ #
136
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
137
+ #
138
+ def ls_files(location = nil)
139
+ location ||= '.'
140
+ {}.tap do |files|
141
+ Git::Commands::LsFiles.new(@execution_context).call(location, stage: true).stdout.split("\n").each do |line|
142
+ info, file = Private.split_status_line(line)
143
+ mode, sha, stage = info.split
144
+ files[file] = { path: file, mode_index: mode, sha_index: sha, stage: stage }
145
+ end
146
+ end
147
+ end
148
+
149
+ # Private helpers local to {Git::Repository::StatusOperations}
150
+ #
151
+ # @api private
152
+ #
153
+ module Private
154
+ module_function
155
+
156
+ # Split a tab-delimited status line from `git ls-files --stage` output
157
+ #
158
+ # The output format is `<mode> <sha> <stage>\t<file>`. Quoted file paths
159
+ # (which git uses when the path contains non-ASCII or special characters)
160
+ # are unescaped before being returned. `line` is assumed to be non-empty
161
+ # because `git ls-files --stage` never emits blank lines.
162
+ #
163
+ # @param line [String] a single line of git ls-files output
164
+ #
165
+ # @return [Array<String>] the tab-delimited parts with the last part
166
+ # unescaped when it was git-quoted
167
+ #
168
+ def split_status_line(line)
169
+ parts = line.split("\t")
170
+ parts[-1] = unescape_quoted_path(parts[-1])
171
+ parts
172
+ end
173
+
174
+ # Unescape a git-quoted path
175
+ #
176
+ # Git wraps paths containing non-ASCII or special characters in
177
+ # double-quotes and octal-escapes each byte. This method strips the
178
+ # surrounding quotes and delegates unescaping to {Git::EscapedPath}.
179
+ #
180
+ # @param path [String] the path as it appears in git output
181
+ #
182
+ # @return [String] the unescaped path
183
+ #
184
+ def unescape_quoted_path(path)
185
+ if path.start_with?('"') && path.end_with?('"')
186
+ Git::EscapedPath.new(path[1..-2]).unescape
187
+ else
188
+ path
189
+ end
190
+ end
191
+ end
192
+
193
+ private_constant :Private
194
+ end
195
+ end
196
+ end
@@ -0,0 +1,252 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/commands/worktree'
4
+ require 'git/parsers/worktree'
5
+ require 'git/worktree_info'
6
+
7
+ module Git
8
+ class Repository
9
+ # Facade methods for worktree operations: listing, adding, removing, moving,
10
+ # locking, repairing, and pruning worktrees
11
+ #
12
+ # Included by {Git::Repository}.
13
+ #
14
+ # @api private
15
+ #
16
+ module WorktreeOperations
17
+ # Returns every worktree attached to the repository
18
+ #
19
+ # Lists the main worktree first, then each linked worktree, in the order
20
+ # git reports them. The main worktree of a bare repository is included
21
+ # with {Git::WorktreeInfo#bare?} true and no head or branch.
22
+ #
23
+ # @example List all worktrees
24
+ # repo.worktree_list.map(&:path)
25
+ # #=> ["/path/to/main", "/tmp/feature"]
26
+ #
27
+ # @example Find the worktree that has a branch checked out
28
+ # info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
29
+ # info.path #=> "/tmp/feature"
30
+ # info.head #=> "b8c63202c3c0ebd37b7e45fd0c22e6c20d5bead1"
31
+ # info.locked? #=> false
32
+ #
33
+ # @return [Array<Git::WorktreeInfo>] one entry per worktree
34
+ #
35
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
36
+ #
37
+ # @raise [Git::UnexpectedResultError] if the worktree listing cannot be
38
+ # parsed
39
+ #
40
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
41
+ #
42
+ def worktree_list
43
+ result = Git::Commands::Worktree::List.new(@execution_context).call(porcelain: true)
44
+ Git::Parsers::Worktree.parse_list(result.stdout)
45
+ end
46
+
47
+ # Create a new linked worktree at the given directory
48
+ #
49
+ # Returns the entry that {#worktree_list} reports for the new worktree.
50
+ # Its `path` is the directory as git records it: absolute, with symlinks
51
+ # resolved, so `/tmp/feature` on macOS comes back as
52
+ # `/private/tmp/feature`.
53
+ #
54
+ # @example Create a worktree at a path (auto-creates a branch)
55
+ # info = repo.worktree_add('/tmp/feature')
56
+ # info.path #=> "/private/tmp/feature"
57
+ # info.branch #=> "refs/heads/feature"
58
+ #
59
+ # @example Create a worktree and check out an existing commitish
60
+ # repo.worktree_add('/tmp/hotfix', 'main').head
61
+ # #=> "4bef5ab0c8e7c19c6be2c0f55ccd45eec1f3d32a"
62
+ #
63
+ # @param dir [String] filesystem path for the new worktree, absolute or
64
+ # relative to the current directory
65
+ #
66
+ # @param commitish [String, nil] branch, tag, or commit to check out
67
+ #
68
+ # When `nil`, git checks out the branch named after the final path
69
+ # component, creating it when no such branch exists
70
+ #
71
+ # @return [Git::WorktreeInfo] the new worktree's entry from {#worktree_list}
72
+ #
73
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
74
+ #
75
+ # @raise [Git::UnexpectedResultError] if the worktree listing cannot be
76
+ # parsed or does not contain an entry for the new worktree's directory
77
+ # (for example, it was removed by another process before the lookup)
78
+ #
79
+ # @note When `commitish` is `nil` and git creates the branch, it does so
80
+ # before it creates the worktree, so a failure after that point leaves
81
+ # the new branch in place without a worktree. A branch that already
82
+ # existed is left as it was.
83
+ #
84
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
85
+ #
86
+ def worktree_add(dir, commitish = nil)
87
+ args = [dir]
88
+ args << commitish unless commitish.nil?
89
+
90
+ Git::Commands::Worktree::Add.new(@execution_context).call(*args)
91
+
92
+ # git records the path as given with symlinks resolved, so compare by
93
+ # identity rather than by string: this covers symlinks, case-insensitive
94
+ # filesystems, and Unicode normalization on macOS
95
+ worktree_list.find { |worktree| File.identical?(worktree.path, dir) } ||
96
+ raise(Git::UnexpectedResultError, "worktree was created but not found in the worktree list: #{dir}")
97
+ end
98
+
99
+ # Remove a linked worktree
100
+ #
101
+ # @example Remove a worktree by path
102
+ # repo.worktree_remove('/tmp/feature')
103
+ #
104
+ # @example Remove a worktree from the list
105
+ # info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
106
+ # repo.worktree_remove(info)
107
+ #
108
+ # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
109
+ # remove, or its entry from {#worktree_list}
110
+ #
111
+ # @return [String] the output from the git worktree remove command
112
+ # (typically empty)
113
+ #
114
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
115
+ #
116
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
117
+ #
118
+ def worktree_remove(worktree)
119
+ Git::Commands::Worktree::Remove.new(@execution_context).call(worktree.to_s).stdout
120
+ end
121
+
122
+ # Move a linked worktree to a new location
123
+ #
124
+ # @example Move a worktree
125
+ # repo.worktree_move('/tmp/feature', '/tmp/feature-moved')
126
+ #
127
+ # @example Move a locked worktree
128
+ # repo.worktree_move('/tmp/feature', '/tmp/feature-moved', force: 2)
129
+ #
130
+ # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
131
+ # move, or its entry from {#worktree_list}
132
+ #
133
+ # @param new_path [String] the destination path
134
+ #
135
+ # @param opts [Hash] options for the move
136
+ #
137
+ # @option opts [Boolean, Integer, nil] :force (nil) override git's
138
+ # safeguards; git refuses to move a locked worktree unless the flag is
139
+ # given twice, so pass `2` for that
140
+ #
141
+ # @return [String] the output from the git worktree move command
142
+ # (typically empty)
143
+ #
144
+ # @raise [ArgumentError] if unsupported options are provided
145
+ #
146
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
147
+ #
148
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
149
+ #
150
+ def worktree_move(worktree, new_path, opts = {})
151
+ Git::Commands::Worktree::Move.new(@execution_context).call(worktree.to_s, new_path, **opts).stdout
152
+ end
153
+
154
+ # Lock a linked worktree so that `git worktree prune` leaves it alone
155
+ #
156
+ # Lock a worktree whose directory is on removable media or a network
157
+ # share that is not always mounted.
158
+ #
159
+ # @example Lock a worktree
160
+ # repo.worktree_lock('/tmp/feature')
161
+ #
162
+ # @example Lock a worktree with a reason
163
+ # repo.worktree_lock('/tmp/feature', reason: 'on an external drive')
164
+ #
165
+ # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
166
+ # lock, or its entry from {#worktree_list}
167
+ #
168
+ # @param opts [Hash] options for the lock
169
+ #
170
+ # @option opts [String, nil] :reason (nil) an explanation stored with the
171
+ # lock and reported as {Git::WorktreeInfo#lock_reason}
172
+ #
173
+ # @return [String] the output from the git worktree lock command
174
+ # (typically empty)
175
+ #
176
+ # @raise [ArgumentError] if unsupported options are provided
177
+ #
178
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
179
+ #
180
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
181
+ #
182
+ def worktree_lock(worktree, opts = {})
183
+ Git::Commands::Worktree::Lock.new(@execution_context).call(worktree.to_s, **opts).stdout
184
+ end
185
+
186
+ # Unlock a linked worktree
187
+ #
188
+ # @example Unlock a worktree
189
+ # repo.worktree_unlock('/tmp/feature')
190
+ #
191
+ # @param worktree [String, Git::WorktreeInfo] the path of the worktree to
192
+ # unlock, or its entry from {#worktree_list}
193
+ #
194
+ # @return [String] the output from the git worktree unlock command
195
+ # (typically empty)
196
+ #
197
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
198
+ #
199
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
200
+ #
201
+ def worktree_unlock(worktree)
202
+ Git::Commands::Worktree::Unlock.new(@execution_context).call(worktree.to_s).stdout
203
+ end
204
+
205
+ # Repair the links between the repository and its linked worktrees
206
+ #
207
+ # With no paths, repairs the link from each linked worktree back to the
208
+ # repository, which is needed after the repository directory was moved.
209
+ # Given the current paths of linked worktrees that were moved without
210
+ # {#worktree_move}, also repairs the repository's links to them.
211
+ #
212
+ # @example Repair after the repository directory was moved
213
+ # repo.worktree_repair
214
+ #
215
+ # @example Repair after a linked worktree was moved by hand
216
+ # repo.worktree_repair('/new/path/to/feature')
217
+ #
218
+ # @param paths [Array<String, Git::WorktreeInfo>] the current paths of the
219
+ # worktrees to repair, or their entries from {#worktree_list}
220
+ #
221
+ # @return [String] the output from the git worktree repair command, which
222
+ # reports each repair made
223
+ #
224
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
225
+ #
226
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
227
+ #
228
+ def worktree_repair(*paths)
229
+ Git::Commands::Worktree::Repair.new(@execution_context).call(*paths.map(&:to_s)).stdout
230
+ end
231
+
232
+ # Prune stale worktree administrative files
233
+ #
234
+ # Removes stale administrative files from `$GIT_DIR/worktrees`. A
235
+ # worktree becomes stale when its directory no longer exists on disk.
236
+ #
237
+ # @example Prune stale worktrees
238
+ # repo.worktree_prune
239
+ #
240
+ # @return [String] the output from the git worktree prune command
241
+ # (typically empty)
242
+ #
243
+ # @raise [Git::FailedError] if git exits with a non-zero exit status
244
+ #
245
+ # @see https://git-scm.com/docs/git-worktree git-worktree documentation
246
+ #
247
+ def worktree_prune
248
+ Git::Commands::Worktree::Prune.new(@execution_context).call.stdout
249
+ end
250
+ end
251
+ end
252
+ end
@@ -1,6 +1,209 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require 'find'
4
+ require 'pathname'
5
+
6
+ require 'git/configuring'
7
+ require 'git/execution_context/repository'
8
+ require 'git/repository/branching'
9
+ require 'git/repository/context_helpers'
10
+ require 'git/repository/committing'
11
+ require 'git/repository/diffing'
12
+ require 'git/repository/inspecting'
13
+ require 'git/repository/logging'
14
+ require 'git/repository/maintenance'
15
+ require 'git/repository/merging'
16
+ require 'git/repository/object_operations'
17
+ require 'git/repository/remote_operations'
18
+ require 'git/repository/staging'
19
+ require 'git/repository/stashing'
20
+ require 'git/repository/status_operations'
21
+ require 'git/repository/worktree_operations'
22
+ require 'git/system_call_guard'
23
+
3
24
  module Git
4
- class Repository < Path
25
+ # The main public interface for interacting with a Git repository
26
+ #
27
+ # `Git::Repository` is the **orchestration layer** for all git operations. It acts
28
+ # as the glue between the user-facing API and the underlying components, but
29
+ # contains minimal domain logic itself. For each operation it:
30
+ #
31
+ # 1. **Pre-processes arguments** — transforms user-provided values into forms
32
+ # suitable for the command layer (e.g. path expansion, option normalization,
33
+ # Ruby-idiomatic defaults, deprecation handling, input validation).
34
+ # 2. **Calls commands** — invokes one or more `Git::Commands::*` classes via the
35
+ # injected `Git::ExecutionContext::Repository`.
36
+ # 3. **Builds rich return values** — passes raw command output through
37
+ # `Git::Parsers::*` classes and result-class factory methods to assemble the
38
+ # meaningful Ruby objects the caller expects.
39
+ #
40
+ # Some operations are genuinely one-line delegators when no pre/post-processing is
41
+ # needed (e.g. `add`, `reset`), but many are short orchestration sequences that
42
+ # coordinate argument preparation, one or more command calls, and result assembly.
43
+ #
44
+ # Facade methods are organized into focused modules under `lib/git/repository/`
45
+ # (e.g. {Git::Repository::Staging}) and included into this class.
46
+ #
47
+ # @api public
48
+ #
49
+ class Repository
50
+ include Git::Configuring
51
+ include Git::Repository::Branching
52
+ include Git::Repository::ContextHelpers
53
+ include Git::Repository::Committing
54
+ include Git::Repository::Diffing
55
+ include Git::Repository::Inspecting
56
+ include Git::Repository::Logging
57
+ include Git::Repository::Maintenance
58
+ include Git::Repository::Merging
59
+ include Git::Repository::ObjectOperations
60
+ include Git::Repository::RemoteOperations
61
+ include Git::Repository::Staging
62
+ include Git::Repository::Stashing
63
+ include Git::Repository::StatusOperations
64
+ include Git::Repository::WorktreeOperations
65
+
66
+ # @return [Git::ExecutionContext::Repository] the execution context used to run
67
+ # git commands for this repository
68
+ #
69
+ # @api private
70
+ attr_reader :execution_context
71
+
72
+ # @param execution_context [Git::ExecutionContext::Repository] the context used
73
+ # to run git commands for this repository; must not be nil
74
+ #
75
+ # @raise [ArgumentError] if `execution_context` is nil
76
+ #
77
+ def initialize(execution_context:)
78
+ raise ArgumentError, 'execution_context must not be nil' if execution_context.nil?
79
+
80
+ @execution_context = execution_context
81
+ end
82
+
83
+ # Returns the root of the working tree, or `nil` for a bare repository
84
+ #
85
+ # @example Get the working directory path
86
+ # repository.dir #=> #<Pathname:/path/to/repo>
87
+ #
88
+ # @return [Pathname, nil] the working directory path, or `nil` when bare
89
+ #
90
+ def dir
91
+ working_dir = execution_context.git_work_dir
92
+ working_dir && Pathname.new(working_dir)
93
+ end
94
+
95
+ # Returns the repository (`.git`) directory
96
+ #
97
+ # @example Get the repository directory path
98
+ # repository.repo #=> #<Pathname:/path/to/repo/.git>
99
+ #
100
+ # @return [Pathname, nil] the repository directory path
101
+ #
102
+ def repo
103
+ repository = execution_context.git_dir
104
+ repository && Pathname.new(repository)
105
+ end
106
+
107
+ # Returns the git index file
108
+ #
109
+ # @example Get the index file path
110
+ # repository.index #=> #<Pathname:/path/to/repo/.git/index>
111
+ #
112
+ # @return [Pathname, nil] the index file path
113
+ #
114
+ def index
115
+ index_file = execution_context.git_index_file
116
+ index_file && Pathname.new(index_file)
117
+ end
118
+
119
+ # @return [String, nil] the git directory path
120
+ #
121
+ # @api private
122
+ def git_dir = execution_context.git_dir
123
+
124
+ # @return [String, nil] the working directory path
125
+ #
126
+ # @api private
127
+ def git_work_dir = execution_context.git_work_dir
128
+
129
+ # @return [String, nil] the index file path
130
+ #
131
+ # @api private
132
+ def git_index_file = execution_context.git_index_file
133
+
134
+ # Returns the installed git version
135
+ #
136
+ # @param timeout [Numeric, nil] seconds to wait for `git version`; `nil`
137
+ # uses the default timeout for this execution context
138
+ #
139
+ # @return [Git::Version] the installed git version
140
+ #
141
+ # @api private
142
+ def git_version(timeout: nil) = execution_context.git_version(timeout: timeout)
143
+
144
+ # @return [String, nil] the SSH wrapper path
145
+ #
146
+ # @api private
147
+ def git_ssh = execution_context.git_ssh
148
+
149
+ # @return [String, :use_global_config] the path to the git binary
150
+ #
151
+ # @api private
152
+ def binary_path = execution_context.binary_path
153
+
154
+ # Returns the size of the repository directory in bytes
155
+ #
156
+ # Sums the sizes of every regular file under the repository (`.git`)
157
+ # directory in a single traversal. Symbolic links are not followed, so files
158
+ # that physically live outside the repository (reached through a symlinked
159
+ # directory) are never counted. Files that disappear mid-traversal are
160
+ # silently skipped.
161
+ #
162
+ # @example Get the repository size in bytes
163
+ # repository.repo_size #=> 12345
164
+ #
165
+ # @return [Integer] the total size in bytes of the repository directory
166
+ #
167
+ # @raise [Git::Error] if the repository directory cannot be traversed, for
168
+ # example when a subdirectory cannot be searched
169
+ #
170
+ def repo_size
171
+ repository = repo
172
+ return 0 unless repository&.directory?
173
+
174
+ Git::SystemCallGuard.call('Failed to compute the repository size') do
175
+ repo_size_of_directory(repository.to_s)
176
+ end
177
+ end
178
+
179
+ private
180
+
181
+ # Sums the size of every regular file under `dir`
182
+ #
183
+ # Symbolic links are not followed. Entries that disappear between the
184
+ # traversal and the `lstat` call are skipped.
185
+ #
186
+ # @param dir [String] the directory to traverse
187
+ #
188
+ # @return [Integer] the total size in bytes of the files under `dir`
189
+ #
190
+ def repo_size_of_directory(dir)
191
+ total = 0
192
+ Find.find(dir) do |path|
193
+ stat = File.lstat(path)
194
+ total += stat.size if stat.file?
195
+ rescue Errno::ENOENT
196
+ next
197
+ end
198
+ total
199
+ end
200
+
201
+ # All git config scopes are valid in a repository context
202
+ #
203
+ # @return [void]
204
+ #
205
+ def assert_valid_scope!(**)
206
+ nil
207
+ end
5
208
  end
6
209
  end