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
data/lib/git/object.rb CHANGED
@@ -1,6 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'git/author'
3
+ require 'git/author_info'
4
4
  require 'git/diff'
5
5
  require 'git/errors'
6
6
  require 'git/log'
@@ -9,11 +9,37 @@ module Git
9
9
  # represents a git object
10
10
  class Object
11
11
  # A base class for all Git objects
12
+ #
13
+ # @api private
14
+ #
12
15
  class AbstractObject
13
- attr_accessor :objectish, :type, :mode
16
+ # @return [String] the object name, SHA, ref, or treeish path
17
+ #
18
+ attr_accessor :objectish
14
19
 
20
+ # @return [String, nil] the git object type
21
+ #
22
+ attr_accessor :type
23
+
24
+ # @return [String, nil] the file mode from tree listings
25
+ #
26
+ attr_accessor :mode
27
+
28
+ # Sets the size of the git object in bytes
29
+ #
30
+ # @example Set the size to 60 bytes
31
+ # object.size = 60
32
+ #
33
+ # @return [Integer] the size of the git object in bytes
34
+ #
15
35
  attr_writer :size
16
36
 
37
+ # Creates a lazy wrapper for a git object
38
+ #
39
+ # @param base [Git::Repository] the repository used to query object data
40
+ #
41
+ # @param objectish [String, #to_s] the object name, SHA, ref, or treeish path
42
+ #
17
43
  def initialize(base, objectish)
18
44
  @base = base
19
45
  @objectish = objectish.to_s
@@ -23,70 +49,241 @@ module Git
23
49
  @sha = nil
24
50
  end
25
51
 
52
+ # Returns the resolved SHA for this object
53
+ #
54
+ # @return [String] the resolved object SHA
55
+ #
26
56
  def sha
27
- @sha ||= @base.lib.rev_parse(@objectish)
57
+ @sha ||= object_repository.rev_parse(@objectish)
28
58
  end
29
59
 
60
+ # Returns the size of this object in bytes
61
+ #
62
+ # @return [Integer] the object size in bytes
63
+ #
30
64
  def size
31
- @size ||= @base.lib.cat_file_size(@objectish)
65
+ @size ||= object_repository.cat_file_size(@objectish)
32
66
  end
33
67
 
34
- # Get the object's contents.
35
- # If no block is given, the contents are cached in memory and returned as a string.
36
- # If a block is given, it yields an IO object (via IO::popen) which could be used to
37
- # read a large file in chunks.
68
+ # Returns the raw content of this git object or streams it into a temporary file
69
+ #
70
+ # Without a block, the full content is buffered in memory and cached, then
71
+ # returned as a `String`. With a block, git output is streamed directly to a
72
+ # temporary file on disk — suitable for large objects.
73
+ #
74
+ # @api public
75
+ #
76
+ # @overload contents
77
+ # Returns the cached content as a string.
78
+ #
79
+ # @return [String] the raw content of the object, cached after first call
80
+ #
81
+ # @raise [Git::FailedError] if the object does not exist or the command fails
82
+ #
83
+ # @example Get the contents of a blob
84
+ # git.object('HEAD:README.md').contents # => "This is a README file\n"
85
+ #
86
+ # @overload contents(&block)
87
+ # Streams the content to a temporary file and yields it.
88
+ #
89
+ # Git output is written directly to a file without buffering in
90
+ # memory. Use this form for large blobs to avoid memory pressure.
91
+ #
92
+ # @yield [file] the temporary file, positioned at the start of the content
93
+ #
94
+ # @yieldparam file [File] readable `IO` object positioned at the beginning
95
+ #
96
+ # @yieldreturn [Object] the value to return from this method
97
+ #
98
+ # @return [Object] the value returned by the block
99
+ #
100
+ # @raise [Git::FailedError] if the object does not exist or the command fails
101
+ #
102
+ # @example Read a large blob without loading it into memory
103
+ # git.object('HEAD:large_file.bin').contents { |f| upload(f) }
38
104
  #
39
- # Use this for large files so that they are not held in memory.
40
105
  def contents(&)
41
106
  if block_given?
42
- @base.lib.cat_file_contents(@objectish, &)
107
+ object_repository.cat_file_contents(@objectish, &)
43
108
  else
44
- @contents ||= @base.lib.cat_file_contents(@objectish)
109
+ @contents ||= object_repository.cat_file_contents(@objectish)
45
110
  end
46
111
  end
47
112
 
113
+ # Returns the object contents split into lines
114
+ #
115
+ # @return [Array<String>] the raw contents split on newline boundaries
116
+ #
48
117
  def contents_array
49
118
  contents.split("\n")
50
119
  end
51
120
 
121
+ # Returns the original object expression
122
+ #
123
+ # @return [String] the object name, SHA, ref, or treeish path
124
+ #
52
125
  def to_s
53
126
  @objectish
54
127
  end
55
128
 
129
+ # Searches this object for matching tracked file contents
130
+ #
131
+ # Always searches this object's resolved SHA. A caller-provided `:object`
132
+ # option is ignored.
133
+ #
134
+ # @param string [String] the pattern to search for
135
+ #
136
+ # @param path_limiter [String, Pathname, Array<String, Pathname>, nil]
137
+ # path or paths to limit the search to
138
+ #
139
+ # @param opts [Hash] additional grep options
140
+ #
141
+ # @option opts [Boolean, nil] :ignore_case (nil) ignore case
142
+ # distinctions in the pattern and file contents
143
+ #
144
+ # Alias: :i
145
+ #
146
+ # @option opts [Boolean, nil] :invert_match (nil) select non-matching
147
+ # lines
148
+ #
149
+ # Alias: :v
150
+ #
151
+ # @option opts [Boolean, nil] :extended_regexp (nil) use POSIX extended
152
+ # regular expressions for the pattern
153
+ #
154
+ # Alias: :E
155
+ #
156
+ # @return [Hash<String, Array<Array(Integer, String)>>] matching lines by path
157
+ #
56
158
  def grep(string, path_limiter = nil, opts = {})
57
- opts = { object: sha, path_limiter: path_limiter }.merge(opts)
58
- @base.lib.grep(string, opts)
159
+ object_repository.grep(string, path_limiter, opts.merge(object: sha))
59
160
  end
60
161
 
162
+ # Returns a diff from this object to another object
163
+ #
164
+ # @param objectish [String] the object name, SHA, ref, or treeish path to diff
165
+ # against
166
+ #
167
+ # @return [Git::Diff] the diff between the two objects
168
+ #
61
169
  def diff(objectish)
62
170
  Git::Diff.new(@base, @objectish, objectish)
63
171
  end
64
172
 
173
+ # Returns a log scoped to this object
174
+ #
175
+ # @param count [Integer] maximum number of commits to include
176
+ #
177
+ # @return [Git::Log] the scoped log object
178
+ #
65
179
  def log(count = 30)
66
180
  Git::Log.new(@base, count).object(@objectish)
67
181
  end
68
182
 
69
- # creates an archive of this object (tree)
183
+ # Creates an archive of this object and writes it to a file
184
+ #
185
+ # @example Archive a tree to a zip file
186
+ # git.object('v1.0').archive('/tmp/release.zip', format: 'zip')
187
+ #
188
+ # @example Archive a tree to a temporary tar file
189
+ # git.object('v2.6').archive(nil, format: 'tar')
190
+ #
191
+ # @example Archive a tree to a tgz file with a path prefix
192
+ # git.object('v2.6').archive('/tmp/release.tgz', format: 'tgz', prefix: 'test/')
193
+ #
194
+ # @example Archive one directory with a path prefix
195
+ # git.object('v2.6').archive(
196
+ # '/tmp/ex-dir.tar',
197
+ # format: 'tar',
198
+ # prefix: 'test/',
199
+ # path: 'ex_dir/'
200
+ # )
201
+ #
202
+ # @param file [String, nil] destination file path; a temp file is created if `nil`
203
+ #
204
+ # @param opts [Hash] archive options (see {Git::Repository#archive})
205
+ #
206
+ # @option opts [String] :format ('zip') archive format: `'tar'`, `'zip'`,
207
+ # or `'tgz'`
208
+ #
209
+ # @option opts [String] :prefix (nil) prefix prepended to every filename
210
+ # in the archive
211
+ #
212
+ # @option opts [String] :path (nil) path within the tree to include
213
+ #
214
+ # @option opts [String] :remote (nil) retrieve the archive from a remote
215
+ # repository
216
+ #
217
+ # @option opts [Boolean, nil] :add_gzip (nil) apply gzip compression after
218
+ # writing the archive
219
+ #
220
+ # @return [String] the path to the written archive file
221
+ #
222
+ # @raise [ArgumentError] when archive options or destination path are invalid
223
+ #
224
+ # @raise [Git::FailedError] if `git archive` fails
225
+ #
226
+ # @note A failure leaves nothing behind and does not replace an existing
227
+ # `file`; see {Git::Repository::ObjectOperations#archive}.
228
+ #
229
+ # @api public
230
+ #
70
231
  def archive(file = nil, opts = {})
71
- @base.lib.archive(@objectish, file, opts)
232
+ object_repository.archive(@objectish, file, opts)
72
233
  end
73
234
 
235
+ # Returns whether this object is a tree
236
+ #
237
+ # @return [Boolean] `true` when this object is a tree
238
+ #
74
239
  def tree? = false
75
240
 
241
+ # Returns whether this object is a blob
242
+ #
243
+ # @return [Boolean] `true` when this object is a blob
244
+ #
76
245
  def blob? = false
77
246
 
247
+ # Returns whether this object is a commit
248
+ #
249
+ # @return [Boolean] `true` when this object is a commit
250
+ #
78
251
  def commit? = false
79
252
 
253
+ # Returns whether this object is a tag
254
+ #
255
+ # @return [Boolean] `true` when this object is a tag
256
+ #
80
257
  def tag? = false
258
+
259
+ private
260
+
261
+ # @return [Git::Repository] the repository used for object lookup
262
+ #
263
+ def object_repository
264
+ @base
265
+ end
81
266
  end
82
267
 
83
268
  # A Git blob object
84
269
  class Blob < AbstractObject
270
+ # Creates a blob object wrapper
271
+ #
272
+ # @param base [Git::Repository] the repository used to query object data
273
+ #
274
+ # @param sha [String] the blob SHA or object expression
275
+ #
276
+ # @param mode [String, nil] the file mode from tree listings
277
+ #
85
278
  def initialize(base, sha, mode = nil)
86
279
  super(base, sha)
87
280
  @mode = mode
88
281
  end
89
282
 
283
+ # Returns whether this object is a blob
284
+ #
285
+ # @return [Boolean] `true`
286
+ #
90
287
  def blob?
91
288
  true
92
289
  end
@@ -94,6 +291,14 @@ module Git
94
291
 
95
292
  # A Git tree object
96
293
  class Tree < AbstractObject
294
+ # Creates a tree object wrapper
295
+ #
296
+ # @param base [Git::Repository] the repository used to query object data
297
+ #
298
+ # @param sha [String] the tree SHA or object expression
299
+ #
300
+ # @param mode [String, nil] the file mode from tree listings
301
+ #
97
302
  def initialize(base, sha, mode = nil)
98
303
  super(base, sha)
99
304
  @mode = mode
@@ -101,29 +306,53 @@ module Git
101
306
  @blobs = nil
102
307
  end
103
308
 
309
+ # Returns child blobs and subtrees keyed by name
310
+ #
311
+ # @return [Hash<String, Git::Object::AbstractObject>] child objects by name
312
+ #
104
313
  def children
105
314
  blobs.merge(subtrees)
106
315
  end
107
316
 
317
+ # Returns blobs directly under this tree
318
+ #
319
+ # @return [Hash<String, Git::Object::Blob>] blob objects by filename
320
+ #
108
321
  def blobs
109
322
  @blobs ||= check_tree[:blobs]
110
323
  end
111
324
  alias files blobs
112
325
 
326
+ # Returns subtrees directly under this tree
327
+ #
328
+ # @return [Hash<String, Git::Object::Tree>] subtree objects by directory name
329
+ #
113
330
  def trees
114
331
  @trees ||= check_tree[:trees]
115
332
  end
116
333
  alias subtrees trees
117
334
  alias subdirectories trees
118
335
 
336
+ # Returns the full tree listing for this tree
337
+ #
338
+ # @return [Hash] parsed recursive tree data
339
+ #
119
340
  def full_tree
120
- @base.lib.full_tree(@objectish)
341
+ object_repository.full_tree(@objectish)
121
342
  end
122
343
 
344
+ # Returns the maximum depth of this tree
345
+ #
346
+ # @return [Integer] maximum tree depth
347
+ #
123
348
  def depth
124
- @base.lib.tree_depth(@objectish)
349
+ object_repository.tree_depth(@objectish)
125
350
  end
126
351
 
352
+ # Returns whether this object is a tree
353
+ #
354
+ # @return [Boolean] `true`
355
+ #
127
356
  def tree?
128
357
  true
129
358
  end
@@ -135,7 +364,7 @@ module Git
135
364
  @trees = {}
136
365
  @blobs = {}
137
366
 
138
- data = @base.lib.ls_tree(@objectish)
367
+ data = object_repository.ls_tree(@objectish)
139
368
 
140
369
  data['tree'].each do |key, tree|
141
370
  @trees[key] = Git::Object::Tree.new(@base, tree[:sha], tree[:mode])
@@ -151,6 +380,14 @@ module Git
151
380
 
152
381
  # A Git commit object
153
382
  class Commit < AbstractObject
383
+ # Creates a commit object wrapper
384
+ #
385
+ # @param base [Git::Repository] the repository used to query object data
386
+ #
387
+ # @param sha [String] the commit SHA or object expression
388
+ #
389
+ # @param init [Hash, nil] parsed commit data used to initialize eagerly
390
+ #
154
391
  def initialize(base, sha, init = nil)
155
392
  super(base, sha)
156
393
  @tree = nil
@@ -163,20 +400,37 @@ module Git
163
400
  from_data(init)
164
401
  end
165
402
 
403
+ # Returns the commit message
404
+ #
405
+ # @return [String] the commit message without the trailing newline
406
+ #
166
407
  def message
167
408
  check_commit
168
409
  @message
169
410
  end
170
411
 
412
+ # Returns the symbolic name for this commit
413
+ #
414
+ # @return [String] the name produced by `git name-rev`
415
+ #
171
416
  def name
172
- @base.lib.name_rev(sha)
417
+ object_repository.name_rev(sha)
173
418
  end
174
419
 
420
+ # Returns the tree for this commit
421
+ #
422
+ # @return [Git::Object::Tree] the commit tree
423
+ #
175
424
  def gtree
176
425
  check_commit
177
426
  Tree.new(@base, @tree)
178
427
  end
179
428
 
429
+ # Returns the first parent commit
430
+ #
431
+ # @return [Git::Object::Commit, nil] the first parent commit, or `nil`
432
+ # for a root commit
433
+ #
180
434
  def parent
181
435
  parents.first
182
436
  end
@@ -187,48 +441,68 @@ module Git
187
441
  @parents
188
442
  end
189
443
 
190
- # git author
444
+ # Returns the commit author identity
445
+ #
446
+ # @return [Git::AuthorInfo] the author name, email, and author date
447
+ #
191
448
  def author
192
449
  check_commit
193
450
  @author
194
451
  end
195
452
 
453
+ # Returns the author date
454
+ #
455
+ # @return [Time] the author timestamp
456
+ #
196
457
  def author_date
197
458
  author.date
198
459
  end
199
460
 
200
- # git author
461
+ # Returns the commit committer identity
462
+ #
463
+ # @return [Git::AuthorInfo] the committer name, email, and commit date
464
+ #
201
465
  def committer
202
466
  check_commit
203
467
  @committer
204
468
  end
205
469
 
470
+ # Returns the committer date
471
+ #
472
+ # @return [Time] the committer timestamp
473
+ #
206
474
  def committer_date
207
475
  committer.date
208
476
  end
209
477
  alias date committer_date
210
478
 
479
+ # Returns the diff between this commit and its first parent
480
+ #
481
+ # @return [Git::Diff] the diff from the first parent to this commit
482
+ #
211
483
  def diff_parent
212
484
  diff(parent)
213
485
  end
214
486
 
215
- def set_commit(data) # rubocop:disable Naming/AccessorMethodName
216
- Git::Deprecation.warn(
217
- 'Git::Object::Commit#set_commit is deprecated and will be removed in a future version. ' \
218
- 'Use #from_data instead.'
219
- )
220
- from_data(data)
221
- end
222
-
487
+ # Loads parsed commit data into this commit object
488
+ #
489
+ # @param data [Hash] parsed commit data from `git cat-file commit`
490
+ #
491
+ # @return [void]
492
+ #
223
493
  def from_data(data)
224
494
  @sha ||= data['sha']
225
- @committer = Git::Author.new(data['committer'])
226
- @author = Git::Author.new(data['author'])
495
+ @committer = Git::AuthorInfo.parse(data['committer'])
496
+ @author = Git::AuthorInfo.parse(data['author'])
227
497
  @tree = Git::Object::Tree.new(@base, data['tree'])
228
498
  @parents = data['parent'].map { |sha| Git::Object::Commit.new(@base, sha) }
229
499
  @message = data['message'].chomp
230
500
  end
231
501
 
502
+ # Returns whether this object is a commit
503
+ #
504
+ # @return [Boolean] `true`
505
+ #
232
506
  def commit?
233
507
  true
234
508
  end
@@ -239,88 +513,24 @@ module Git
239
513
  def check_commit
240
514
  return if @tree
241
515
 
242
- data = @base.lib.cat_file_commit(@objectish)
516
+ data = object_repository.cat_file_commit(@objectish)
243
517
  from_data(data)
244
518
  end
245
519
  end
246
520
 
247
- # A Git tag object
521
+ # if we're calling this, we don't know what type it is yet
522
+ # so this is our little factory method
248
523
  #
249
- # This class represents a tag in Git, which can be either annotated or lightweight.
524
+ # @param base [Git::Repository] the repository used to query object data
250
525
  #
251
- # Annotated tags contain additional metadata such as the tagger's name, email, and
252
- # the date when the tag was created, along with a message.
526
+ # @param objectish [String] the object name, SHA, ref, or treeish path
253
527
  #
254
- # TODO: Annotated tags are not objects
528
+ # @param type [String, nil] object type hint: `blob`, `commit`, or `tree`
255
529
  #
256
- class Tag < AbstractObject
257
- attr_accessor :name
258
-
259
- # @overload initialize(base, name)
260
- # @param base [Git::Base] The Git base object
261
- # @param name [String] The name of the tag
262
- #
263
- # @overload initialize(base, sha, name)
264
- # @param base [Git::Base] The Git base object
265
- # @param sha [String] The SHA of the tag object
266
- # @param name [String] The name of the tag
267
- #
268
- def initialize(base, sha, name = nil)
269
- if name.nil?
270
- name = sha
271
- sha = base.lib.tag_sha(name)
272
- raise Git::UnexpectedResultError, "Tag '#{name}' does not exist." if sha == ''
273
- end
274
-
275
- super(base, sha)
276
-
277
- @name = name
278
- @annotated = nil
279
- @loaded = false
280
- end
281
-
282
- def annotated?
283
- @annotated = @annotated.nil? ? (@base.lib.cat_file_type(name) == 'tag') : @annotated
284
- end
285
-
286
- def message
287
- check_tag
288
- @message
289
- end
290
-
291
- def tag?
292
- true
293
- end
294
-
295
- def tagger
296
- check_tag
297
- @tagger
298
- end
299
-
300
- private
301
-
302
- def check_tag
303
- return if @loaded
304
-
305
- if annotated?
306
- tdata = @base.lib.cat_file_tag(@name)
307
- @message = tdata['message'].chomp
308
- @tagger = Git::Author.new(tdata['tagger'])
309
- else
310
- @message = @tagger = nil
311
- end
312
-
313
- @loaded = true
314
- end
315
- end
316
-
317
- # if we're calling this, we don't know what type it is yet
318
- # so this is our little factory method
319
- def self.new(base, objectish, type = nil, is_tag = false) # rubocop:disable Style/OptionalBooleanParameter
320
- return new_tag(base, objectish) if is_tag
321
-
322
- type ||= base.lib.cat_file_type(objectish)
323
- # TODO: why not handle tag case here too?
530
+ # @return [Git::Object::AbstractObject] the concrete object wrapper
531
+ #
532
+ def self.new(base, objectish, type = nil)
533
+ type ||= object_repository_for(base).cat_file_type(objectish)
324
534
  klass =
325
535
  case type
326
536
  when /blob/ then Blob
@@ -330,9 +540,14 @@ module Git
330
540
  klass.new(base, objectish)
331
541
  end
332
542
 
333
- private_class_method def self.new_tag(base, objectish)
334
- Git::Deprecation.warn('Git::Object.new with is_tag argument is deprecated. Use Git::Object::Tag.new instead.')
335
- Git::Object::Tag.new(base, objectish)
543
+ # Returns the repository used for object lookup
544
+ #
545
+ # @param base [Git::Repository] the repository to return
546
+ #
547
+ # @return [Git::Repository] the repository used for object lookup
548
+ #
549
+ private_class_method def self.object_repository_for(base)
550
+ base
336
551
  end
337
552
  end
338
553
  end