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,77 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Git
4
+ # Immutable value object representing a reference to a file at a specific point in time
5
+ #
6
+ # FileRef encapsulates the mode, SHA, and path of a file as it exists on one side
7
+ # of a diff. This is used to represent either the source (before) or destination
8
+ # (after) state of a file in a diff operation.
9
+ #
10
+ # When a file doesn't exist on a side of the diff (e.g., src for new files,
11
+ # dst for deleted files), the entire FileRef should be nil rather than having
12
+ # a FileRef with nil attributes.
13
+ #
14
+ #
15
+ # @example A modified file's source reference
16
+ # src = Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/foo.rb')
17
+ #
18
+ # @example A new file (src would be nil, not a FileRef)
19
+ # # src = nil
20
+ # dst = Git::FileRef.new(mode: '100644', sha: 'def5678', path: 'lib/new_file.rb')
21
+ #
22
+ # @api private
23
+ #
24
+ # Work in progress; this class is internal for now and may be made public in a future release.
25
+ #
26
+ # @!attribute [r] mode
27
+ # @return [String] the file mode (e.g., '100644' for regular file, '100755' for executable,
28
+ # '120000' for symlink)
29
+ #
30
+ # @!attribute [r] sha
31
+ # @return [String] the blob SHA (object identifier)
32
+ #
33
+ # @!attribute [r] path
34
+ # @return [String] the file path relative to repository root
35
+ #
36
+ FileRef = Data.define(:mode, :sha, :path) do
37
+ # Check if this is a regular file (not executable, symlink, etc.)
38
+ #
39
+ # @return [Boolean] true if mode is 100644
40
+ #
41
+ def regular_file?
42
+ mode == '100644'
43
+ end
44
+
45
+ # Check if this is an executable file
46
+ #
47
+ # @return [Boolean] true if mode is 100755
48
+ #
49
+ def executable?
50
+ mode == '100755'
51
+ end
52
+
53
+ # Check if this is a symbolic link
54
+ #
55
+ # @return [Boolean] true if mode is 120000
56
+ #
57
+ def symlink?
58
+ mode == '120000'
59
+ end
60
+
61
+ # Return the mode as an integer (parsed as octal)
62
+ #
63
+ # Useful for bit operations on file permissions.
64
+ #
65
+ # @example Check file permissions
66
+ # ref.mode_bits & 0o777 # => 0o644 (420 decimal)
67
+ #
68
+ # @example Check if group writable
69
+ # (ref.mode_bits & 0o020) != 0
70
+ #
71
+ # @return [Integer] the mode as an integer
72
+ #
73
+ def mode_bits
74
+ mode.to_i(8)
75
+ end
76
+ end
77
+ end
@@ -10,39 +10,47 @@ module Git
10
10
  #
11
11
  class FsckObject
12
12
  # The type of the Git object
13
+ #
13
14
  # @return [Symbol] one of :commit, :tree, :blob, or :tag
14
15
  attr_reader :type
15
16
 
16
- # The SHA-1 hash of the object
17
- # @return [String] the 40-character SHA-1 hash
18
- attr_reader :sha
17
+ # The object identifier (OID) of the object
18
+ #
19
+ # @return [String] the 40-character object identifier
20
+ attr_reader :oid
19
21
 
20
22
  # A warning or error message associated with this object
23
+ #
21
24
  # @return [String, nil] the message, or nil if no message
22
25
  attr_reader :message
23
26
 
24
27
  # A name describing how the object is reachable (from --name-objects)
28
+ #
25
29
  # @return [String, nil] the name, or nil if not provided
26
30
  attr_reader :name
27
31
 
28
32
  # Create a new FsckObject
29
33
  #
30
34
  # @param type [Symbol] the object type (:commit, :tree, :blob, or :tag)
31
- # @param sha [String] the 40-character SHA-1 hash
35
+ #
36
+ # @param oid [String] the 40-character object identifier
37
+ #
32
38
  # @param message [String, nil] optional warning/error message
39
+ #
33
40
  # @param name [String, nil] optional name from --name-objects (e.g., "HEAD~2^2:src/")
34
41
  #
35
- def initialize(type:, sha:, message: nil, name: nil)
42
+ def initialize(type:, oid:, message: nil, name: nil)
36
43
  @type = type
37
- @sha = sha
44
+ @oid = oid
38
45
  @message = message
39
46
  @name = name
40
47
  end
41
48
 
42
- # Returns the SHA as the string representation
43
- # @return [String] the SHA-1 hash
49
+ # Returns the OID as the string representation
50
+ #
51
+ # @return [String] the object identifier
44
52
  def to_s
45
- sha
53
+ oid
46
54
  end
47
55
  end
48
56
  end
@@ -10,26 +10,32 @@ module Git
10
10
  #
11
11
  class FsckResult
12
12
  # Objects not referenced by any other object
13
+ #
13
14
  # @return [Array<Git::FsckObject>]
14
15
  attr_reader :dangling
15
16
 
16
17
  # Objects that are referenced but not present in the repository
18
+ #
17
19
  # @return [Array<Git::FsckObject>]
18
20
  attr_reader :missing
19
21
 
20
22
  # Objects not reachable from any ref
23
+ #
21
24
  # @return [Array<Git::FsckObject>]
22
25
  attr_reader :unreachable
23
26
 
24
27
  # Objects with warnings (each includes a message)
28
+ #
25
29
  # @return [Array<Git::FsckObject>]
26
30
  attr_reader :warnings
27
31
 
28
32
  # Root nodes (commits with no parents) when --root is used
33
+ #
29
34
  # @return [Array<Git::FsckObject>]
30
35
  attr_reader :root
31
36
 
32
37
  # Tagged objects when --tags is used
38
+ #
33
39
  # @return [Array<Git::FsckObject>]
34
40
  attr_reader :tagged
35
41
 
@@ -38,10 +44,15 @@ module Git
38
44
  # Create a new FsckResult
39
45
  #
40
46
  # @param dangling [Array<Git::FsckObject>] dangling objects
47
+ #
41
48
  # @param missing [Array<Git::FsckObject>] missing objects
49
+ #
42
50
  # @param unreachable [Array<Git::FsckObject>] unreachable objects
51
+ #
43
52
  # @param warnings [Array<Git::FsckObject>] objects with warnings
53
+ #
44
54
  # @param root [Array<Git::FsckObject>] root nodes
55
+ #
45
56
  # @param tagged [Array<Git::FsckObject>] tagged objects
46
57
  #
47
58
  def initialize(dangling: [], missing: [], unreachable: [], warnings: [], root: [], tagged: [])
@@ -57,35 +68,35 @@ module Git
57
68
 
58
69
  # Returns true if any issues were found
59
70
  #
60
- # @return [Boolean]
61
- #
62
- # @example
71
+ # @example Check for repository issues
63
72
  # result = git.fsck
64
73
  # puts "Repository has issues!" if result.any_issues?
65
74
  #
75
+ # @return [Boolean]
76
+ #
66
77
  def any_issues?
67
78
  [dangling, missing, unreachable, warnings].any?(&:any?)
68
79
  end
69
80
 
70
81
  # Returns true if no issues were found
71
82
  #
72
- # @return [Boolean]
73
- #
74
- # @example
83
+ # @example Check if the result is empty
75
84
  # result = git.fsck
76
85
  # puts "Repository is clean" if result.empty?
77
86
  #
87
+ # @return [Boolean]
88
+ #
78
89
  def empty?
79
90
  !any_issues?
80
91
  end
81
92
 
82
93
  # Returns all objects from all categories (excluding informational root/tagged)
83
94
  #
84
- # @return [Array<Git::FsckObject>]
85
- #
86
- # @example
95
+ # @example Iterate over all objects
87
96
  # result = git.fsck
88
- # result.all_objects.each { |obj| puts obj.sha }
97
+ # result.all_objects.each { |obj| puts obj.oid }
98
+ #
99
+ # @return [Array<Git::FsckObject>]
89
100
  #
90
101
  def all_objects
91
102
  dangling + missing + unreachable + warnings
@@ -93,24 +104,24 @@ module Git
93
104
 
94
105
  # Returns the total number of issues found
95
106
  #
96
- # @return [Integer]
97
- #
98
- # @example
107
+ # @example Count all issues
99
108
  # result = git.fsck
100
109
  # puts "Found #{result.count} issues"
101
110
  #
111
+ # @return [Integer]
112
+ #
102
113
  def count
103
114
  all_objects.size
104
115
  end
105
116
 
106
117
  # Returns a hash representation of the result
107
118
  #
108
- # @return [Hash{Symbol => Array<Git::FsckObject>}]
109
- #
110
- # @example
119
+ # @example Convert to a hash
111
120
  # result = git.fsck
112
121
  # result.to_h # => { dangling: [...], missing: [...], ... }
113
122
  #
123
+ # @return [Hash{Symbol => Array<Git::FsckObject>}]
124
+ #
114
125
  def to_h
115
126
  {
116
127
  dangling: dangling, missing: missing, unreachable: unreachable,
data/lib/git/log.rb CHANGED
@@ -9,10 +9,10 @@ module Git
9
9
  # return every matching commit. Calling {#all} adds the `--all` flag to include
10
10
  # all refs in the search but does not change the number of commits returned.
11
11
  #
12
- # The query is lazily executed when results are requested either via the modern
13
- # `#execute` method or the deprecated Enumerable methods.
12
+ # The query runs when {#execute} is called and returns a {Git::Log::Result}
13
+ # holding the matching commits.
14
14
  #
15
- # @example Using the modern `execute` API
15
+ # @example Running a query
16
16
  # log = git.log.max_count(50).between('v1.0', 'v1.1').author('Scott')
17
17
  # results = log.execute
18
18
  # puts "Found #{results.size} commits."
@@ -21,18 +21,60 @@ module Git
21
21
  # @api public
22
22
  #
23
23
  class Log
24
- include Enumerable
25
-
26
24
  # An immutable, Enumerable collection of `Git::Object::Commit` objects.
27
25
  # Returned by `Git::Log#execute`.
26
+ #
28
27
  # @api public
29
28
  Result = Data.define(:commits) do
30
29
  include Enumerable
31
30
 
31
+ # Iterates over each commit in query order
32
+ #
33
+ # @overload each
34
+ # @example Get an enumerator
35
+ # results.each.map(&:sha)
36
+ #
37
+ # @return [Enumerator<Git::Object::Commit>] an enumerator over commits
38
+ #
39
+ # @overload each(&block)
40
+ # @example Iterate with a block
41
+ # results.each { |commit| puts commit.sha }
42
+ #
43
+ # @yield [commit] each commit from the result
44
+ #
45
+ # @yieldparam commit [Git::Object::Commit] a commit in query order
46
+ #
47
+ # @yieldreturn [void]
48
+ #
49
+ # @return [Array<Git::Object::Commit>] the commit array
50
+ #
32
51
  def each(&block) = commits.each(&block)
52
+
53
+ # Returns the last commit in the result
54
+ #
55
+ # @return [Git::Object::Commit, nil] the last commit, or `nil` when empty
56
+ #
33
57
  def last = commits.last
58
+
59
+ # Returns a commit by index or a slice of commits by range
60
+ #
61
+ # @param index [Integer, Range] the commit index or range to retrieve
62
+ #
63
+ # @return [Git::Object::Commit, Array<Git::Object::Commit>, nil] the selected
64
+ # commit or commits
65
+ #
34
66
  def [](index) = commits[index]
67
+
68
+ # Returns the commits joined with newlines
69
+ #
70
+ # @return [String] newline-separated commits
71
+ #
35
72
  def to_s = commits.join("\n")
73
+
74
+ # Returns the number of commits in the result
75
+ #
76
+ # @return [Integer] the commit count
77
+ #
36
78
  def size = commits.size
37
79
  end
38
80
 
@@ -42,7 +84,8 @@ module Git
42
84
  # git = Git.open('.')
43
85
  # Git::Log.new(git)
44
86
  #
45
- # @param base [Git::Base] the git repository object
87
+ # @param base [Git::Repository] the git repository object
88
+ #
46
89
  # @param max_count [Integer, Symbol, nil] the number of commits to return, or
47
90
  # `:all` or `nil` to return all
48
91
  #
@@ -58,17 +101,117 @@ module Git
58
101
  # Set query options using a fluent interface.
59
102
  # Each method returns `self` to allow for chaining.
60
103
  #
104
+ # Sets the maximum number of commits to return
105
+ #
106
+ # @param num [Integer, Symbol, nil] the maximum commit count, or `:all` / `nil`
107
+ # for no limit
108
+ #
109
+ # @return [Git::Log] the current query builder
110
+ #
61
111
  def max_count(num) = set_option(:count, num == :all ? nil : num)
112
+
113
+ # Includes commits reachable from all refs
114
+ #
115
+ # @return [Git::Log] the current query builder
116
+ #
62
117
  def all = set_option(:all, true)
118
+
119
+ # Sets the revision range expression for the log query
120
+ #
121
+ # @param objectish [String] a git revision expression to pass to `git log`
122
+ #
123
+ # @return [Git::Log] the current query builder
124
+ #
63
125
  def object(objectish) = set_option(:object, objectish)
126
+
127
+ # Filters commits by author pattern
128
+ #
129
+ # @param regex [String] a pattern matched against author names
130
+ #
131
+ # @return [Git::Log] the current query builder
132
+ #
64
133
  def author(regex) = set_option(:author, regex)
134
+
135
+ # Filters commits by commit message pattern
136
+ #
137
+ # @param regex [String] a pattern matched against commit messages
138
+ #
139
+ # @return [Git::Log] the current query builder
140
+ #
65
141
  def grep(regex) = set_option(:grep, regex)
142
+
143
+ # Interprets {#grep} and {#author} patterns as Perl-compatible regular expressions
144
+ #
145
+ # Selects PCRE instead of git's default POSIX basic regular expressions for
146
+ # every pattern in the query. Requires a git built with PCRE support.
147
+ #
148
+ # @example Match a metacharacter against a non-ASCII character on Git for Windows
149
+ # repo.log.perl_regexp.grep('^.PFEL').execute
150
+ #
151
+ # @return [Git::Log] the current query builder
152
+ #
153
+ # @note On Git for Windows, git's default regex engine matches *bytes* rather
154
+ # than characters, so a metacharacter such as `.` or a POSIX class such as
155
+ # `[[:alpha:]]` never matches a whole multi-byte character. The match fails
156
+ # silently: git exits zero and the result is empty. PCRE does match characters
157
+ # on that platform, but it is a different dialect than git's default, so
158
+ # selecting it is a deliberate choice by the caller.
159
+ #
160
+ def perl_regexp = set_option(:perl_regexp, true)
161
+
162
+ # Limits commits to those that touch the given path or paths
163
+ #
164
+ # @param path [String, Pathname, Array<String, Pathname>] path limiter input
165
+ #
166
+ # @return [Git::Log] the current query builder
167
+ #
66
168
  def path(path) = set_option(:path_limiter, path)
169
+
170
+ # Skips a number of commits before returning results
171
+ #
172
+ # @param num [Integer] the number of commits to skip
173
+ #
174
+ # @return [Git::Log] the current query builder
175
+ #
67
176
  def skip(num) = set_option(:skip, num)
177
+
178
+ # Includes only commits newer than the given date expression
179
+ #
180
+ # @param date [String] a git-compatible date expression
181
+ #
182
+ # @return [Git::Log] the current query builder
183
+ #
68
184
  def since(date) = set_option(:since, date)
185
+
186
+ # Includes only commits older than the given date expression
187
+ #
188
+ # @param date [String] a git-compatible date expression
189
+ #
190
+ # @return [Git::Log] the current query builder
191
+ #
69
192
  def until(date) = set_option(:until, date)
193
+
194
+ # Limits commits to the given revision range
195
+ #
196
+ # @param val1 [String] the first revision
197
+ #
198
+ # @param val2 [String, nil] the second revision; when `nil`, validation fails
199
+ # at execution time
200
+ #
201
+ # @return [Git::Log] the current query builder
202
+ #
70
203
  def between(val1, val2 = nil) = set_option(:between, [val1, val2])
204
+
205
+ # Omits commits equivalent to cherry-picked commits
206
+ #
207
+ # @return [Git::Log] the current query builder
208
+ #
71
209
  def cherry = set_option(:cherry, true)
210
+
211
+ # Includes only merge commits
212
+ #
213
+ # @return [Git::Log] the current query builder
214
+ #
72
215
  def merges = set_option(:merges, true)
73
216
 
74
217
  # Executes the git log command and returns an immutable result object
@@ -91,76 +234,40 @@ module Git
91
234
  Result.new(@commits)
92
235
  end
93
236
 
94
- # @!group Deprecated Enumerable Interface
95
-
96
- # @deprecated Use {#execute} and call `each` on the result.
97
- def each(&)
98
- Git::Deprecation.warn(
99
- 'Calling Git::Log#each is deprecated. Call #execute and then #each on the result object.'
100
- )
101
- run_log_if_dirty
102
- @commits.each(&)
103
- end
104
-
105
- # @deprecated Use {#execute} and call `size` on the result.
106
- def size
107
- Git::Deprecation.warn(
108
- 'Calling Git::Log#size is deprecated. Call #execute and then #size on the result object.'
109
- )
110
- run_log_if_dirty
111
- @commits&.size
112
- end
113
-
114
- # @deprecated Use {#execute} and call `to_s` on the result.
115
- def to_s
116
- Git::Deprecation.warn(
117
- 'Calling Git::Log#to_s is deprecated. Call #execute and then #to_s on the result object.'
118
- )
119
- run_log_if_dirty
120
- @commits&.join("\n")
121
- end
122
-
123
- # @deprecated Use {#execute} and call the method on the result.
124
- def first
125
- Git::Deprecation.warn(
126
- 'Calling Git::Log#first is deprecated. Call #execute and then #first on the result object.'
127
- )
128
- run_log_if_dirty
129
- @commits&.first
130
- end
131
-
132
- # @deprecated Use {#execute} and call the method on the result.
133
- def last
134
- Git::Deprecation.warn(
135
- 'Calling Git::Log#last is deprecated. Call #execute and then #last on the result object.'
136
- )
137
- run_log_if_dirty
138
- @commits&.last
139
- end
140
-
141
- # @deprecated Use {#execute} and call the method on the result.
142
- def [](index)
143
- Git::Deprecation.warn(
144
- 'Calling Git::Log#[] is deprecated. Call #execute and then #[] on the result object.'
145
- )
146
- run_log_if_dirty
147
- @commits&.[](index)
148
- end
149
-
150
- # @!endgroup
151
-
152
237
  private
153
238
 
239
+ # Sets a log query option and marks cached results dirty
240
+ #
241
+ # @param key [Symbol] the option key
242
+ #
243
+ # @param value [Object] the option value
244
+ #
245
+ # @return [Git::Log] the current query builder
246
+ #
154
247
  def set_option(key, value)
155
248
  @dirty = true
156
249
  @options[key] = value
157
250
  self
158
251
  end
159
252
 
253
+ # @return [Git::Repository]
254
+ #
255
+ def log_repository
256
+ @base
257
+ end
258
+
259
+ # Refreshes cached commits when query options have changed
260
+ #
261
+ # @return [void]
262
+ #
263
+ # @raise [ArgumentError] if configured query options are invalid
264
+ #
265
+ # @raise [Git::FailedError] if the underlying `git log` command fails
266
+ #
160
267
  def run_log_if_dirty
161
268
  return unless @dirty
162
269
 
163
- log_data = @base.lib.full_log_commits(@options)
270
+ log_data = log_repository.full_log_commits(@options)
164
271
  @commits = log_data.map { |c| Git::Object::Commit.new(@base, c['sha'], c) }
165
272
  @dirty = false
166
273
  end