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/base.rb DELETED
@@ -1,1140 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require 'logger'
4
-
5
- module Git
6
- # The main public interface for interacting with Git commands
7
- #
8
- # Instead of creating a Git::Base directly, obtain a Git::Base instance by
9
- # calling one of the follow {Git} class methods: {Git.open}, {Git.init},
10
- # {Git.clone}, or {Git.bare}.
11
- #
12
- # @api public
13
- #
14
- class Base
15
- # (see Git.bare)
16
- def self.bare(git_dir, options = {})
17
- normalize_paths(options, default_repository: git_dir, bare: true)
18
- new(options)
19
- end
20
-
21
- # (see Git.clone)
22
- def self.clone(repository_url, directory, options = {})
23
- lib_options = {}
24
- lib_options[:git_ssh] = options[:git_ssh] if options.key?(:git_ssh)
25
- new_options = LibImpl.new(lib_options, options[:log]).clone(repository_url, directory, options)
26
- normalize_paths(new_options, bare: options[:bare] || options[:mirror])
27
- new(new_options)
28
- end
29
-
30
- # (see Git.default_branch)
31
- def self.repository_default_branch(repository, options = {})
32
- LibImpl.new(nil, options[:log]).repository_default_branch(repository)
33
- end
34
-
35
- # Returns (and initialize if needed) a Git::Config instance
36
- #
37
- # @return [Git::Config] the current config instance.
38
- def self.config
39
- @config ||= Config.new
40
- end
41
-
42
- def self.binary_version(binary_path)
43
- parse_version_string(execute_git_version(binary_path))
44
- end
45
-
46
- private_class_method def self.execute_git_version(binary_path)
47
- bootstrap_command_line(binary_path).run('version', merge: true).stdout
48
- rescue Git::CommandLineError => e
49
- raise "Failed to get git version: #{e.result.status}\n#{e.result.stdout}"
50
- rescue Errno::ENOENT, ProcessExecuter::SpawnError
51
- raise "Failed to get git version: #{binary_path} not found"
52
- end
53
-
54
- private_class_method def self.parse_version_string(raw_string)
55
- version_match = raw_string.match(/\d+(\.\d+)+/)
56
- return [0, 0, 0] unless version_match
57
-
58
- version_parts = version_match[0].split('.').map(&:to_i)
59
- version_parts.fill(0, version_parts.length...3)
60
- end
61
-
62
- # (see Git.init)
63
- def self.init(directory = '.', options = {})
64
- normalize_paths(options, default_working_directory: directory, default_repository: directory,
65
- bare: options[:bare])
66
-
67
- init_options = {
68
- bare: options[:bare],
69
- initial_branch: options[:initial_branch]
70
- }
71
-
72
- directory = options[:bare] ? options[:repository] : options[:working_directory]
73
- FileUtils.mkdir_p(directory)
74
-
75
- # TODO: this dance seems awkward: this creates a Git::Lib so we can call
76
- # init so we can create a new Git::Base which in turn (ultimately)
77
- # creates another/different Git::Lib.
78
- #
79
- # TODO: maybe refactor so this Git::Bare.init does this:
80
- # self.new(opts).init(init_opts) and move all/some of this code into
81
- # Git::Bare#init. This way the init method can be called on any
82
- # repository you have a Git::Base instance for. This would not
83
- # change the existing interface (other than adding to it).
84
- #
85
- LibImpl.new(options).init(init_options)
86
-
87
- new(options)
88
- end
89
-
90
- def self.root_of_worktree(working_dir)
91
- raise ArgumentError, "'#{working_dir}' does not exist" unless Dir.exist?(working_dir)
92
-
93
- execute_rev_parse_toplevel(working_dir)
94
- end
95
-
96
- private_class_method def self.execute_rev_parse_toplevel(working_dir)
97
- bootstrap_command_line(Git::Base.config.binary_path).run(
98
- 'rev-parse', '--show-toplevel', chdir: File.expand_path(working_dir), merge: true, chomp: true
99
- ).stdout
100
- rescue Git::CommandLineError
101
- raise ArgumentError, "'#{working_dir}' is not in a git working tree"
102
- rescue Errno::ENOENT, ProcessExecuter::SpawnError
103
- raise ArgumentError, 'Failed to find the root of the worktree: git binary not found'
104
- end
105
-
106
- # A command line for the git commands that run before a repository is known
107
- #
108
- # `Open3` is deliberately not used here. Windows has no fork, so
109
- # `Process.spawn` implements a redirect of the child's stdin by redirecting
110
- # the *parent's* stdin and restoring it afterward, which replaces the
111
- # process's stdin handle. That leaves a console REPL such as irb or pry
112
- # unable to read input for the rest of the session. `Git::CommandLine`
113
- # redirects only stdout and stderr, so stdin is never disturbed.
114
- #
115
- # @see https://github.com/ruby-git/ruby-git/issues/840 issue 840
116
- #
117
- # @param binary_path [String] the path to the git binary to run
118
- #
119
- # @return [Git::CommandLine] a command line that runs `binary_path` with
120
- # `-c core.quotePath=true -c color.ui=false`
121
- #
122
- # Those are the options the `Open3` calls this replaced passed, kept as they were
123
- # so these two commands behave exactly as before. Neither `git version` nor
124
- # `git rev-parse --show-toplevel` emits colored output, so the remaining `color.*`
125
- # settings in {Git::Lib}'s `STATIC_GLOBAL_OPTS` are not needed here.
126
- #
127
- # @api private
128
- #
129
- private_class_method def self.bootstrap_command_line(binary_path)
130
- Git::CommandLine.new({}, binary_path, ['-c', 'core.quotePath=true', '-c', 'color.ui=false'],
131
- Logger.new(nil))
132
- end
133
-
134
- # (see Git.open)
135
- def self.open(working_dir, options = {})
136
- raise ArgumentError, "'#{working_dir}' is not a directory" unless Dir.exist?(working_dir)
137
-
138
- working_dir = root_of_worktree(working_dir) unless options[:repository]
139
-
140
- normalize_paths(options, default_working_directory: working_dir)
141
-
142
- new(options)
143
- end
144
-
145
- # Create an object that executes Git commands in the context of a working
146
- # copy or a bare repository.
147
- #
148
- # @param [Hash] options The options for this command (see list of valid
149
- # options below)
150
- #
151
- # @option options [Pathname] :working_dir the path to the root of the working
152
- # directory. Should be `nil` if executing commands on a bare repository.
153
- #
154
- # @option options [Pathname] :repository used to specify a non-standard path to
155
- # the repository directory. The default is `"#{working_dir}/.git"`.
156
- #
157
- # @option options [Pathname] :index used to specify a non-standard path to an
158
- # index file. The default is `"#{working_dir}/.git/index"`
159
- #
160
- # @option options [Logger] :log A logger to use for Git operations. Git
161
- # commands are logged at the `:info` level. Additional logging is done
162
- # at the `:debug` level.
163
- #
164
- # @option options [String, nil] :git_ssh Path to a custom SSH executable or script.
165
- # Controls how SSH is configured for this {Git::Base} instance:
166
- # - If this option is not provided, the global Git::Base.config.git_ssh setting is used.
167
- # - If this option is explicitly set to nil, SSH is disabled for this instance.
168
- # - If this option is a non-empty String, that value is used as the SSH command for
169
- # this instance, overriding the global Git::Base.config.git_ssh setting.
170
- #
171
- # @return [Git::Base] an object that can execute git commands in the context
172
- # of the opened working copy or bare repository
173
- #
174
- def initialize(options = {})
175
- options = default_paths(options)
176
- setup_logger(options[:log])
177
- @git_ssh = options.key?(:git_ssh) ? options[:git_ssh] : :use_global_config
178
- initialize_components(options)
179
- end
180
-
181
- # Update the index from the current worktree to prepare the for the next commit
182
- #
183
- # @example
184
- # lib.add('path/to/file')
185
- # lib.add(['path/to/file1','path/to/file2'])
186
- # lib.add(all: true)
187
- #
188
- # @param [String, Array<String>] paths a file or files to be added to the repository (relative to the worktree root)
189
- # @param [Hash] options
190
- #
191
- # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
192
- # @option options [Boolean] :force Allow adding otherwise ignored files
193
- #
194
- def add(paths = '.', **options)
195
- lib.add(paths, options)
196
- end
197
-
198
- # adds a new remote to this repository
199
- # url can be a git url or a Git::Base object if it's a local reference
200
- #
201
- # @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
202
- # @git.fetch('scotts_git')
203
- # @git.merge('scotts_git/master')
204
- #
205
- # Options:
206
- # :fetch => true
207
- # :track => <branch_name>
208
- def add_remote(name, url, opts = {})
209
- url = url.repo.to_s if url.is_a?(Git::Base)
210
- lib.remote_add(name, url, opts)
211
- Git::Remote.new(self, name)
212
- end
213
-
214
- # changes current working directory for a block
215
- # to the git working directory
216
- #
217
- # example
218
- # @git.chdir do
219
- # # write files
220
- # @git.add
221
- # @git.commit('message')
222
- # end
223
- def chdir # :yields: the Git::Path
224
- Dir.chdir(dir.to_s) do
225
- yield dir.to_s
226
- end
227
- end
228
-
229
- # g.config('user.name', 'Scott Chacon') # sets value
230
- # g.config('user.email', 'email@email.com') # sets value
231
- # g.config('user.email', 'email@email.com', file: 'path/to/custom/config) # sets value in file
232
- # g.config('user.name') # returns 'Scott Chacon'
233
- # g.config # returns whole config hash
234
- def config(name = nil, value = nil, options = {})
235
- if name && value
236
- # set value
237
- lib.config_set(name, value, options)
238
- elsif name
239
- # return value
240
- lib.config_get(name)
241
- else
242
- # return hash
243
- lib.config_list
244
- end
245
- end
246
-
247
- # returns a reference to the working directory
248
- # @git.dir.path
249
- # @git.dir.writeable?
250
- def dir
251
- @working_directory
252
- end
253
-
254
- # returns reference to the git index file
255
- attr_reader :index
256
-
257
- # returns reference to the git repository directory
258
- # @git.dir.path
259
- def repo
260
- @repository
261
- end
262
-
263
- # returns the repository size in bytes
264
- def repo_size
265
- all_files = Dir.glob(File.join(repo.path, '**', '*'), File::FNM_DOTMATCH)
266
-
267
- all_files.reject { |file| file.include?('..') }
268
- .map { |file| File.expand_path(file) }
269
- .uniq
270
- .sum { |file| File.stat(file).size.to_i }
271
- end
272
-
273
- def set_index(index_file, check = nil, must_exist: nil)
274
- unless check.nil?
275
- Git::Deprecation.warn(
276
- 'The "check" argument is deprecated and will be removed in a future version. ' \
277
- 'Use "must_exist:" instead.'
278
- )
279
- end
280
-
281
- # default is true
282
- must_exist = must_exist.nil? && check.nil? ? true : must_exist | check
283
-
284
- @lib = nil
285
- @index = Git::Index.new(index_file.to_s, must_exist:)
286
- end
287
-
288
- def set_working(work_dir, check = nil, must_exist: nil)
289
- unless check.nil?
290
- Git::Deprecation.warn(
291
- 'The "check" argument is deprecated and will be removed in a future version. ' \
292
- 'Use "must_exist:" instead.'
293
- )
294
- end
295
-
296
- # default is true
297
- must_exist = must_exist.nil? && check.nil? ? true : must_exist | check
298
-
299
- @lib = nil
300
- @working_directory = Git::WorkingDirectory.new(work_dir.to_s, must_exist:)
301
- end
302
-
303
- # returns +true+ if the branch exists locally
304
- def local_branch?(branch)
305
- branch_names = branches.local.map(&:name)
306
- branch_names.include?(branch)
307
- end
308
-
309
- # @deprecated Use {#local_branch?} instead
310
- def is_local_branch?(branch) # rubocop:disable Naming/PredicatePrefix
311
- Git::Deprecation.warn(
312
- 'Git::Base#is_local_branch? is deprecated and will be removed in a future version. ' \
313
- 'Use Git::Base#local_branch? instead.'
314
- )
315
- local_branch?(branch)
316
- end
317
-
318
- # returns +true+ if the branch exists remotely
319
- def remote_branch?(branch)
320
- branch_names = branches.remote.map(&:name)
321
- branch_names.include?(branch)
322
- end
323
-
324
- # @deprecated Use {#remote_branch?} instead
325
- def is_remote_branch?(branch) # rubocop:disable Naming/PredicatePrefix
326
- Git::Deprecation.warn(
327
- 'Git::Base#is_remote_branch? is deprecated and will be removed in a future version. ' \
328
- 'Use Git::Base#remote_branch? instead.'
329
- )
330
- remote_branch?(branch)
331
- end
332
-
333
- # returns +true+ if the branch exists
334
- def branch?(branch)
335
- branch_names = branches.map(&:name)
336
- branch_names.include?(branch)
337
- end
338
-
339
- # @deprecated Use {#branch?} instead
340
- def is_branch?(branch) # rubocop:disable Naming/PredicatePrefix
341
- Git::Deprecation.warn(
342
- 'Git::Base#is_branch? is deprecated and will be removed in a future version. ' \
343
- 'Use Git::Base#branch? instead.'
344
- )
345
- branch?(branch)
346
- end
347
-
348
- # this is a convenience method for accessing the class that wraps all the
349
- # actual 'git' forked system calls. At some point I hope to replace the Git::Lib
350
- # class with one that uses native methods or libgit C bindings
351
- def lib
352
- @lib ||= LibImpl.new(self, @logger)
353
- end
354
-
355
- # Returns the per-instance git_ssh configuration value.
356
- #
357
- # This may be:
358
- # * a [String] path when an explicit git_ssh command has been configured
359
- # * the Symbol `:use_global_config` when this instance is using the global config
360
- # * `nil` when SSH has been explicitly disabled for this instance
361
- #
362
- # @return [String, Symbol, nil] the git_ssh configuration value for this instance
363
- # @api private
364
- attr_reader :git_ssh
365
-
366
- # Run a grep for 'string' on the HEAD of the git repository
367
- #
368
- # @example Limit grep's scope by calling grep() from a specific object:
369
- # git.object("v2.3").grep('TODO')
370
- #
371
- # @example Using grep results:
372
- # git.grep("TODO").each do |sha, arr|
373
- # puts "in blob #{sha}:"
374
- # arr.each do |line_no, match_string|
375
- # puts "\t line #{line_no}: '#{match_string}'"
376
- # end
377
- # end
378
- #
379
- # @param string [String] the string to search for
380
- # @param path_limiter [String, Pathname, Array<String, Pathname>] a path or array
381
- # of paths to limit the search to or nil for no limit
382
- # @param opts [Hash] options to pass to the underlying `git grep` command
383
- #
384
- # @option opts [Boolean] :ignore_case (false) ignore case when matching
385
- # @option opts [Boolean] :invert_match (false) select non-matching lines
386
- # @option opts [Boolean] :extended_regexp (false) use extended regular expressions
387
- # @option opts [String] :object (HEAD) the object to search from
388
- #
389
- # @return [Hash<String, Array>] a hash of arrays
390
- # ```Ruby
391
- # {
392
- # 'tree-ish1' => [[line_no1, match_string1], ...],
393
- # 'tree-ish2' => [[line_no1, match_string1], ...],
394
- # ...
395
- # }
396
- # ```
397
- #
398
- def grep(string, path_limiter = nil, opts = {})
399
- object('HEAD').grep(string, path_limiter, opts)
400
- end
401
-
402
- # List the files in the worktree that are ignored by git
403
- # @return [Array<String>] the list of ignored files relative to teh root of the worktree
404
- #
405
- def ignored_files
406
- lib.ignored_files
407
- end
408
-
409
- # removes file(s) from the git repository
410
- def rm(path = '.', opts = {})
411
- lib.rm(path, opts)
412
- end
413
-
414
- alias remove rm
415
-
416
- # resets the working directory to the provided commitish
417
- def reset(commitish = nil, opts = {})
418
- lib.reset(commitish, opts)
419
- end
420
-
421
- # resets the working directory to the commitish with '--hard'
422
- def reset_hard(commitish = nil, opts = {})
423
- opts = { hard: true }.merge(opts)
424
- lib.reset(commitish, opts)
425
- end
426
-
427
- # cleans the working directory
428
- #
429
- # options:
430
- # :force
431
- # :d
432
- # :ff
433
- #
434
- def clean(opts = {})
435
- lib.clean(opts)
436
- end
437
-
438
- # returns the most recent tag that is reachable from a commit
439
- #
440
- # options:
441
- # :all
442
- # :tags
443
- # :contains
444
- # :debug
445
- # :exact_match
446
- # :dirty
447
- # :abbrev
448
- # :candidates
449
- # :long
450
- # :always
451
- # :match
452
- #
453
- def describe(committish = nil, opts = {})
454
- lib.describe(committish, opts)
455
- end
456
-
457
- # reverts the working directory to the provided commitish.
458
- # Accepts a range, such as comittish..HEAD
459
- #
460
- # options:
461
- # :no_edit
462
- #
463
- def revert(commitish = nil, opts = {})
464
- lib.revert(commitish, opts)
465
- end
466
-
467
- # commits all pending changes in the index file to the git repository
468
- #
469
- # options:
470
- # :all
471
- # :allow_empty
472
- # :amend
473
- # :author
474
- #
475
- def commit(message, opts = {})
476
- lib.commit(message, opts)
477
- end
478
-
479
- # commits all pending changes in the index file to the git repository,
480
- # but automatically adds all modified files without having to explicitly
481
- # calling @git.add() on them.
482
- def commit_all(message, opts = {})
483
- opts = { add_all: true }.merge(opts)
484
- lib.commit(message, opts)
485
- end
486
-
487
- # checks out a branch as the new git working directory
488
- def checkout(*, **)
489
- lib.checkout(*, **)
490
- end
491
-
492
- # checks out an old version of a file
493
- def checkout_file(version, file)
494
- lib.checkout_file(version, file)
495
- end
496
-
497
- # fetches changes from a remote branch - this does not modify the working directory,
498
- # it just gets the changes from the remote if there are any
499
- def fetch(remote = 'origin', opts = {})
500
- if remote.is_a?(Hash)
501
- opts = remote
502
- remote = nil
503
- end
504
- lib.fetch(remote, opts)
505
- end
506
-
507
- # Push changes to a remote repository
508
- #
509
- # @overload push(remote = nil, branch = nil, options = {})
510
- # @param remote [String] the remote repository to push to
511
- # @param branch [String] the branch to push
512
- # @param options [Hash] options to pass to the push command
513
- #
514
- # @option opts [Boolean] :mirror (false) Push all refs under refs/heads/, refs/tags/ and refs/remotes/
515
- # @option opts [Boolean] :delete (false) Delete refs that don't exist on the remote
516
- # @option opts [Boolean] :force (false) Force updates
517
- # @option opts [Boolean] :tags (false) Push all refs under refs/tags/
518
- # @option opts [Array, String] :push_options (nil) Push options to transmit
519
- #
520
- # @return [Void]
521
- #
522
- # @raise [Git::FailedError] if the push fails
523
- # @raise [ArgumentError] if a branch is given without a remote
524
- #
525
- def push(*, **)
526
- lib.push(*, **)
527
- end
528
-
529
- # merges one or more branches into the current working branch
530
- #
531
- # you can specify more than one branch to merge by passing an array of branches
532
- def merge(branch, message = 'merge', opts = {})
533
- lib.merge(branch, message, opts)
534
- end
535
-
536
- # iterates over the files which are unmerged
537
- def each_conflict(&) # :yields: file, your_version, their_version
538
- lib.conflicts(&)
539
- end
540
-
541
- # Pulls the given branch from the given remote into the current branch
542
- #
543
- # @param remote [String] the remote repository to pull from
544
- # @param branch [String] the branch to pull from
545
- # @param opts [Hash] options to pass to the pull command
546
- #
547
- # @option opts [Boolean] :allow_unrelated_histories (false) Merges histories of
548
- # two projects that started their lives independently
549
- # @example pulls from origin/master
550
- # @git.pull
551
- # @example pulls from upstream/master
552
- # @git.pull('upstream')
553
- # @example pulls from upstream/develop
554
- # @git.pull('upstream', 'develop')
555
- #
556
- # @return [Void]
557
- #
558
- # @raise [Git::FailedError] if the pull fails
559
- # @raise [ArgumentError] if a branch is given without a remote
560
- def pull(remote = nil, branch = nil, opts = {})
561
- lib.pull(remote, branch, opts)
562
- end
563
-
564
- # returns an array of Git:Remote objects
565
- def remotes
566
- lib.remotes.map { |r| Git::Remote.new(self, r) }
567
- end
568
-
569
- # sets the url for a remote
570
- # url can be a git url or a Git::Base object if it's a local reference
571
- #
572
- # @git.set_remote_url('scotts_git', 'git://repo.or.cz/rubygit.git')
573
- #
574
- def set_remote_url(name, url)
575
- url = url.repo.to_s if url.is_a?(Git::Base)
576
- lib.remote_set_url(name, url)
577
- Git::Remote.new(self, name)
578
- end
579
-
580
- # Configures which branches are fetched for a remote
581
- #
582
- # Uses `git remote set-branches` to set or append fetch refspecs. When the `add:`
583
- # option is not given, the `--add` option is not passed to the git command
584
- #
585
- # @example Replace fetched branches with a single glob pattern
586
- # git = Git.open('/path/to/repo')
587
- # # Only fetch branches matching "feature/*" from origin
588
- # git.remote_set_branches('origin', 'feature/*')
589
- #
590
- # @example Append a glob pattern to existing fetched branches
591
- # git = Git.open('/path/to/repo')
592
- # # Keep existing fetch refspecs and add all release branches
593
- # git.remote_set_branches('origin', 'release/*', add: true)
594
- #
595
- # @example Configure multiple explicit branches
596
- # git = Git.open('/path/to/repo')
597
- # git.remote_set_branches('origin', 'main', 'development', 'hotfix')
598
- #
599
- # @param name [String] the remote name (for example, "origin")
600
- # @param branches [Array<String>] branch names or globs (for example, '*')
601
- # @param add [Boolean] when true, append to existing refspecs instead of replacing them
602
- #
603
- # @return [nil]
604
- #
605
- # @raise [ArgumentError] if no branches are provided @raise [Git::FailedError] if
606
- # the underlying git command fails
607
- #
608
- def remote_set_branches(name, *branches, add: false)
609
- branch_list = branches.flatten
610
- raise ArgumentError, 'branches are required' if branch_list.empty?
611
-
612
- lib.remote_set_branches(name, branch_list, add: add)
613
-
614
- nil
615
- end
616
-
617
- # removes a remote from this repository
618
- #
619
- # @git.remove_remote('scott_git')
620
- def remove_remote(name)
621
- lib.remote_remove(name)
622
- end
623
-
624
- # returns an array of all Git::Tag objects for this repository
625
- def tags
626
- lib.tags.map { |r| tag(r) }
627
- end
628
-
629
- # Create a new git tag
630
- #
631
- # @example
632
- # repo.add_tag('tag_name', object_reference)
633
- # repo.add_tag('tag_name', object_reference, {:options => 'here'})
634
- # repo.add_tag('tag_name', {:options => 'here'})
635
- #
636
- # @param [String] name The name of the tag to add
637
- # @param [Hash] options Opstions to pass to `git tag`.
638
- # See [git-tag](https://git-scm.com/docs/git-tag) for more details.
639
- # @option options [boolean] :annotate Make an unsigned, annotated tag object
640
- # @option options [boolean] :a An alias for the `:annotate` option
641
- # @option options [boolean] :d Delete existing tag with the given names.
642
- # @option options [boolean] :f Replace an existing tag with the given name (instead of failing)
643
- # @option options [String] :message Use the given tag message
644
- # @option options [String] :m An alias for the `:message` option
645
- # @option options [boolean] :s Make a GPG-signed tag.
646
- #
647
- def add_tag(name, *options)
648
- lib.tag(name, *options)
649
- tag(name)
650
- end
651
-
652
- # deletes a tag
653
- def delete_tag(name)
654
- lib.tag(name, { d: true })
655
- end
656
-
657
- # creates an archive file of the given tree-ish
658
- def archive(treeish, file = nil, opts = {})
659
- object(treeish).archive(file, opts)
660
- end
661
-
662
- # repacks the repository
663
- def repack
664
- lib.repack
665
- end
666
-
667
- def gc
668
- lib.gc
669
- end
670
-
671
- # Verifies the connectivity and validity of objects in the database
672
- #
673
- # Runs `git fsck` to check repository integrity and identify dangling,
674
- # missing, or unreachable objects.
675
- #
676
- # @overload fsck(objects = [], options = {})
677
- # @param objects [Array<String>] specific objects to treat as heads for unreachability trace.
678
- # If no objects are given, git fsck defaults to using the index file, all SHA-1
679
- # references in the refs namespace, and all reflogs.
680
- # @param [Hash] options options to pass to the underlying `git fsck` command
681
- #
682
- # @option options [Boolean] :unreachable print unreachable objects
683
- # @option options [Boolean] :strict enable strict checking
684
- # @option options [Boolean] :connectivity_only check only connectivity (faster)
685
- # @option options [Boolean] :root report root nodes
686
- # @option options [Boolean] :tags report tags
687
- # @option options [Boolean] :cache consider objects in the index
688
- # @option options [Boolean] :no_reflogs do not consider reflogs
689
- # @option options [Boolean] :lost_found write dangling objects to .git/lost-found
690
- # (note: this modifies the repository by creating files)
691
- # @option options [Boolean, nil] :dangling print dangling objects (true/false/nil for default)
692
- # @option options [Boolean, nil] :full check objects in alternate pools (true/false/nil for default)
693
- # @option options [Boolean, nil] :name_objects name objects by refs (true/false/nil for default)
694
- # @option options [Boolean, nil] :references check refs database consistency (true/false/nil for default)
695
- #
696
- # @return [Git::FsckResult] categorized objects flagged by fsck
697
- #
698
- # @example Check repository integrity
699
- # result = git.fsck
700
- # result.dangling.each { |obj| puts "#{obj.type}: #{obj.sha}" }
701
- #
702
- # @example Check with strict mode and suppress dangling output
703
- # result = git.fsck(strict: true, dangling: false)
704
- #
705
- # @example Check if repository has any issues
706
- # result = git.fsck
707
- # puts "Repository is clean" if result.empty?
708
- #
709
- # @example List root commits
710
- # result = git.fsck(root: true)
711
- # result.root.each { |obj| puts obj.sha }
712
- #
713
- # @example Check specific objects
714
- # result = git.fsck('abc1234', 'def5678')
715
- #
716
- def fsck(*objects, **opts) # rubocop:disable Style/ArgumentsForwarding
717
- lib.fsck(*objects, **opts) # rubocop:disable Style/ArgumentsForwarding
718
- end
719
-
720
- def apply(file)
721
- return unless File.exist?(file)
722
-
723
- lib.apply(file)
724
- end
725
-
726
- def apply_mail(file)
727
- lib.apply_mail(file) if File.exist?(file)
728
- end
729
-
730
- # Shows objects
731
- #
732
- # @param [String|NilClass] objectish the target object reference (nil == HEAD)
733
- # @param [String|NilClass] path the path of the file to be shown
734
- # @return [String] the object information
735
- def show(objectish = nil, path = nil)
736
- lib.show(objectish, path)
737
- end
738
-
739
- ## LOWER LEVEL INDEX OPERATIONS ##
740
-
741
- def with_index(new_index) # :yields: new_index
742
- old_index = @index
743
- set_index(new_index, false)
744
- return_value = yield @index
745
- set_index(old_index)
746
- return_value
747
- end
748
-
749
- def with_temp_index(&)
750
- # Workaround for JRUBY, since they handle the TempFile path different.
751
- # MUST be improved to be safer and OS independent.
752
- if RUBY_PLATFORM == 'java'
753
- temp_path = "/tmp/temp-index-#{(0...15).map { ('a'..'z').to_a[rand(26)] }.join}"
754
- else
755
- tempfile = Tempfile.new('temp-index')
756
- temp_path = tempfile.path
757
- tempfile.close
758
- tempfile.unlink
759
- end
760
-
761
- with_index(temp_path, &)
762
- end
763
-
764
- def checkout_index(opts = {})
765
- lib.checkout_index(opts)
766
- end
767
-
768
- def read_tree(treeish, opts = {})
769
- lib.read_tree(treeish, opts)
770
- end
771
-
772
- def write_tree
773
- lib.write_tree
774
- end
775
-
776
- def write_and_commit_tree(opts = {})
777
- tree = write_tree
778
- commit_tree(tree, opts)
779
- end
780
-
781
- def update_ref(branch, commit)
782
- branch(branch).update_ref(commit)
783
- end
784
-
785
- def ls_files(location = nil)
786
- lib.ls_files(location)
787
- end
788
-
789
- def with_working(work_dir) # :yields: the Git::WorkingDirectory
790
- return_value = false
791
- old_working = @working_directory
792
- set_working(work_dir)
793
- Dir.chdir work_dir do
794
- return_value = yield @working_directory
795
- end
796
- set_working(old_working)
797
- return_value
798
- end
799
-
800
- def with_temp_working(&)
801
- tempfile = Tempfile.new('temp-workdir')
802
- temp_dir = tempfile.path
803
- tempfile.close
804
- tempfile.unlink
805
- Dir.mkdir(temp_dir, 0o700)
806
- with_working(temp_dir, &)
807
- end
808
-
809
- # runs git rev-parse to convert the objectish to a full sha
810
- #
811
- # @example
812
- # git.rev_parse("HEAD^^")
813
- # git.rev_parse('v2.4^{tree}')
814
- # git.rev_parse('v2.4:/doc/index.html')
815
- #
816
- def rev_parse(objectish)
817
- lib.rev_parse(objectish)
818
- end
819
-
820
- # For backwards compatibility
821
- alias revparse rev_parse
822
-
823
- def ls_tree(objectish, opts = {})
824
- lib.ls_tree(objectish, opts)
825
- end
826
-
827
- # Returns the contents of a git object
828
- #
829
- # Uses `git cat-file -p` to pretty-print the contents of the given object.
830
- #
831
- # @param objectish [String] a SHA, branch name, tag, or other revision reference
832
- # to the git object
833
- #
834
- # @return [String] the contents of the object
835
- #
836
- # @see https://git-scm.com/docs/git-cat-file git-cat-file
837
- #
838
- def cat_file(objectish)
839
- lib.cat_file_contents(objectish)
840
- end
841
-
842
- # The name of the branch HEAD refers to or 'HEAD' if detached
843
- #
844
- # Returns one of the following:
845
- # * The branch name that HEAD refers to (even if it is an unborn branch)
846
- # * 'HEAD' if in a detached HEAD state
847
- #
848
- # @return [String] the name of the branch HEAD refers to or 'HEAD' if detached
849
- #
850
- def current_branch
851
- lib.branch_current
852
- end
853
-
854
- # @return [Git::Branch] an object for branch_name
855
- def branch(branch_name = current_branch)
856
- Git::Branch.new(self, branch_name)
857
- end
858
-
859
- # @return [Git::Branches] a collection of all the branches in the repository.
860
- # Each branch is represented as a {Git::Branch}.
861
- def branches
862
- Git::Branches.new(self)
863
- end
864
-
865
- # returns a Git::Worktree object for dir, commitish
866
- def worktree(dir, commitish = nil)
867
- Git::Worktree.new(self, dir, commitish)
868
- end
869
-
870
- # returns a Git::worktrees object of all the Git::Worktrees
871
- # objects for this repo
872
- def worktrees
873
- Git::Worktrees.new(self)
874
- end
875
-
876
- # @return [Git::Object::Commit] a commit object
877
- def commit_tree(tree = nil, opts = {})
878
- Git::Object::Commit.new(self, lib.commit_tree(tree, opts))
879
- end
880
-
881
- # @return [Git::Diff] a Git::Diff object
882
- def diff(objectish = 'HEAD', obj2 = nil)
883
- Git::Diff.new(self, objectish, obj2)
884
- end
885
-
886
- # @return [Git::Object] a Git object
887
- def gblob(objectish)
888
- Git::Object.new(self, objectish, 'blob')
889
- end
890
-
891
- # @return [Git::Object] a Git object
892
- def gcommit(objectish)
893
- Git::Object.new(self, objectish, 'commit')
894
- end
895
-
896
- # @return [Git::Object] a Git object
897
- def gtree(objectish)
898
- Git::Object.new(self, objectish, 'tree')
899
- end
900
-
901
- # @return [Git::Log] a log with the specified number of commits
902
- def log(count = 30)
903
- Git::Log.new(self, count)
904
- end
905
-
906
- # returns a Git::Object of the appropriate type
907
- # you can also call @git.gtree('tree'), but that's
908
- # just for readability. If you call @git.gtree('HEAD') it will
909
- # still return a Git::Object::Commit object.
910
- #
911
- # object calls a method that will run a rev-parse
912
- # on the objectish and determine the type of the object and return
913
- # an appropriate object for that type
914
- #
915
- # @return [Git::Object] an instance of the appropriate type of Git::Object
916
- def object(objectish)
917
- Git::Object.new(self, objectish)
918
- end
919
-
920
- # @return [Git::Remote] a remote of the specified name
921
- def remote(remote_name = 'origin')
922
- Git::Remote.new(self, remote_name)
923
- end
924
-
925
- # @return [Git::Status] a status object
926
- def status
927
- Git::Status.new(self)
928
- end
929
-
930
- # @return [Git::Object::Tag] a tag object
931
- def tag(tag_name)
932
- Git::Object::Tag.new(self, tag_name)
933
- end
934
-
935
- # Find as good common ancestors as possible for a merge
936
- # example: g.merge_base('master', 'some_branch', 'some_sha', octopus: true)
937
- #
938
- # @return [Array<Git::Object::Commit>] a collection of common ancestors
939
- def merge_base(*)
940
- shas = lib.merge_base(*)
941
- shas.map { |sha| gcommit(sha) }
942
- end
943
-
944
- # Returns a Git::Diff::Stats object for accessing diff statistics.
945
- #
946
- # @param objectish [String] The first commit or object to compare. Defaults to 'HEAD'.
947
- # @param obj2 [String, nil] The second commit or object to compare.
948
- # @param opts [Hash] Options to filter the diff.
949
- # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter Limit stats to specified path(s).
950
- # @return [Git::DiffStats]
951
- def diff_stats(objectish = 'HEAD', obj2 = nil, opts = {})
952
- Git::DiffStats.new(self, objectish, obj2, opts[:path_limiter])
953
- end
954
-
955
- # Returns a Git::Diff::PathStatus object for accessing the name-status report.
956
- #
957
- # @param objectish [String] The first commit or object to compare. Defaults to 'HEAD'.
958
- # @param obj2 [String, nil] The second commit or object to compare.
959
- # @param opts [Hash] Options to filter the diff.
960
- # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter Limit status to specified path(s).
961
- # @option opts [String, Pathname, Array<String, Pathname>] :path (deprecated) Legacy alias for :path_limiter.
962
- # @return [Git::DiffPathStatus]
963
- def diff_path_status(objectish = 'HEAD', obj2 = nil, opts = {})
964
- path_limiter = if opts.key?(:path_limiter)
965
- opts[:path_limiter]
966
- elsif opts.key?(:path)
967
- Git::Deprecation.warn(
968
- 'Git::Base#diff_path_status :path option is deprecated. Use :path_limiter instead.'
969
- )
970
- opts[:path]
971
- end
972
-
973
- Git::DiffPathStatus.new(self, objectish, obj2, path_limiter)
974
- end
975
-
976
- # Provided for backwards compatibility
977
- alias diff_name_status diff_path_status
978
-
979
- private
980
-
981
- # Sets default paths in the options hash for direct `Git::Base.new` calls
982
- #
983
- # Factory methods like `Git.open` pre-populate these options by calling
984
- # `normalize_paths`, making this a fallback. It avoids mutating the
985
- # original options hash by returning a new one.
986
- #
987
- # @param options [Hash] the original options hash
988
- # @return [Hash] a new options hash with defaults applied
989
- def default_paths(options)
990
- return options unless (working_dir = options[:working_directory])
991
-
992
- options.dup.tap do |opts|
993
- opts[:repository] ||= File.join(working_dir, '.git')
994
- opts[:index] ||= File.join(opts[:repository], 'index')
995
- end
996
- end
997
-
998
- # Initializes the logger from the provided options
999
- # @param log_option [Logger, nil] The logger instance from options.
1000
- def setup_logger(log_option)
1001
- @logger = log_option || Logger.new(nil)
1002
- @logger.info('Starting Git')
1003
- end
1004
-
1005
- # Initializes the core git objects based on the provided options
1006
- # @param options [Hash] The processed options hash.
1007
- def initialize_components(options)
1008
- @working_directory = Git::WorkingDirectory.new(options[:working_directory]) if options[:working_directory]
1009
- @repository = Git::Repository.new(options[:repository]) if options[:repository]
1010
- @index = Git::Index.new(options[:index], must_exist: false) if options[:index]
1011
- end
1012
-
1013
- # Normalize options before they are sent to Git::Base.new
1014
- #
1015
- # Updates the options parameter by setting appropriate values for the following keys:
1016
- # * options[:working_directory]
1017
- # * options[:repository]
1018
- # * options[:index]
1019
- #
1020
- # All three values will be set to absolute paths. An exception is that
1021
- # :working_directory will be set to nil if bare is true.
1022
- #
1023
- private_class_method def self.normalize_paths(
1024
- options, default_working_directory: nil, default_repository: nil, bare: false
1025
- )
1026
- normalize_working_directory(options, default: default_working_directory, bare: bare)
1027
- normalize_repository(options, default: default_repository, bare: bare)
1028
- normalize_index(options)
1029
- end
1030
-
1031
- # Normalize options[:working_directory]
1032
- #
1033
- # If working with a bare repository, set to `nil`.
1034
- # Otherwise, set to the first non-nil value of:
1035
- # 1. `options[:working_directory]`,
1036
- # 2. the `default` parameter, or
1037
- # 3. the current working directory
1038
- #
1039
- # Finally, if options[:working_directory] is a relative path, convert it to an absoluite
1040
- # path relative to the current directory.
1041
- #
1042
- private_class_method def self.normalize_working_directory(options, default:, bare: false)
1043
- working_directory =
1044
- if bare
1045
- nil
1046
- else
1047
- File.expand_path(options[:working_directory] || default || Dir.pwd)
1048
- end
1049
-
1050
- options[:working_directory] = working_directory
1051
- end
1052
-
1053
- # Normalize options[:repository]
1054
- #
1055
- # If working with a bare repository, set to the first non-nil value out of:
1056
- # 1. `options[:repository]`
1057
- # 2. the `default` parameter
1058
- # 3. the current working directory
1059
- #
1060
- # Otherwise, set to the first non-nil value of:
1061
- # 1. `options[:repository]`
1062
- # 2. `.git`
1063
- #
1064
- # Next, if options[:repository] refers to a *file* and not a *directory*, set
1065
- # options[:repository] to the contents of that file. This is the case when
1066
- # working with a submodule or a secondary working tree (created with git worktree
1067
- # add). In these cases the repository is actually contained/nested within the
1068
- # parent's repository directory.
1069
- #
1070
- # Finally, if options[:repository] is a relative path, convert it to an absolute
1071
- # path relative to:
1072
- # 1. the current directory if working with a bare repository or
1073
- # 2. the working directory if NOT working with a bare repository
1074
- #
1075
- private_class_method def self.normalize_repository(options, default:, bare: false)
1076
- initial_path = initial_repository_path(options, default: default, bare: bare)
1077
- final_path = resolve_gitdir_if_present(initial_path, options[:working_directory])
1078
- options[:repository] = final_path
1079
- end
1080
-
1081
- # Determines the initial, potential path to the repository directory
1082
- #
1083
- # This path is considered 'initial' because it is not guaranteed to be the
1084
- # final repository location. For features like submodules or worktrees,
1085
- # this path may point to a text file containing a `gitdir:` pointer to the
1086
- # actual repository directory elsewhere. This initial path must be
1087
- # subsequently resolved.
1088
- #
1089
- # @api private
1090
- #
1091
- # @param options [Hash] The options hash, checked for `[:repository]`.
1092
- #
1093
- # @param default [String] A fallback path if `options[:repository]` is not set.
1094
- #
1095
- # @param bare [Boolean] Whether the repository is bare, which changes path resolution.
1096
- #
1097
- # @return [String] The initial, absolute path to the `.git` directory or file.
1098
- #
1099
- private_class_method def self.initial_repository_path(options, default:, bare:)
1100
- if bare
1101
- File.expand_path(options[:repository] || default || Dir.pwd)
1102
- else
1103
- File.expand_path(options[:repository] || '.git', options[:working_directory])
1104
- end
1105
- end
1106
-
1107
- # Resolves the path to the actual repository if it's a `gitdir:` pointer file.
1108
- #
1109
- # If `path` points to a file (common in submodules and worktrees), this
1110
- # method reads the `gitdir:` path from it and returns the real repository
1111
- # path. Otherwise, it returns the original path.
1112
- #
1113
- # @api private
1114
- #
1115
- # @param path [String] The initial path to the repository, which may be a pointer file.
1116
- #
1117
- # @param working_dir [String] The working directory, used as a base to resolve the path.
1118
- #
1119
- # @return [String] The final, resolved absolute path to the repository directory.
1120
- #
1121
- private_class_method def self.resolve_gitdir_if_present(path, working_dir)
1122
- return path unless File.file?(path)
1123
-
1124
- # The file contains `gitdir: <path>`, so we read the file,
1125
- # extract the path part, and expand it.
1126
- gitdir_pointer = File.read(path).sub(/\Agitdir: /, '').strip
1127
- File.expand_path(gitdir_pointer, working_dir)
1128
- end
1129
-
1130
- # Normalize options[:index]
1131
- #
1132
- # If options[:index] is a relative directory, convert it to an absolute
1133
- # directory relative to the repository directory
1134
- #
1135
- private_class_method def self.normalize_index(options)
1136
- index = File.expand_path(options[:index] || 'index', options[:repository])
1137
- options[:index] = index
1138
- end
1139
- end
1140
- end