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
@@ -3,31 +3,87 @@
3
3
  require 'rchardet'
4
4
 
5
5
  module Git
6
- # Method that can be used to detect and normalize string encoding
6
+ # Provides helpers for detecting and normalizing string encodings
7
+ #
8
+ # `default_encoding` refers to {Git::EncodingUtils.default_encoding}, which is
9
+ # derived from this source file's encoding declaration
10
+ #
11
+ # @api private
12
+ #
7
13
  module EncodingUtils
14
+ # Returns the default encoding name used by this source file
15
+ #
16
+ # @return [String] the source file encoding name
17
+ #
8
18
  def self.default_encoding
9
19
  __ENCODING__.name
10
20
  end
11
21
 
22
+ # Returns the fallback encoding name used when detection fails
23
+ #
24
+ # @return [String] the fallback encoding name
25
+ #
12
26
  def self.best_guess_encoding
13
27
  # Encoding::ASCII_8BIT.name
14
28
  Encoding::UTF_8.name
15
29
  end
16
30
 
31
+ # Returns the detected encoding name for the given string
32
+ #
33
+ # @param str [String] the string whose encoding should be detected
34
+ #
35
+ # @return [String] the detected encoding name or the fallback encoding name
36
+ #
17
37
  def self.detected_encoding(str)
18
38
  CharDet.detect(str)['encoding'] || best_guess_encoding
19
39
  end
20
40
 
41
+ # Returns replacement options used when transcoding invalid byte sequences
42
+ #
43
+ # @return [Hash<Symbol, Symbol>] options for replacing invalid and undefined bytes
44
+ #
21
45
  def self.encoding_options
22
46
  { invalid: :replace, undef: :replace }
23
47
  end
24
48
 
49
+ # Returns the given string converted to {Git::EncodingUtils.default_encoding}
50
+ #
51
+ # When the string is not valid in its own encoding, the source encoding is
52
+ # taken from {Git::EncodingUtils.detected_encoding}. rchardet can name an
53
+ # encoding Ruby has no converter for (`UTF-7` and the two unusual-octet-order
54
+ # `UCS-4` forms, each assigned from a byte-order mark). In that case the
55
+ # invalid bytes are replaced with `String#scrub` instead, which keeps any
56
+ # valid multibyte sequences on the same line.
57
+ #
58
+ # @param str [String] the string to normalize
59
+ #
60
+ # @return [String] the original or transcoded string in
61
+ # {Git::EncodingUtils.default_encoding}
62
+ #
25
63
  def self.normalize_encoding(str)
26
64
  return str if str.valid_encoding? && str.encoding.name == default_encoding
27
65
 
28
66
  return str.encode(default_encoding, str.encoding, **encoding_options) if str.valid_encoding?
29
67
 
30
68
  str.encode(default_encoding, detected_encoding(str), **encoding_options)
69
+ rescue Encoding::ConverterNotFoundError
70
+ scrub_to_default_encoding(str)
31
71
  end
72
+
73
+ # Returns the given string with its invalid bytes replaced, in
74
+ # {Git::EncodingUtils.default_encoding}
75
+ #
76
+ # `String#scrub` returns the string in its own encoding, so the result is
77
+ # transcoded afterward. On the gem's own call path the string is already
78
+ # tagged UTF-8 and that step is a no-op.
79
+ #
80
+ # @param str [String] the string to scrub
81
+ #
82
+ # @return [String] the scrubbed string in {Git::EncodingUtils.default_encoding}
83
+ #
84
+ def self.scrub_to_default_encoding(str)
85
+ str.scrub.encode(default_encoding, **encoding_options)
86
+ end
87
+ private_class_method :scrub_to_default_encoding
32
88
  end
33
89
  end
data/lib/git/errors.rb CHANGED
@@ -6,21 +6,21 @@ module Git
6
6
  # Base class for all custom git module errors
7
7
  #
8
8
  # The git gem will only raise an `ArgumentError` or an error that is a subclass of
9
- # `Git::Error`. It does not explicitly raise any other types of errors.
10
- #
11
- # The gem's own filesystem operations, such as reading a `.git` pointer file,
12
- # creating a temporary file, or changing directory, do not convert operating
13
- # system errors. These can be raised as a bare `SystemCallError` (for example
14
- # `Errno::ENOENT` or `Errno::EACCES`) rather than `Git::Error`. Gzip compression
15
- # in `archive` can likewise raise a `Zlib::Error`. Rescue `SystemCallError` and
16
- # `Zlib::Error` alongside `Git::Error` if your code needs to handle them. Any
17
- # method that captures git output can also raise
18
- # `Encoding::ConverterNotFoundError` when a line's detected encoding has no Ruby
19
- # converter.
9
+ # `Git::Error`.
20
10
  #
21
11
  # It is recommended to rescue `Git::Error` to catch any runtime error raised by
22
12
  # this gem unless you need more specific error handling.
23
13
  #
14
+ # Operating system errors from the gem's own filesystem operations, such as
15
+ # reading a `.git` pointer file or creating a temporary file, are raised as
16
+ # `Git::Error`. The original `SystemCallError` is available through `cause`.
17
+ #
18
+ # The promise covers errors the gem raises from its own operations. An error
19
+ # raised by a block your code passes to a method such as `chdir` propagates
20
+ # unchanged, and when `Git::Deprecation.behavior` is `:raise` a deprecated call
21
+ # raises `ActiveSupport::DeprecationException`, which is intentionally not a
22
+ # `Git::Error`.
23
+ #
24
24
  # Git's custom errors are arranged in the following class heirarchy:
25
25
  #
26
26
  # ```text
@@ -31,7 +31,8 @@ module Git
31
31
  # │ └─> Git::SignaledError
32
32
  # │ └─> Git::TimeoutError
33
33
  # ├─> Git::ProcessIOError
34
- # └─> Git::UnexpectedResultError
34
+ # ├─> Git::UnexpectedResultError
35
+ # └─> Git::VersionError
35
36
  # ```
36
37
  #
37
38
  # | Error Class | Description |
@@ -43,6 +44,7 @@ module Git
43
44
  # | `TimeoutError` | This is a specific type of `SignaledError` that is raised when the git command line operation times out and is killed via the SIGKILL signal. This happens if the operation takes longer than the timeout duration configured in `Git.config.timeout` or via the `:timeout` parameter given in git methods that support timeouts. |
44
45
  # | `ProcessIOError` | An error was encountered reading or writing to a subprocess. |
45
46
  # | `UnexpectedResultError` | The command line ran without error but did not return the expected results. |
47
+ # | `VersionError` | The installed git version does not meet the requirements of the git gem or a specific command. |
46
48
  #
47
49
  # @example Rescuing a generic error
48
50
  # begin
@@ -62,12 +64,19 @@ module Git
62
64
  # end
63
65
  #
64
66
  # @see Git::CommandLineError
67
+ #
65
68
  # @see Git::FailedError
69
+ #
66
70
  # @see Git::SignaledError
71
+ #
67
72
  # @see Git::TimeoutError
73
+ #
68
74
  # @see Git::ProcessIOError
75
+ #
69
76
  # @see Git::UnexpectedResultError
70
77
  #
78
+ # @see Git::VersionError
79
+ #
71
80
  # @api public
72
81
  #
73
82
  class Error < StandardError; end
@@ -76,12 +85,20 @@ module Git
76
85
 
77
86
  # An alias for Git::Error
78
87
  #
79
- # Git::GitExecuteError error class is an alias for Git::Error for backwards
80
- # compatibility. It is recommended to use Git::Error directly.
88
+ # Git::GitExecuteError is an alias for Git::Error kept for backwards
89
+ # compatibility. It is an ActiveSupport::Deprecation::DeprecatedConstantProxy,
90
+ # so any use of it, including instantiating it and matching it in a `rescue`
91
+ # clause, emits a deprecation warning through Git::Deprecation. The
92
+ # reflective methods that debuggers and IRB call, such as `inspect` and
93
+ # `name`, do not warn. It will be removed in a future major release.
81
94
  #
82
- # @deprecated Use Git::Error instead
95
+ # @deprecated Use Git::Error instead. Will be removed in a future major release.
83
96
  #
84
- GitExecuteError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Git::GitExecuteError', 'Git::Error', Git::Deprecation)
97
+ GitExecuteError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new(
98
+ 'Git::GitExecuteError', 'Git::Error', Git::Deprecation,
99
+ message: 'Git::GitExecuteError is deprecated and will be removed in a future major release. ' \
100
+ 'Use Git::Error instead.'
101
+ )
85
102
 
86
103
  # Raised when a git command fails or exits because of an uncaught signal
87
104
  #
@@ -101,11 +118,11 @@ module Git
101
118
  #
102
119
  # @example
103
120
  # `exit 1` # set $? appropriately for this example
104
- # result = Git::CommandLineResult.new(%w[git status], $?, 'stdout', 'stderr')
121
+ # result = Git::CommandLine::Result.new(%w[git status], $?, 'stdout', 'stderr')
105
122
  # error = Git::CommandLineError.new(result)
106
123
  # error.to_s #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
107
124
  #
108
- # @param result [Git::CommandLineResult] the result of the git command including
125
+ # @param result [Git::CommandLine::Result] the result of the git command including
109
126
  # the git command, status, stdout, and stderr
110
127
  #
111
128
  def initialize(result)
@@ -124,14 +141,12 @@ module Git
124
141
  #{result.git_cmd}, status: #{result.status}, stderr: #{result.stderr.inspect}
125
142
  MESSAGE
126
143
 
127
- # @attribute [r] result
128
- #
129
144
  # The result of the git command including the git command and its status and output
130
145
  #
131
146
  # @example
132
- # error.result #=> #<Git::CommandLineResult:0x00000001046bd488 ...>
147
+ # error.result #=> #<Git::CommandLine::Result:0x00000001046bd488 ...>
133
148
  #
134
- # @return [Git::CommandLineResult]
149
+ # @return [Git::CommandLine::Result]
135
150
  #
136
151
  attr_reader :result
137
152
  end
@@ -156,7 +171,7 @@ module Git
156
171
  # The git command executed, status, stdout, and stderr, and the timeout duration
157
172
  # are available from this object.
158
173
  #
159
- # result.status.timeout? will be `true`
174
+ # result.status.timed_out? will be `true`
160
175
  #
161
176
  # @api public
162
177
  #
@@ -167,12 +182,12 @@ module Git
167
182
  # command = %w[sleep 10]
168
183
  # timeout_duration = 1
169
184
  # status = ProcessExecuter.spawn(*command, timeout: timeout_duration)
170
- # result = Git::CommandLineResult.new(command, status, 'stdout', 'err output')
185
+ # result = Git::CommandLine::Result.new(command, status, 'stdout', 'err output')
171
186
  # error = Git::TimeoutError.new(result, timeout_duration)
172
187
  # error.error_message
173
188
  # #=> '["sleep", "10"], status: pid 70144 SIGKILL (signal 9), stderr: "err output", timed out after 1s'
174
189
  #
175
- # @param result [Git::CommandLineResult] the result of the git command including
190
+ # @param result [Git::CommandLine::Result] the result of the git command including
176
191
  # the git command, status, stdout, and stderr
177
192
  #
178
193
  # @param timeout_duration [Numeric] the amount of time the subprocess was allowed
@@ -199,7 +214,7 @@ module Git
199
214
  #
200
215
  # @example
201
216
  # `kill -9 $$` # set $? appropriately for this example
202
- # result = Git::CommandLineResult.new(%w[git status], $?, '', "killed")
217
+ # result = Git::CommandLine::Result.new(%w[git status], $?, '', "killed")
203
218
  # error = Git::TimeoutError.new(result, 10)
204
219
  # error.timeout_duration #=> 10
205
220
  #
@@ -219,4 +234,70 @@ module Git
219
234
  # @api public
220
235
  #
221
236
  class UnexpectedResultError < Git::Error; end
237
+
238
+ # Raised when the installed git version does not meet requirements
239
+ #
240
+ # This error is raised when:
241
+ # - The installed git version is below `Git::MINIMUM_GIT_VERSION`
242
+ # - A command requires a minimum git version that isn't met
243
+ # - A command was removed in a git version older than the installed version
244
+ #
245
+ # @example Rescuing a version error
246
+ # begin
247
+ # git.some_command
248
+ # rescue Git::VersionError => e
249
+ # puts "Git version #{e.actual_version} does not meet requirements"
250
+ # puts " #{e.subject}: requires #{e.constraint}"
251
+ # end
252
+ #
253
+ # @api public
254
+ #
255
+ class VersionError < Git::Error
256
+ # Create a VersionError
257
+ #
258
+ # @param subject [#to_s] the entity with the version requirement (e.g., "The git gem", a Class)
259
+ #
260
+ # @param constraint [Git::VersionConstraint] the version constraint that was violated
261
+ #
262
+ # @param actual_version [Git::Version] the installed git version
263
+ #
264
+ def initialize(subject:, constraint:, actual_version:)
265
+ @subject = subject
266
+ @constraint = constraint
267
+ @actual_version = actual_version
268
+ super(build_message)
269
+ end
270
+
271
+ # The entity that has the version requirement
272
+ #
273
+ # @return [#to_s]
274
+ #
275
+ attr_reader :subject
276
+
277
+ # The version constraint that was violated
278
+ #
279
+ # @return [Git::VersionConstraint]
280
+ #
281
+ attr_reader :constraint
282
+
283
+ # The installed git version that caused the error
284
+ #
285
+ # @return [Git::Version]
286
+ #
287
+ attr_reader :actual_version
288
+
289
+ private
290
+
291
+ # Builds the error message for the violated version constraint.
292
+ #
293
+ # @return [String]
294
+ #
295
+ def build_message
296
+ if constraint.too_new?(actual_version)
297
+ "#{subject} requires git < #{constraint.before} (found #{actual_version})"
298
+ else
299
+ "#{subject} requires git >= #{constraint.min} (found #{actual_version})"
300
+ end
301
+ end
302
+ end
222
303
  end
@@ -8,10 +8,15 @@ module Git
8
8
  # characters (e.g. \t for TAB, \n for LF, \\ for backslash) or bytes with values
9
9
  # larger than 0x80 (e.g. octal \302\265 for "micro" in UTF-8).
10
10
  #
11
- # @example
12
- # Git::GitPath.new('\302\265').unescape # => "µ"
11
+ # @example Decode octal UTF-8 bytes
12
+ # Git::EscapedPath.new('\302\265').unescape # => "µ"
13
+ #
14
+ # @api private
13
15
  #
14
16
  class EscapedPath
17
+ # Maps single-character escapes to their decoded byte values
18
+ #
19
+ # @return [Hash<String, Integer>] escape characters mapped to byte values
15
20
  UNESCAPES = {
16
21
  'a' => 0x07,
17
22
  'b' => 0x08,
@@ -26,13 +31,27 @@ module Git
26
31
  "'" => 0x27
27
32
  }.freeze
28
33
 
34
+ # Returns the escaped path as provided by git output
35
+ #
36
+ # @return [String] the escaped path string
29
37
  attr_reader :path
30
38
 
39
+ # Initializes an escaped path wrapper
40
+ #
41
+ # @param path [String] the path string with Git-style escape sequences
42
+ #
43
+ # @return [void]
31
44
  def initialize(path)
32
45
  @path = path
33
46
  end
34
47
 
35
- # Convert an escaped path to an unescaped path
48
+ # Converts an escaped path to an unescaped UTF-8 path
49
+ #
50
+ # @example Decode escaped path output
51
+ # Git::EscapedPath.new("dir/\\342\\230\\240\\n").unescape
52
+ # # => "dir/☠\n"
53
+ #
54
+ # @return [String] the decoded path string
36
55
  def unescape
37
56
  bytes = escaped_path_to_bytes(path)
38
57
  str = bytes.pack('C*')
@@ -41,18 +60,46 @@ module Git
41
60
 
42
61
  private
43
62
 
63
+ # Extracts an octal escape sequence starting at the given index
64
+ #
65
+ # @param path [String] the escaped path string
66
+ #
67
+ # @param index [Integer] the index where the sequence starts
68
+ #
69
+ # @return [Array(Integer, Integer)] decoded byte and consumed character count
44
70
  def extract_octal(path, index)
45
71
  [path[(index + 1)..(index + 3)].to_i(8), 4]
46
72
  end
47
73
 
74
+ # Extracts a single-character escape sequence at the given index
75
+ #
76
+ # @param path [String] the escaped path string
77
+ #
78
+ # @param index [Integer] the index where the sequence starts
79
+ #
80
+ # @return [Array(Integer, Integer)] decoded byte and consumed character count
48
81
  def extract_escape(path, index)
49
82
  [UNESCAPES[path[index + 1]], 2]
50
83
  end
51
84
 
85
+ # Extracts a non-escaped character byte at the given index
86
+ #
87
+ # @param path [String] the escaped path string
88
+ #
89
+ # @param index [Integer] the index of the character to decode
90
+ #
91
+ # @return [Array(Integer, Integer)] decoded byte and consumed character count
52
92
  def extract_single_char(path, index)
53
93
  [path[index].ord, 1]
54
94
  end
55
95
 
96
+ # Decodes the next byte from the escaped path at the given index
97
+ #
98
+ # @param path [String] the escaped path string
99
+ #
100
+ # @param index [Integer] the index to decode from
101
+ #
102
+ # @return [Array(Integer, Integer)] decoded byte and consumed character count
56
103
  def next_byte(path, index)
57
104
  if path[index] == '\\' && path[index + 1] >= '0' && path[index + 1] <= '7'
58
105
  extract_octal(path, index)
@@ -63,6 +110,11 @@ module Git
63
110
  end
64
111
  end
65
112
 
113
+ # Converts an escaped path string into decoded bytes
114
+ #
115
+ # @param path [String] the escaped path string
116
+ #
117
+ # @return [Array<Integer>] decoded bytes in order
66
118
  def escaped_path_to_bytes(path)
67
119
  index = 0
68
120
  [].tap do |bytes|
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/execution_context'
4
+
5
+ module Git
6
+ class ExecutionContext
7
+ # Execution context for global git commands (no repository required)
8
+ #
9
+ # Used for commands that do not require an existing repository — such as
10
+ # `git init`, `git clone`, and `git version`. Unlike
11
+ # {Git::ExecutionContext::Repository}, this class leaves `GIT_DIR`,
12
+ # `GIT_WORK_TREE`, and `GIT_INDEX_FILE` as `nil` (which unsets them), so
13
+ # that the parent environment cannot leak an unintended repository context.
14
+ # `GIT_SSH` is still supported to allow SSH-based remote operations
15
+ # (e.g. `git clone git@github.com:...`).
16
+ #
17
+ # @example Create a context using the default git binary
18
+ # context = Git::ExecutionContext::Global.new
19
+ #
20
+ # @example Create a context targeting a specific binary
21
+ # context = Git::ExecutionContext::Global.new(binary_path: '/usr/local/bin/git2')
22
+ #
23
+ # @see Git::ExecutionContext#initialize for constructor parameters and
24
+ # their semantics
25
+ #
26
+ # @api private
27
+ #
28
+ class Global < ExecutionContext
29
+ end
30
+ end
31
+ end
@@ -0,0 +1,151 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'git/execution_context'
4
+
5
+ module Git
6
+ class ExecutionContext
7
+ # Execution context for repository-bound git commands
8
+ #
9
+ # Manages the git environment for commands that operate within an existing
10
+ # repository — setting `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, and
11
+ # `GIT_SSH` — and prepending `--git-dir` / `--work-tree` to every git
12
+ # invocation via {#global_opts}.
13
+ #
14
+ # ### Construction
15
+ #
16
+ # Use {.from_hash} to build from a configuration hash:
17
+ #
18
+ # context = Git::ExecutionContext::Repository.from_hash(repository: '/repo/.git', ...)
19
+ #
20
+ # @example Build from a configuration hash
21
+ # context = Git::ExecutionContext::Repository.from_hash(
22
+ # repository: '/path/to/.git',
23
+ # working_directory: '/path/to'
24
+ # )
25
+ #
26
+ # @api private
27
+ #
28
+ class Repository < ExecutionContext
29
+ # Creates a Repository context from a Hash
30
+ #
31
+ # Expected keys: `:repository`, `:working_directory`, `:index`, `:git_ssh`,
32
+ # `:binary_path`
33
+ #
34
+ # @example Build from a configuration hash
35
+ # context = Git::ExecutionContext::Repository.from_hash(
36
+ # repository: '/path/to/.git',
37
+ # working_directory: '/path/to'
38
+ # )
39
+ #
40
+ # @param base_hash [Hash] the hash of repository configuration values
41
+ #
42
+ # @param logger [Logger, nil] logger forwarded to the CommandLine layer;
43
+ # `nil` uses a null logger (see {Git::ExecutionContext#initialize})
44
+ #
45
+ # @return [Git::ExecutionContext::Repository] the new repository context
46
+ #
47
+ def self.from_hash(base_hash, logger: nil)
48
+ new(
49
+ git_dir: base_hash[:repository],
50
+ git_index_file: base_hash[:index],
51
+ git_work_dir: base_hash[:working_directory],
52
+ git_ssh: base_hash.fetch(:git_ssh, :use_global_config),
53
+ binary_path: base_hash.fetch(:binary_path, :use_global_config),
54
+ logger: logger
55
+ )
56
+ end
57
+
58
+ # Creates a new repository execution context
59
+ #
60
+ # @example Create with required git_dir
61
+ # Git::ExecutionContext::Repository.new(git_dir: '/path/to/.git')
62
+ #
63
+ # @param git_dir [String, nil] path to the `.git` directory
64
+ #
65
+ # @param git_work_dir [String, nil] path to the working tree
66
+ #
67
+ # @param git_index_file [String, nil] path to the index file
68
+ #
69
+ # @param binary_path [String, :use_global_config] path to the git binary
70
+ #
71
+ # Give `:use_global_config` (the default) to use
72
+ # `Git::Config.instance.binary_path`.
73
+ #
74
+ # Passing `nil` raises `ArgumentError` — there is no "unset the
75
+ # binary" semantic.
76
+ #
77
+ # @param git_ssh [String, nil, :use_global_config] the SSH wrapper path
78
+ #
79
+ # Give `nil` to unset `GIT_SSH`, or `:use_global_config` (default)
80
+ # to use `Git::Config.instance.git_ssh`.
81
+ #
82
+ # @param logger [Logger, nil] the logger to use in the CommandLine layer
83
+ #
84
+ # Give `nil` to use a null logger (`Logger.new(nil)`).
85
+ #
86
+ # @raise [ArgumentError] if `binary_path` is `nil`
87
+ #
88
+ def initialize( # rubocop:disable Metrics/ParameterLists
89
+ git_dir:,
90
+ git_work_dir: nil,
91
+ git_index_file: nil,
92
+ binary_path: :use_global_config,
93
+ git_ssh: :use_global_config,
94
+ logger: nil
95
+ )
96
+ super(binary_path: binary_path, git_ssh: git_ssh, logger: logger)
97
+ @git_dir = git_dir
98
+ @git_work_dir = git_work_dir
99
+ @git_index_file = git_index_file
100
+ end
101
+
102
+ # @return [String, nil] path to the `.git` directory
103
+ attr_reader :git_dir
104
+
105
+ # @return [String, nil] path to the working tree
106
+ attr_reader :git_work_dir
107
+
108
+ # @return [String, nil] path to the index file
109
+ attr_reader :git_index_file
110
+
111
+ # Returns a new instance with the same configuration, applying `overrides`
112
+ #
113
+ # Uses raw stored values for `binary_path`, `git_ssh`, and `logger` so
114
+ # that `:use_global_config` sentinels are preserved across rebuilds and
115
+ # future changes to `Git.configure` continue to take effect.
116
+ #
117
+ # @param overrides [Hash] keyword arguments to override in the new instance
118
+ #
119
+ # @option overrides [String, nil] :git_dir path to the `.git` directory
120
+ #
121
+ # @option overrides [String, nil] :git_work_dir path to the working tree
122
+ #
123
+ # @option overrides [String, nil] :git_index_file path to the index file
124
+ #
125
+ # @option overrides [String, :use_global_config] :binary_path path to the git
126
+ # binary
127
+ #
128
+ # @option overrides [String, nil, :use_global_config] :git_ssh the SSH
129
+ # wrapper path
130
+ #
131
+ # @option overrides [Logger, nil] :logger the logger to use in the
132
+ # CommandLine layer
133
+ #
134
+ # @return [Git::ExecutionContext::Repository] the new context
135
+ #
136
+ # @api private
137
+ #
138
+ def dup_with(**overrides)
139
+ self.class.new(
140
+ git_dir: @git_dir,
141
+ git_work_dir: @git_work_dir,
142
+ git_index_file: @git_index_file,
143
+ binary_path: @binary_path,
144
+ git_ssh: @git_ssh,
145
+ logger: @logger,
146
+ **overrides
147
+ )
148
+ end
149
+ end
150
+ end
151
+ end