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.
- checksums.yaml +4 -4
- data/.yardopts +1 -0
- data/CHANGELOG.md +348 -39
- data/CONTRIBUTING.md +1014 -144
- data/README.md +386 -504
- data/UPGRADING.md +1822 -0
- data/git.gemspec +102 -22
- data/lib/git/author_info.rb +65 -0
- data/lib/git/branch_delete_failure.rb +34 -0
- data/lib/git/branch_delete_result.rb +66 -0
- data/lib/git/branch_info.rb +237 -0
- data/lib/git/command_line/base.rb +247 -0
- data/lib/git/command_line/capturing.rb +308 -0
- data/lib/git/command_line/result.rb +88 -0
- data/lib/git/command_line/streaming.rb +236 -0
- data/lib/git/command_line.rb +45 -323
- data/lib/git/commands/add.rb +139 -0
- data/lib/git/commands/am/abort.rb +43 -0
- data/lib/git/commands/am/apply.rb +263 -0
- data/lib/git/commands/am/continue.rb +43 -0
- data/lib/git/commands/am/quit.rb +43 -0
- data/lib/git/commands/am/retry.rb +49 -0
- data/lib/git/commands/am/show_current_patch.rb +64 -0
- data/lib/git/commands/am/skip.rb +42 -0
- data/lib/git/commands/am.rb +33 -0
- data/lib/git/commands/apply.rb +242 -0
- data/lib/git/commands/archive/list_formats.rb +46 -0
- data/lib/git/commands/archive.rb +145 -0
- data/lib/git/commands/arguments.rb +4521 -0
- data/lib/git/commands/base.rb +522 -0
- data/lib/git/commands/branch/copy.rb +102 -0
- data/lib/git/commands/branch/create.rb +177 -0
- data/lib/git/commands/branch/delete.rb +88 -0
- data/lib/git/commands/branch/list.rb +178 -0
- data/lib/git/commands/branch/move.rb +102 -0
- data/lib/git/commands/branch/set_upstream.rb +86 -0
- data/lib/git/commands/branch/show_current.rb +49 -0
- data/lib/git/commands/branch/unset_upstream.rb +53 -0
- data/lib/git/commands/branch.rb +34 -0
- data/lib/git/commands/cat_file/batch.rb +385 -0
- data/lib/git/commands/cat_file/filtered.rb +105 -0
- data/lib/git/commands/cat_file/raw.rb +203 -0
- data/lib/git/commands/cat_file.rb +49 -0
- data/lib/git/commands/checkout/branch.rb +153 -0
- data/lib/git/commands/checkout/files.rb +116 -0
- data/lib/git/commands/checkout.rb +38 -0
- data/lib/git/commands/checkout_index.rb +106 -0
- data/lib/git/commands/clean.rb +102 -0
- data/lib/git/commands/clone.rb +241 -0
- data/lib/git/commands/commit.rb +273 -0
- data/lib/git/commands/commit_tree.rb +101 -0
- data/lib/git/commands/config_option_syntax/add.rb +86 -0
- data/lib/git/commands/config_option_syntax/get.rb +121 -0
- data/lib/git/commands/config_option_syntax/get_all.rb +118 -0
- data/lib/git/commands/config_option_syntax/get_color.rb +95 -0
- data/lib/git/commands/config_option_syntax/get_color_bool.rb +96 -0
- data/lib/git/commands/config_option_syntax/get_regexp.rb +119 -0
- data/lib/git/commands/config_option_syntax/get_urlmatch.rb +111 -0
- data/lib/git/commands/config_option_syntax/list.rb +111 -0
- data/lib/git/commands/config_option_syntax/remove_section.rb +79 -0
- data/lib/git/commands/config_option_syntax/rename_section.rb +83 -0
- data/lib/git/commands/config_option_syntax/replace_all.rb +109 -0
- data/lib/git/commands/config_option_syntax/set.rb +119 -0
- data/lib/git/commands/config_option_syntax/unset.rb +92 -0
- data/lib/git/commands/config_option_syntax/unset_all.rb +94 -0
- data/lib/git/commands/config_option_syntax.rb +56 -0
- data/lib/git/commands/describe.rb +156 -0
- data/lib/git/commands/diff.rb +657 -0
- data/lib/git/commands/diff_files.rb +519 -0
- data/lib/git/commands/diff_index.rb +499 -0
- data/lib/git/commands/fetch.rb +354 -0
- data/lib/git/commands/fsck.rb +138 -0
- data/lib/git/commands/gc.rb +134 -0
- data/lib/git/commands/grep.rb +339 -0
- data/lib/git/commands/init.rb +101 -0
- data/lib/git/commands/log.rb +634 -0
- data/lib/git/commands/ls_files.rb +195 -0
- data/lib/git/commands/ls_remote.rb +161 -0
- data/lib/git/commands/ls_tree.rb +135 -0
- data/lib/git/commands/maintenance/register.rb +73 -0
- data/lib/git/commands/maintenance/run.rb +105 -0
- data/lib/git/commands/maintenance/start.rb +67 -0
- data/lib/git/commands/maintenance/stop.rb +56 -0
- data/lib/git/commands/maintenance/unregister.rb +80 -0
- data/lib/git/commands/maintenance.rb +29 -0
- data/lib/git/commands/merge/abort.rb +44 -0
- data/lib/git/commands/merge/continue.rb +44 -0
- data/lib/git/commands/merge/quit.rb +46 -0
- data/lib/git/commands/merge/start.rb +250 -0
- data/lib/git/commands/merge.rb +28 -0
- data/lib/git/commands/merge_base.rb +91 -0
- data/lib/git/commands/mv.rb +82 -0
- data/lib/git/commands/name_rev.rb +119 -0
- data/lib/git/commands/pull.rb +382 -0
- data/lib/git/commands/push.rb +251 -0
- data/lib/git/commands/read_tree.rb +154 -0
- data/lib/git/commands/remote/add.rb +96 -0
- data/lib/git/commands/remote/get_url.rb +68 -0
- data/lib/git/commands/remote/list.rb +56 -0
- data/lib/git/commands/remote/prune.rb +63 -0
- data/lib/git/commands/remote/remove.rb +52 -0
- data/lib/git/commands/remote/rename.rb +76 -0
- data/lib/git/commands/remote/set_branches.rb +70 -0
- data/lib/git/commands/remote/set_head.rb +89 -0
- data/lib/git/commands/remote/set_url.rb +78 -0
- data/lib/git/commands/remote/set_url_add.rb +70 -0
- data/lib/git/commands/remote/set_url_delete.rb +71 -0
- data/lib/git/commands/remote/show.rb +77 -0
- data/lib/git/commands/remote/update.rb +79 -0
- data/lib/git/commands/remote.rb +42 -0
- data/lib/git/commands/repack.rb +281 -0
- data/lib/git/commands/reset.rb +154 -0
- data/lib/git/commands/rev_parse.rb +304 -0
- data/lib/git/commands/revert/abort.rb +45 -0
- data/lib/git/commands/revert/continue.rb +62 -0
- data/lib/git/commands/revert/quit.rb +47 -0
- data/lib/git/commands/revert/skip.rb +44 -0
- data/lib/git/commands/revert/start.rb +158 -0
- data/lib/git/commands/revert.rb +29 -0
- data/lib/git/commands/rm.rb +113 -0
- data/lib/git/commands/show.rb +632 -0
- data/lib/git/commands/show_ref/exclude_existing.rb +119 -0
- data/lib/git/commands/show_ref/exists.rb +75 -0
- data/lib/git/commands/show_ref/list.rb +149 -0
- data/lib/git/commands/show_ref/verify.rb +122 -0
- data/lib/git/commands/show_ref.rb +42 -0
- data/lib/git/commands/stash/apply.rb +81 -0
- data/lib/git/commands/stash/branch.rb +67 -0
- data/lib/git/commands/stash/clear.rb +43 -0
- data/lib/git/commands/stash/create.rb +60 -0
- data/lib/git/commands/stash/drop.rb +73 -0
- data/lib/git/commands/stash/list.rb +43 -0
- data/lib/git/commands/stash/pop.rb +87 -0
- data/lib/git/commands/stash/push.rb +112 -0
- data/lib/git/commands/stash/show.rb +158 -0
- data/lib/git/commands/stash/store.rb +72 -0
- data/lib/git/commands/stash.rb +38 -0
- data/lib/git/commands/status.rb +174 -0
- data/lib/git/commands/symbolic_ref/delete.rb +72 -0
- data/lib/git/commands/symbolic_ref/read.rb +99 -0
- data/lib/git/commands/symbolic_ref/update.rb +79 -0
- data/lib/git/commands/symbolic_ref.rb +38 -0
- data/lib/git/commands/tag/create.rb +142 -0
- data/lib/git/commands/tag/delete.rb +57 -0
- data/lib/git/commands/tag/list.rb +146 -0
- data/lib/git/commands/tag/verify.rb +71 -0
- data/lib/git/commands/tag.rb +26 -0
- data/lib/git/commands/update_ref/batch.rb +145 -0
- data/lib/git/commands/update_ref/delete.rb +90 -0
- data/lib/git/commands/update_ref/update.rb +103 -0
- data/lib/git/commands/update_ref.rb +42 -0
- data/lib/git/commands/version.rb +60 -0
- data/lib/git/commands/worktree/add.rb +139 -0
- data/lib/git/commands/worktree/list.rb +64 -0
- data/lib/git/commands/worktree/lock.rb +58 -0
- data/lib/git/commands/worktree/management_base.rb +51 -0
- data/lib/git/commands/worktree/move.rb +66 -0
- data/lib/git/commands/worktree/prune.rb +67 -0
- data/lib/git/commands/worktree/remove.rb +63 -0
- data/lib/git/commands/worktree/repair.rb +71 -0
- data/lib/git/commands/worktree/unlock.rb +47 -0
- data/lib/git/commands/worktree.rb +43 -0
- data/lib/git/commands/write_tree.rb +68 -0
- data/lib/git/commands.rb +88 -0
- data/lib/git/config.rb +64 -1
- data/lib/git/config_entry_info.rb +106 -0
- data/lib/git/configuring.rb +795 -0
- data/lib/git/detached_head_info.rb +57 -0
- data/lib/git/diff.rb +295 -12
- data/lib/git/diff_file_numstat_info.rb +31 -0
- data/lib/git/diff_file_patch_info.rb +136 -0
- data/lib/git/diff_file_raw_info.rb +129 -0
- data/lib/git/diff_info.rb +162 -0
- data/lib/git/diff_path_status.rb +80 -19
- data/lib/git/diff_result.rb +34 -0
- data/lib/git/diff_stats.rb +66 -14
- data/lib/git/dirstat_info.rb +102 -0
- data/lib/git/encoding_utils.rb +57 -1
- data/lib/git/errors.rb +107 -26
- data/lib/git/escaped_path.rb +55 -3
- data/lib/git/execution_context/global.rb +31 -0
- data/lib/git/execution_context/repository.rb +151 -0
- data/lib/git/execution_context.rb +559 -0
- data/lib/git/factories.rb +1049 -0
- data/lib/git/file_ref.rb +77 -0
- data/lib/git/fsck_object.rb +17 -9
- data/lib/git/fsck_result.rb +27 -16
- data/lib/git/log.rb +172 -65
- data/lib/git/object.rb +323 -108
- data/lib/git/parsers/branch.rb +240 -0
- data/lib/git/parsers/cat_file.rb +111 -0
- data/lib/git/parsers/config_entry.rb +110 -0
- data/lib/git/parsers/diff.rb +792 -0
- data/lib/git/parsers/fsck.rb +144 -0
- data/lib/git/parsers/grep.rb +42 -0
- data/lib/git/parsers/ls_remote.rb +79 -0
- data/lib/git/parsers/ls_tree.rb +58 -0
- data/lib/git/parsers/remote.rb +162 -0
- data/lib/git/parsers/stash.rb +292 -0
- data/lib/git/parsers/status.rb +251 -0
- data/lib/git/parsers/tag.rb +341 -0
- data/lib/git/parsers/worktree.rb +185 -0
- data/lib/git/path_resolver.rb +274 -0
- data/lib/git/remote_info.rb +203 -0
- data/lib/git/repository/branching.rb +796 -0
- data/lib/git/repository/committing.rb +221 -0
- data/lib/git/repository/context_helpers.rb +454 -0
- data/lib/git/repository/diffing.rb +743 -0
- data/lib/git/repository/inspecting.rb +252 -0
- data/lib/git/repository/logging.rb +410 -0
- data/lib/git/repository/maintenance.rb +65 -0
- data/lib/git/repository/merging.rb +429 -0
- data/lib/git/repository/object_operations.rb +1334 -0
- data/lib/git/repository/remote_operations.rb +772 -0
- data/lib/git/repository/shared_private.rb +120 -0
- data/lib/git/repository/staging.rb +409 -0
- data/lib/git/repository/stashing.rb +619 -0
- data/lib/git/repository/status_operations.rb +196 -0
- data/lib/git/repository/worktree_operations.rb +252 -0
- data/lib/git/repository.rb +204 -1
- data/lib/git/stash_info.rb +102 -0
- data/lib/git/status_file_info.rb +258 -0
- data/lib/git/status_info.rb +189 -0
- data/lib/git/system_call_guard.rb +95 -0
- data/lib/git/tag_delete_failure.rb +34 -0
- data/lib/git/tag_delete_result.rb +66 -0
- data/lib/git/tag_info.rb +99 -0
- data/lib/git/url.rb +12 -5
- data/lib/git/version.rb +111 -2
- data/lib/git/version_constraint.rb +85 -0
- data/lib/git/worktree_info.rb +128 -0
- data/lib/git.rb +319 -332
- metadata +318 -74
- data/.commitlintrc.yml +0 -38
- data/.github/copilot-instructions.md +0 -2733
- data/.github/issue_template.md +0 -15
- data/.github/pull_request_template.md +0 -17
- data/.github/workflows/continuous_integration.yml +0 -120
- data/.github/workflows/enforce_conventional_commits.yml +0 -29
- data/.github/workflows/experimental_continuous_integration.yml +0 -59
- data/.github/workflows/release.yml +0 -53
- data/.gitignore +0 -15
- data/.husky/commit-msg +0 -1
- data/.release-please-manifest.json +0 -3
- data/.rubocop.yml +0 -55
- data/.rubocop_todo.yml +0 -12
- data/Gemfile +0 -5
- data/Rakefile +0 -18
- data/lib/git/args_builder.rb +0 -111
- data/lib/git/author.rb +0 -16
- data/lib/git/base.rb +0 -1140
- data/lib/git/branch.rb +0 -423
- data/lib/git/branches.rb +0 -68
- data/lib/git/command_line_result.rb +0 -92
- data/lib/git/index.rb +0 -6
- data/lib/git/lib.rb +0 -2333
- data/lib/git/path.rb +0 -38
- data/lib/git/remote.rb +0 -39
- data/lib/git/stash.rb +0 -26
- data/lib/git/stashes.rb +0 -56
- data/lib/git/status.rb +0 -159
- data/lib/git/working_directory.rb +0 -6
- data/lib/git/worktree.rb +0 -39
- data/lib/git/worktrees.rb +0 -47
- data/package.json +0 -10
- data/redesign/1_architecture_existing.md +0 -66
- data/redesign/2_architecture_redesign.md +0 -130
- data/redesign/3_architecture_implementation.md +0 -138
- data/redesign/index.md +0 -34
- data/release-please-config.json +0 -36
- data/tasks/gem_tasks.rake +0 -10
- data/tasks/rubocop.rake +0 -12
- data/tasks/test.rake +0 -13
- data/tasks/test_gem.rake +0 -12
- data/tasks/yard.rake +0 -23
|
@@ -0,0 +1,1334 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'fileutils'
|
|
4
|
+
require 'git/commands/archive'
|
|
5
|
+
require 'git/object'
|
|
6
|
+
require 'git/commands/cat_file/raw'
|
|
7
|
+
require 'git/commands/grep'
|
|
8
|
+
require 'git/commands/ls_tree'
|
|
9
|
+
require 'git/commands/name_rev'
|
|
10
|
+
require 'git/commands/rev_parse'
|
|
11
|
+
require 'git/commands/show_ref/list'
|
|
12
|
+
require 'git/commands/tag/create'
|
|
13
|
+
require 'git/commands/tag/delete'
|
|
14
|
+
require 'git/commands/tag/list'
|
|
15
|
+
require 'git/parsers/cat_file'
|
|
16
|
+
require 'git/parsers/grep'
|
|
17
|
+
require 'git/parsers/ls_tree'
|
|
18
|
+
require 'git/parsers/tag'
|
|
19
|
+
require 'git/repository/shared_private'
|
|
20
|
+
require 'git/system_call_guard'
|
|
21
|
+
require 'git/escaped_path'
|
|
22
|
+
require 'tempfile'
|
|
23
|
+
require 'zlib'
|
|
24
|
+
|
|
25
|
+
module Git
|
|
26
|
+
class Repository
|
|
27
|
+
# Facade methods for raw git object store queries
|
|
28
|
+
#
|
|
29
|
+
# Included by {Git::Repository}.
|
|
30
|
+
#
|
|
31
|
+
# @api private
|
|
32
|
+
#
|
|
33
|
+
module ObjectOperations # rubocop:disable Metrics/ModuleLength
|
|
34
|
+
# Returns the raw content of a git object, or streams it into a tempfile
|
|
35
|
+
#
|
|
36
|
+
# Without a block, the full content is buffered in memory and returned as a
|
|
37
|
+
# `String`. With a block, git output is streamed directly to disk without
|
|
38
|
+
# memory buffering — safe for large blobs.
|
|
39
|
+
#
|
|
40
|
+
# @overload cat_file_contents(object)
|
|
41
|
+
# Returns the object's raw content as a string
|
|
42
|
+
#
|
|
43
|
+
# @example Get the contents of a blob
|
|
44
|
+
# repo.cat_file_contents('HEAD:README.md') # => "This is a README file\n"
|
|
45
|
+
#
|
|
46
|
+
# @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
|
|
47
|
+
#
|
|
48
|
+
# @return [String] the raw content of the object
|
|
49
|
+
#
|
|
50
|
+
# @overload cat_file_contents(object, &block)
|
|
51
|
+
# Streams the object's raw content to a temporary file and yields it
|
|
52
|
+
#
|
|
53
|
+
# Git output is written directly to a file on disk without being buffered in
|
|
54
|
+
# memory first, then the file is rewound and yielded to the block. The return
|
|
55
|
+
# value is whatever the block returns.
|
|
56
|
+
#
|
|
57
|
+
# @example Read a large blob without buffering it in memory
|
|
58
|
+
# repo.cat_file_contents('HEAD:large_file.bin') { |f| process(f) }
|
|
59
|
+
#
|
|
60
|
+
# @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
|
|
61
|
+
#
|
|
62
|
+
# @yield [file] the temporary file containing the streamed content,
|
|
63
|
+
# positioned at the start
|
|
64
|
+
#
|
|
65
|
+
# @yieldparam file [File] readable `IO` object positioned at the beginning
|
|
66
|
+
# of the content
|
|
67
|
+
#
|
|
68
|
+
# @yieldreturn [Object] the value to return from this method
|
|
69
|
+
#
|
|
70
|
+
# @return [Object] the value returned by the block
|
|
71
|
+
#
|
|
72
|
+
# @raise [ArgumentError] if `object` starts with a hyphen
|
|
73
|
+
#
|
|
74
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
75
|
+
#
|
|
76
|
+
# @raise [Git::Error] if a block is given and the object content cannot be
|
|
77
|
+
# written to a temporary file
|
|
78
|
+
#
|
|
79
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
80
|
+
#
|
|
81
|
+
def cat_file_contents(object, &block)
|
|
82
|
+
raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
|
|
83
|
+
|
|
84
|
+
return Git::Commands::CatFile::Raw.new(@execution_context).call(object, p: true).stdout unless block_given?
|
|
85
|
+
|
|
86
|
+
# Stream git output directly to a tempfile to avoid buffering large
|
|
87
|
+
# object content in memory when a block is given.
|
|
88
|
+
Git::SystemCallGuard.call('Failed to write the object content to a temporary file') do |guard|
|
|
89
|
+
Tempfile.create do |file|
|
|
90
|
+
file.binmode
|
|
91
|
+
Git::Commands::CatFile::Raw.new(@execution_context).call(object, p: true, out: file)
|
|
92
|
+
file.rewind
|
|
93
|
+
guard.unguarded { block.call(file) }
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
# Alias for {#cat_file_contents}; kept as a legacy name and not scheduled
|
|
99
|
+
# for removal
|
|
100
|
+
#
|
|
101
|
+
# @see #cat_file_contents
|
|
102
|
+
alias cat_file cat_file_contents
|
|
103
|
+
|
|
104
|
+
# Returns the size of a git object in bytes
|
|
105
|
+
#
|
|
106
|
+
# @example Get the size of a commit object
|
|
107
|
+
# repo.cat_file_size('HEAD') #=> 265
|
|
108
|
+
#
|
|
109
|
+
# @example Get the size of a blob by treeish path
|
|
110
|
+
# repo.cat_file_size('HEAD:README.md') #=> 14
|
|
111
|
+
#
|
|
112
|
+
# @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
|
|
113
|
+
#
|
|
114
|
+
# @return [Integer] the object size in bytes
|
|
115
|
+
#
|
|
116
|
+
# @raise [ArgumentError] if `object` starts with a hyphen
|
|
117
|
+
#
|
|
118
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
119
|
+
#
|
|
120
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
121
|
+
#
|
|
122
|
+
def cat_file_size(object)
|
|
123
|
+
raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
|
|
124
|
+
|
|
125
|
+
Git::Commands::CatFile::Raw.new(@execution_context).call(object, s: true).stdout.chomp.to_i
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
# Returns the type of a git object
|
|
129
|
+
#
|
|
130
|
+
# @example Get the type of a commit reference
|
|
131
|
+
# repo.cat_file_type('HEAD') #=> "commit"
|
|
132
|
+
#
|
|
133
|
+
# @example Get the type of a blob via treeish path
|
|
134
|
+
# repo.cat_file_type('HEAD:README.md') #=> "blob"
|
|
135
|
+
#
|
|
136
|
+
# @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
|
|
137
|
+
#
|
|
138
|
+
# @return [String] the object type — one of `"blob"`, `"commit"`,
|
|
139
|
+
# `"tag"`, or `"tree"`
|
|
140
|
+
#
|
|
141
|
+
# @raise [ArgumentError] if `object` starts with a hyphen
|
|
142
|
+
#
|
|
143
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
144
|
+
#
|
|
145
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
146
|
+
#
|
|
147
|
+
def cat_file_type(object)
|
|
148
|
+
raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
|
|
149
|
+
|
|
150
|
+
Git::Commands::CatFile::Raw.new(@execution_context).call(object, t: true).stdout.chomp
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
# Returns parsed commit data for the given git object
|
|
154
|
+
#
|
|
155
|
+
# @example Get commit data for HEAD
|
|
156
|
+
# repo.cat_file_commit('HEAD')
|
|
157
|
+
# # => {
|
|
158
|
+
# # 'sha' => 'HEAD',
|
|
159
|
+
# # 'tree' => 'def5678...',
|
|
160
|
+
# # 'parent' => ['ghi9012...'],
|
|
161
|
+
# # 'author' => 'A U Thor <author@example.com> 1234567890 +0000',
|
|
162
|
+
# # 'committer' => 'A U Thor <author@example.com> 1234567890 +0000',
|
|
163
|
+
# # 'message' => "Initial commit\n"
|
|
164
|
+
# # }
|
|
165
|
+
#
|
|
166
|
+
# @param object [String] the object name (SHA, ref, `HEAD`, etc.)
|
|
167
|
+
#
|
|
168
|
+
# @return [Hash] commit data
|
|
169
|
+
#
|
|
170
|
+
# String-keyed hash with the following keys:
|
|
171
|
+
#
|
|
172
|
+
# * `tree` — the tree SHA
|
|
173
|
+
# * `parent` — Array of parent SHAs (empty for the root commit)
|
|
174
|
+
# * `author` — author identity string and timestamp
|
|
175
|
+
# * `committer` — committer identity string and timestamp
|
|
176
|
+
# * `message` — the commit message (includes trailing newline)
|
|
177
|
+
# * `gpgsig` — the cryptographic signature (signed commits only)
|
|
178
|
+
# * `sha` — the `object` argument as passed by the caller
|
|
179
|
+
#
|
|
180
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
181
|
+
#
|
|
182
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
183
|
+
#
|
|
184
|
+
def cat_file_commit(object)
|
|
185
|
+
result = Git::Commands::CatFile::Raw.new(@execution_context).call('commit', object)
|
|
186
|
+
Git::Parsers::CatFile.parse_commit(result.stdout.split("\n"), object)
|
|
187
|
+
end
|
|
188
|
+
|
|
189
|
+
# Returns parsed tag data for the given annotated tag object
|
|
190
|
+
#
|
|
191
|
+
# Does not work with lightweight tags. To list all annotated tags in a
|
|
192
|
+
# repository:
|
|
193
|
+
#
|
|
194
|
+
# ```sh
|
|
195
|
+
# git for-each-ref --format='%(refname:strip=2)' refs/tags | \
|
|
196
|
+
# while read tag; do
|
|
197
|
+
# git cat-file tag "$tag" >/dev/null 2>&1 && echo "$tag"
|
|
198
|
+
# done
|
|
199
|
+
# ```
|
|
200
|
+
#
|
|
201
|
+
# @example Get tag data for an annotated tag
|
|
202
|
+
# repo.cat_file_tag('v1.0')
|
|
203
|
+
# # => {
|
|
204
|
+
# # 'name' => 'v1.0',
|
|
205
|
+
# # 'object' => 'abc1234...',
|
|
206
|
+
# # 'type' => 'commit',
|
|
207
|
+
# # 'tag' => 'v1.0',
|
|
208
|
+
# # 'tagger' => 'A U Thor <author@example.com> 1234567890 +0000',
|
|
209
|
+
# # 'message' => "Release v1.0\n"
|
|
210
|
+
# # }
|
|
211
|
+
#
|
|
212
|
+
# @param object [String] the annotated tag name or SHA
|
|
213
|
+
#
|
|
214
|
+
# @return [Hash] tag data
|
|
215
|
+
#
|
|
216
|
+
# String-keyed hash with the following keys:
|
|
217
|
+
#
|
|
218
|
+
# * `name` — the `object` argument as passed by the caller
|
|
219
|
+
# * `object` — the SHA of the tagged object
|
|
220
|
+
# * `type` — the type of the tagged object (usually `"commit"`)
|
|
221
|
+
# * `tag` — the tag name
|
|
222
|
+
# * `tagger` — tagger identity string and timestamp
|
|
223
|
+
# * `message` — the tag message (includes trailing newline)
|
|
224
|
+
#
|
|
225
|
+
# @raise [ArgumentError] if `object` starts with a hyphen
|
|
226
|
+
#
|
|
227
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
228
|
+
#
|
|
229
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
230
|
+
#
|
|
231
|
+
def cat_file_tag(object)
|
|
232
|
+
raise ArgumentError, "Invalid object: '#{object}'" if object&.start_with?('-')
|
|
233
|
+
|
|
234
|
+
tdata = Git::Commands::CatFile::Raw.new(@execution_context).call('tag', object).stdout.split("\n")
|
|
235
|
+
Git::Parsers::CatFile.parse_tag(tdata, object)
|
|
236
|
+
end
|
|
237
|
+
|
|
238
|
+
# Resolve a revision specifier to its full object ID
|
|
239
|
+
#
|
|
240
|
+
# Passes the given revision specifier to `git rev-parse` and returns the
|
|
241
|
+
# full object ID.
|
|
242
|
+
#
|
|
243
|
+
# @example Resolve HEAD to its full object ID
|
|
244
|
+
# repo.rev_parse('HEAD') #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
|
|
245
|
+
#
|
|
246
|
+
# @example Resolve an abbreviated SHA
|
|
247
|
+
# repo.rev_parse('9b9b31e') #=> "9b9b31e704c0b85ffdd8d2af2ded85170a5af87d"
|
|
248
|
+
#
|
|
249
|
+
# @example Resolve a tree object via rev-parse syntax
|
|
250
|
+
# repo.rev_parse('HEAD^{tree}') #=> "94c827875e2cadb8bc8d4cdd900f19aa9e8634c7"
|
|
251
|
+
#
|
|
252
|
+
# @param objectish [String] the revision specifier to resolve (branch name,
|
|
253
|
+
# tag, abbreviated SHA, refspec, etc.)
|
|
254
|
+
#
|
|
255
|
+
# @return [String] the full object ID of the resolved object
|
|
256
|
+
#
|
|
257
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
258
|
+
#
|
|
259
|
+
# @see https://git-scm.com/docs/git-rev-parse git-rev-parse documentation
|
|
260
|
+
#
|
|
261
|
+
# @see https://git-scm.com/docs/git-rev-parse#_specifying_revisions Valid ways to specify revisions
|
|
262
|
+
#
|
|
263
|
+
def rev_parse(objectish)
|
|
264
|
+
Git::Commands::RevParse.new(@execution_context).call(objectish, '--', revs_only: true).stdout
|
|
265
|
+
end
|
|
266
|
+
|
|
267
|
+
# Returns the SHA of a named tag
|
|
268
|
+
#
|
|
269
|
+
# Returns an empty string when the tag does not exist.
|
|
270
|
+
#
|
|
271
|
+
# Reads the loose ref file under `refs/tags` directly when it exists and
|
|
272
|
+
# falls back to `git show-ref` otherwise, including when the file cannot
|
|
273
|
+
# be read.
|
|
274
|
+
#
|
|
275
|
+
# @example Get the SHA of an existing tag
|
|
276
|
+
# repo.tag_sha('v1.0')
|
|
277
|
+
# #=> "abc1234567890abcdef1234567890abcdef123456"
|
|
278
|
+
#
|
|
279
|
+
# @example Get the SHA of a non-existent tag
|
|
280
|
+
# repo.tag_sha('nonexistent') #=> ""
|
|
281
|
+
#
|
|
282
|
+
# @param tag_name [String] the tag name to look up
|
|
283
|
+
#
|
|
284
|
+
# @return [String] the SHA of the named tag, or an empty string if the
|
|
285
|
+
# tag does not exist
|
|
286
|
+
#
|
|
287
|
+
# @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
|
|
288
|
+
#
|
|
289
|
+
def tag_sha(tag_name)
|
|
290
|
+
tags_dir = File.expand_path(File.join(@execution_context.git_dir, 'refs', 'tags'))
|
|
291
|
+
head = File.expand_path(File.join(tags_dir, tag_name))
|
|
292
|
+
Private.loose_tag_sha(tags_dir, head) || Private.show_ref_tag_sha(@execution_context, tag_name)
|
|
293
|
+
end
|
|
294
|
+
|
|
295
|
+
# Returns all recursive entries for a given tree object
|
|
296
|
+
#
|
|
297
|
+
# Equivalent to running `git ls-tree -r <objectish>` and splitting the
|
|
298
|
+
# output on newlines. Each returned line describes a single entry in the
|
|
299
|
+
# tree in the format produced by `git ls-tree`: `<mode> <type> <object>\t<file>`.
|
|
300
|
+
#
|
|
301
|
+
# @example List all files in the tree rooted at HEAD
|
|
302
|
+
# repo.full_tree('HEAD^{tree}')
|
|
303
|
+
# # => [
|
|
304
|
+
# # "100644 blob e69de29bb2d1d6434b8b29ae775ad8c2e48c5391\tex_dir/ex.txt",
|
|
305
|
+
# # "100644 blob abc1234...\tlib/git.rb"
|
|
306
|
+
# # ]
|
|
307
|
+
#
|
|
308
|
+
# @param objectish [String] the tree SHA or tree-ish specifier to recurse
|
|
309
|
+
# into
|
|
310
|
+
#
|
|
311
|
+
# @return [Array<String>] one entry per path, in the format
|
|
312
|
+
# `<mode> <type> <object>\t<file>`
|
|
313
|
+
#
|
|
314
|
+
# Returns an empty array for an empty tree.
|
|
315
|
+
#
|
|
316
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
317
|
+
#
|
|
318
|
+
# @see https://git-scm.com/docs/git-ls-tree git-ls-tree documentation
|
|
319
|
+
#
|
|
320
|
+
def full_tree(objectish)
|
|
321
|
+
Git::Commands::LsTree.new(@execution_context).call(objectish, r: true).stdout.split("\n")
|
|
322
|
+
end
|
|
323
|
+
|
|
324
|
+
# Returns the number of entries in a tree
|
|
325
|
+
#
|
|
326
|
+
# Runs `git ls-tree -r <objectish>` and counts output lines.
|
|
327
|
+
# This matches `Git::Lib#tree_depth` behavior in the 4.x branch.
|
|
328
|
+
#
|
|
329
|
+
# @example Count entries in the tree rooted at HEAD
|
|
330
|
+
# repo.tree_depth('HEAD^{tree}') #=> 42
|
|
331
|
+
#
|
|
332
|
+
# @param objectish [String] the tree SHA or tree-ish specifier to recurse
|
|
333
|
+
# into
|
|
334
|
+
#
|
|
335
|
+
# @return [Integer] the number of entries in the recursive tree listing
|
|
336
|
+
#
|
|
337
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
338
|
+
#
|
|
339
|
+
# @see https://git-scm.com/docs/git-ls-tree git-ls-tree documentation
|
|
340
|
+
#
|
|
341
|
+
def tree_depth(objectish)
|
|
342
|
+
Git::Commands::LsTree.new(@execution_context).call(objectish, r: true).stdout.each_line.count
|
|
343
|
+
end
|
|
344
|
+
|
|
345
|
+
# Find the first symbolic name for a commit-ish
|
|
346
|
+
#
|
|
347
|
+
# @example Find the symbolic name for a commit
|
|
348
|
+
# repo.name_rev('abc123') #=> "main~5"
|
|
349
|
+
#
|
|
350
|
+
# @example Find the symbolic name for HEAD
|
|
351
|
+
# repo.name_rev('HEAD') #=> "main"
|
|
352
|
+
#
|
|
353
|
+
# @param commit_ish [String] the commit-ish to find the symbolic name of
|
|
354
|
+
#
|
|
355
|
+
# @return [String, nil] the first symbolic name, or nil if stdout contains
|
|
356
|
+
# fewer than two words
|
|
357
|
+
#
|
|
358
|
+
# @raise [ArgumentError] if commit_ish starts with a hyphen
|
|
359
|
+
#
|
|
360
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
361
|
+
#
|
|
362
|
+
# @see https://git-scm.com/docs/git-name-rev git-name-rev documentation
|
|
363
|
+
#
|
|
364
|
+
def name_rev(commit_ish)
|
|
365
|
+
raise ArgumentError, "Invalid commit_ish: '#{commit_ish}'" if commit_ish&.start_with?('-')
|
|
366
|
+
|
|
367
|
+
Git::Commands::NameRev.new(@execution_context).call(commit_ish).stdout.split[1]
|
|
368
|
+
end
|
|
369
|
+
|
|
370
|
+
# Option keys accepted by {#ls_tree}
|
|
371
|
+
LS_TREE_ALLOWED_OPTS = %i[recursive path].freeze
|
|
372
|
+
private_constant :LS_TREE_ALLOWED_OPTS
|
|
373
|
+
|
|
374
|
+
# List the objects in a git tree
|
|
375
|
+
#
|
|
376
|
+
# Runs `git ls-tree` against the given sha and returns a Hash of tree
|
|
377
|
+
# entries organised by object type.
|
|
378
|
+
#
|
|
379
|
+
# @example List the top-level tree
|
|
380
|
+
# repo.ls_tree('HEAD')
|
|
381
|
+
# # => { 'blob' => { 'README.md' => { mode: '100644', sha: 'abc...' } },
|
|
382
|
+
# # 'tree' => { 'lib' => { mode: '040000', sha: 'def...' } },
|
|
383
|
+
# # 'commit' => {} }
|
|
384
|
+
#
|
|
385
|
+
# @example List the tree recursively
|
|
386
|
+
# repo.ls_tree('HEAD', recursive: true)
|
|
387
|
+
# # => { 'blob' => { 'lib/git.rb' => { mode: '100644', sha: '...' } }, ... }
|
|
388
|
+
#
|
|
389
|
+
# @example Limit the listing to a path
|
|
390
|
+
# repo.ls_tree('HEAD', path: 'lib/')
|
|
391
|
+
#
|
|
392
|
+
# @param objectish [String] the tree-ish object to list
|
|
393
|
+
#
|
|
394
|
+
# @param opts [Hash] additional options
|
|
395
|
+
#
|
|
396
|
+
# @option opts [Boolean, nil] :recursive (nil) recurse into subtrees
|
|
397
|
+
#
|
|
398
|
+
# @option opts [String, Array<String>] :path (nil) path or array of paths
|
|
399
|
+
# to limit the listing to
|
|
400
|
+
#
|
|
401
|
+
# @return [Hash<String, Hash<String, Hash>>] a three-level Hash keyed by
|
|
402
|
+
# object type (`'blob'`, `'tree'`, `'commit'`), then by filename, then
|
|
403
|
+
# holding `:mode` and `:sha` values
|
|
404
|
+
#
|
|
405
|
+
# @raise [ArgumentError] when unsupported options are provided
|
|
406
|
+
#
|
|
407
|
+
# @raise [Git::FailedError] when git exits with a non-zero exit status
|
|
408
|
+
#
|
|
409
|
+
# @see https://git-scm.com/docs/git-ls-tree git-ls-tree documentation
|
|
410
|
+
#
|
|
411
|
+
def ls_tree(objectish, opts = {})
|
|
412
|
+
SharedPrivate.assert_valid_opts!(LS_TREE_ALLOWED_OPTS, **opts)
|
|
413
|
+
paths = Array(opts[:path]).compact
|
|
414
|
+
r_value = opts[:recursive]
|
|
415
|
+
safe_options = {}
|
|
416
|
+
safe_options[:r] = r_value unless r_value.nil?
|
|
417
|
+
result = Git::Commands::LsTree.new(@execution_context).call(objectish, *paths, **safe_options)
|
|
418
|
+
Git::Parsers::LsTree.parse(result.stdout)
|
|
419
|
+
end
|
|
420
|
+
|
|
421
|
+
# Option keys accepted by {#grep}
|
|
422
|
+
GREP_ALLOWED_OPTS = %i[ignore_case i invert_match v extended_regexp E perl_regexp P object].freeze
|
|
423
|
+
private_constant :GREP_ALLOWED_OPTS
|
|
424
|
+
|
|
425
|
+
# Search tracked file contents in a git tree for a pattern
|
|
426
|
+
#
|
|
427
|
+
# Runs `git grep` against the given tree-ish and returns every match as a
|
|
428
|
+
# filename-keyed hash of `[line_number, text]` pairs.
|
|
429
|
+
#
|
|
430
|
+
# @example Search HEAD for a pattern
|
|
431
|
+
# repo.grep('TODO')
|
|
432
|
+
# # => { "HEAD:src/foo.rb" => [[12, "# TODO: fix this"]], ... }
|
|
433
|
+
#
|
|
434
|
+
# @example Limit the search to a path
|
|
435
|
+
# repo.grep('TODO', 'src/')
|
|
436
|
+
#
|
|
437
|
+
# @example Search a specific commit
|
|
438
|
+
# repo.grep('TODO', nil, object: 'abc1234')
|
|
439
|
+
#
|
|
440
|
+
# @example Case-insensitive search
|
|
441
|
+
# repo.grep('todo', nil, ignore_case: true)
|
|
442
|
+
#
|
|
443
|
+
# @example Match a metacharacter against a non-ASCII character on Git for Windows
|
|
444
|
+
# repo.grep('^.PFEL', nil, perl_regexp: true)
|
|
445
|
+
#
|
|
446
|
+
# @param pattern [String] the pattern to search for
|
|
447
|
+
#
|
|
448
|
+
# @param path_limiter [String, Pathname, Array<String, Pathname>, nil]
|
|
449
|
+
# a path or array of paths to limit the search to, or `nil` for no limit
|
|
450
|
+
#
|
|
451
|
+
# @param opts [Hash] additional options for the grep command
|
|
452
|
+
#
|
|
453
|
+
# @option opts [String] :object ('HEAD') the tree-ish to search
|
|
454
|
+
#
|
|
455
|
+
# @option opts [Boolean, nil] :ignore_case (nil) ignore case
|
|
456
|
+
# distinctions in both the pattern and the file contents
|
|
457
|
+
#
|
|
458
|
+
# Alias: :i
|
|
459
|
+
#
|
|
460
|
+
# @option opts [Boolean, nil] :invert_match (nil) select non-matching
|
|
461
|
+
# lines
|
|
462
|
+
#
|
|
463
|
+
# Alias: :v
|
|
464
|
+
#
|
|
465
|
+
# @option opts [Boolean, nil] :extended_regexp (nil) use POSIX extended
|
|
466
|
+
# regular expressions for the pattern
|
|
467
|
+
#
|
|
468
|
+
# Alias: :E
|
|
469
|
+
#
|
|
470
|
+
# @option opts [Boolean, nil] :perl_regexp (nil) use Perl-compatible regular
|
|
471
|
+
# expressions (PCRE) for the pattern
|
|
472
|
+
#
|
|
473
|
+
# Requires a git built with PCRE support; git otherwise fails with
|
|
474
|
+
# "cannot use Perl-compatible regexes...".
|
|
475
|
+
#
|
|
476
|
+
# Alias: :P
|
|
477
|
+
#
|
|
478
|
+
# @return [Hash<String, Array<Array(Integer, String)>>] a hash mapping
|
|
479
|
+
# each `"treeish:filename"` key to an array of `[line_number, text]`
|
|
480
|
+
# pairs; returns an empty hash when no lines match
|
|
481
|
+
#
|
|
482
|
+
# @raise [ArgumentError] if unsupported options are provided
|
|
483
|
+
#
|
|
484
|
+
# @raise [Git::FailedError] if git exits with a non-zero status and
|
|
485
|
+
# stderr is non-empty (e.g. bad object reference)
|
|
486
|
+
#
|
|
487
|
+
# @note On Git for Windows, git's default regex engine matches *bytes* rather
|
|
488
|
+
# than characters, so a metacharacter such as `.` or a POSIX class such as
|
|
489
|
+
# `[[:alpha:]]` never matches a whole multi-byte character. The failure is
|
|
490
|
+
# silent: nothing raises, and the empty hash returned is indistinguishable
|
|
491
|
+
# from a pattern that genuinely does not occur in the tree. Pass
|
|
492
|
+
# `perl_regexp: true` to select PCRE, which does match characters. PCRE is a
|
|
493
|
+
# different dialect than git's default POSIX basic/extended regular
|
|
494
|
+
# expressions, so this is a deliberate choice by the caller rather than a
|
|
495
|
+
# transparent substitution, and it requires a git built with PCRE support.
|
|
496
|
+
#
|
|
497
|
+
# @see https://git-scm.com/docs/git-grep git-grep documentation
|
|
498
|
+
#
|
|
499
|
+
def grep(pattern, path_limiter = nil, opts = {})
|
|
500
|
+
SharedPrivate.assert_valid_opts!(GREP_ALLOWED_OPTS, **opts)
|
|
501
|
+
opts = opts.dup
|
|
502
|
+
object = opts.delete(:object) || 'HEAD'
|
|
503
|
+
opts[:pathspec] = Array(path_limiter).map(&:to_s) if path_limiter
|
|
504
|
+
result = Git::Commands::Grep.new(@execution_context).call(
|
|
505
|
+
object, pattern:, **opts, no_color: true, line_number: true, null: true
|
|
506
|
+
)
|
|
507
|
+
Private.parse_grep_result(result)
|
|
508
|
+
end
|
|
509
|
+
|
|
510
|
+
# Option keys accepted by {#archive}
|
|
511
|
+
ARCHIVE_ALLOWED_OPTS = %i[prefix remote path format add_gzip].freeze
|
|
512
|
+
private_constant :ARCHIVE_ALLOWED_OPTS
|
|
513
|
+
|
|
514
|
+
# Create an archive of the repository tree and write it to a file
|
|
515
|
+
#
|
|
516
|
+
# Writes the archive content to a file and returns the file path. The
|
|
517
|
+
# default format is `zip`. Pass `format: 'tar'` for an uncompressed tar
|
|
518
|
+
# archive, or `format: 'tgz'` for a gzip-compressed tar archive
|
|
519
|
+
# (equivalent to `format: 'tar'` with `add_gzip: true`).
|
|
520
|
+
#
|
|
521
|
+
# When no `file` path is given, a temporary file is created and its path
|
|
522
|
+
# is returned.
|
|
523
|
+
#
|
|
524
|
+
# **File replacement behavior when `file` is given:**
|
|
525
|
+
#
|
|
526
|
+
# The archive is first written to a staging file in the same directory as
|
|
527
|
+
# `file`. This means write permission is required on the parent directory
|
|
528
|
+
# of `file`, not just on `file` itself. Once the archive is fully written,
|
|
529
|
+
# the staging file atomically replaces `file` via rename.
|
|
530
|
+
#
|
|
531
|
+
# If `file` already exists, only its numeric permission bits are applied to
|
|
532
|
+
# the new archive; ownership, ACLs, and extended attributes are not
|
|
533
|
+
# transferred. If `file` does not exist, the archive receives the standard
|
|
534
|
+
# file creation mode (`0666 & ~umask`). On Windows, `File.chmod` has no
|
|
535
|
+
# effect, so the archive always receives the default creation mode
|
|
536
|
+
# regardless of whether `file` already exists.
|
|
537
|
+
#
|
|
538
|
+
# If `file` is a symlink that does not point to a directory, the symlink
|
|
539
|
+
# itself is replaced by the new archive file rather than writing through
|
|
540
|
+
# the link to its target. A symlink that points to a directory is treated
|
|
541
|
+
# as a directory and rejected with `ArgumentError`.
|
|
542
|
+
#
|
|
543
|
+
# @example Archive HEAD as a zip file
|
|
544
|
+
# repo.archive('HEAD', '/tmp/release.zip') #=> "/tmp/release.zip"
|
|
545
|
+
#
|
|
546
|
+
# @example Archive a tag as a tar file
|
|
547
|
+
# repo.archive('v1.0', '/tmp/release.tar', format: 'tar') #=> "/tmp/release.tar"
|
|
548
|
+
#
|
|
549
|
+
# @example Archive with a path prefix applied to every entry
|
|
550
|
+
# repo.archive('HEAD', '/tmp/out.tar', format: 'tar', prefix: 'myproject/')
|
|
551
|
+
# #=> "/tmp/out.tar"
|
|
552
|
+
#
|
|
553
|
+
# @example Archive a subdirectory only
|
|
554
|
+
# repo.archive('HEAD', '/tmp/src.tar', format: 'tar', path: 'src/')
|
|
555
|
+
# #=> "/tmp/src.tar"
|
|
556
|
+
#
|
|
557
|
+
# @param treeish [String] tree-ish to archive — commit SHA, tag, branch
|
|
558
|
+
# name, or tree SHA
|
|
559
|
+
#
|
|
560
|
+
# @param file [String, nil] (nil) destination file path; when `nil`, a
|
|
561
|
+
# unique temporary file is created and its path is returned
|
|
562
|
+
#
|
|
563
|
+
# @param opts [Hash] archive options
|
|
564
|
+
#
|
|
565
|
+
# @option opts [String] :format ('zip') archive format — `'tar'`, `'zip'`,
|
|
566
|
+
# or `'tgz'`; `'tgz'` is internally converted to `'tar'` with gzip
|
|
567
|
+
# post-processing
|
|
568
|
+
#
|
|
569
|
+
# @option opts [String] :prefix (nil) prefix prepended to every filename
|
|
570
|
+
# in the archive; typically ends with `/`
|
|
571
|
+
#
|
|
572
|
+
# @option opts [String] :path (nil) path within the tree to include in the
|
|
573
|
+
# archive; when given, only files under that path are archived
|
|
574
|
+
#
|
|
575
|
+
# @option opts [String] :remote (nil) retrieve the archive from a remote
|
|
576
|
+
# repository rather than the local one
|
|
577
|
+
#
|
|
578
|
+
# @option opts [Boolean, nil] :add_gzip (nil) apply gzip compression after
|
|
579
|
+
# writing the archive; set automatically when `format: 'tgz'` is given
|
|
580
|
+
#
|
|
581
|
+
# @return [String] path to the written archive file
|
|
582
|
+
#
|
|
583
|
+
# @raise [ArgumentError] if unsupported options are provided
|
|
584
|
+
#
|
|
585
|
+
# @raise [ArgumentError] if `file` is an existing directory
|
|
586
|
+
#
|
|
587
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
588
|
+
#
|
|
589
|
+
# @raise [Git::Error] if the archive file cannot be written or gzip
|
|
590
|
+
# compression fails
|
|
591
|
+
#
|
|
592
|
+
# @note A failure leaves nothing behind: the staging and temporary files
|
|
593
|
+
# are removed and an existing `file` is not replaced.
|
|
594
|
+
#
|
|
595
|
+
# @see https://git-scm.com/docs/git-archive git-archive documentation
|
|
596
|
+
#
|
|
597
|
+
def archive(treeish, file = nil, opts = {})
|
|
598
|
+
SharedPrivate.assert_valid_opts!(ARCHIVE_ALLOWED_OPTS, **opts)
|
|
599
|
+
raise ArgumentError, "#{file.inspect} is a directory" if file && File.directory?(file)
|
|
600
|
+
|
|
601
|
+
Git::SystemCallGuard.call('Failed to write the archive') do
|
|
602
|
+
Private.write_archive(@execution_context, treeish, file, opts)
|
|
603
|
+
end
|
|
604
|
+
end
|
|
605
|
+
|
|
606
|
+
# Returns a blob object for the given object reference
|
|
607
|
+
#
|
|
608
|
+
# The returned object is lazy: no git command is invoked until a property
|
|
609
|
+
# (e.g. {Git::Object::AbstractObject#sha}, {Git::Object::AbstractObject#contents})
|
|
610
|
+
# is accessed on the result.
|
|
611
|
+
#
|
|
612
|
+
# @example Get a blob from a treeish path
|
|
613
|
+
# repo.gblob('HEAD:README.md')
|
|
614
|
+
# #=> #<Git::Object::Blob ...>
|
|
615
|
+
#
|
|
616
|
+
# @param objectish [String] the object name (SHA, treeish path, ref, etc.)
|
|
617
|
+
#
|
|
618
|
+
# @return [Git::Object::Blob] the blob object
|
|
619
|
+
#
|
|
620
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
621
|
+
#
|
|
622
|
+
def gblob(objectish)
|
|
623
|
+
Git::Object.new(self, objectish, 'blob')
|
|
624
|
+
end
|
|
625
|
+
|
|
626
|
+
# Returns a commit object for the given object reference
|
|
627
|
+
#
|
|
628
|
+
# The returned object is lazy: no git command is invoked until a property
|
|
629
|
+
# (e.g. {Git::Object::AbstractObject#sha}, {Git::Object::Commit#message})
|
|
630
|
+
# is accessed on the result.
|
|
631
|
+
#
|
|
632
|
+
# @example Get a commit by symbolic ref
|
|
633
|
+
# repo.gcommit('HEAD')
|
|
634
|
+
# #=> #<Git::Object::Commit ...>
|
|
635
|
+
#
|
|
636
|
+
# @example Get a commit by abbreviated SHA
|
|
637
|
+
# repo.gcommit('abc1234')
|
|
638
|
+
# #=> #<Git::Object::Commit ...>
|
|
639
|
+
#
|
|
640
|
+
# @param objectish [String] the object name (SHA, branch, tag, refspec, etc.)
|
|
641
|
+
#
|
|
642
|
+
# @return [Git::Object::Commit] the commit object
|
|
643
|
+
#
|
|
644
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
645
|
+
#
|
|
646
|
+
def gcommit(objectish)
|
|
647
|
+
Git::Object.new(self, objectish, 'commit')
|
|
648
|
+
end
|
|
649
|
+
|
|
650
|
+
# Returns a tree object for the given object reference
|
|
651
|
+
#
|
|
652
|
+
# The returned object is lazy: no git command is invoked until a property
|
|
653
|
+
# (e.g. {Git::Object::AbstractObject#sha}, {Git::Object::Tree#children})
|
|
654
|
+
# is accessed on the result.
|
|
655
|
+
#
|
|
656
|
+
# @example Get the root tree for the current HEAD
|
|
657
|
+
# repo.gtree('HEAD^{tree}')
|
|
658
|
+
# #=> #<Git::Object::Tree ...>
|
|
659
|
+
#
|
|
660
|
+
# @param objectish [String] the object name (SHA, treeish specifier, etc.)
|
|
661
|
+
#
|
|
662
|
+
# @return [Git::Object::Tree] the tree object
|
|
663
|
+
#
|
|
664
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
665
|
+
#
|
|
666
|
+
def gtree(objectish)
|
|
667
|
+
Git::Object.new(self, objectish, 'tree')
|
|
668
|
+
end
|
|
669
|
+
|
|
670
|
+
# Returns the appropriate git object for the given object reference
|
|
671
|
+
#
|
|
672
|
+
# Runs `git cat-file -t` to determine the object type, then constructs
|
|
673
|
+
# and returns the corresponding `Git::Object::*` subclass instance.
|
|
674
|
+
#
|
|
675
|
+
# @example Get a commit object from HEAD
|
|
676
|
+
# repo.object('HEAD')
|
|
677
|
+
# #=> #<Git::Object::Commit ...>
|
|
678
|
+
#
|
|
679
|
+
# @example Get a blob from a treeish path
|
|
680
|
+
# repo.object('HEAD:README.md')
|
|
681
|
+
# #=> #<Git::Object::Blob ...>
|
|
682
|
+
#
|
|
683
|
+
# @param objectish [String] the object name (SHA, ref, treeish path, etc.)
|
|
684
|
+
#
|
|
685
|
+
# @return [Git::Object::Blob, Git::Object::Commit, Git::Object::Tree] the
|
|
686
|
+
# git object for the given reference
|
|
687
|
+
#
|
|
688
|
+
# @raise [ArgumentError] if `objectish` starts with a hyphen
|
|
689
|
+
#
|
|
690
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
691
|
+
#
|
|
692
|
+
# @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
|
|
693
|
+
#
|
|
694
|
+
def object(objectish)
|
|
695
|
+
Git::Object.new(self, objectish)
|
|
696
|
+
end
|
|
697
|
+
|
|
698
|
+
# Returns the tags in the repository as structured objects
|
|
699
|
+
#
|
|
700
|
+
# @example List all tags
|
|
701
|
+
# repo.tag_list
|
|
702
|
+
# # => [#<data Git::TagInfo name="v1.0.0", oid=nil, target_oid="abc123...", ...>,
|
|
703
|
+
# # #<data Git::TagInfo name="v2.0.0", oid="def456...", target_oid="789abc...", ...>]
|
|
704
|
+
#
|
|
705
|
+
# @example Look up a single tag by name
|
|
706
|
+
# repo.tag_list('v1.0.0').first
|
|
707
|
+
# # => #<data Git::TagInfo name="v1.0.0", ...>
|
|
708
|
+
#
|
|
709
|
+
# @example Look up a tag that does not exist
|
|
710
|
+
# repo.tag_list('nonexistent').first #=> nil
|
|
711
|
+
#
|
|
712
|
+
# @example Filter using glob patterns
|
|
713
|
+
# repo.tag_list('v1.*', 'v2.*')
|
|
714
|
+
#
|
|
715
|
+
# @example List only annotated tags
|
|
716
|
+
# repo.tag_list.select(&:annotated?)
|
|
717
|
+
#
|
|
718
|
+
# @param patterns [Array<String>] optional shell wildcard patterns passed
|
|
719
|
+
# directly to `git tag --list`; when empty (the default) all tags are
|
|
720
|
+
# returned
|
|
721
|
+
#
|
|
722
|
+
# @return [Array<Git::TagInfo>] parsed tag information for every tag
|
|
723
|
+
# matching the patterns, in the order `git tag --list` reports them
|
|
724
|
+
#
|
|
725
|
+
# Returns an empty array when the repository has no tags or no tag
|
|
726
|
+
# matches the given patterns.
|
|
727
|
+
#
|
|
728
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
729
|
+
#
|
|
730
|
+
# @see https://git-scm.com/docs/git-tag git-tag
|
|
731
|
+
#
|
|
732
|
+
def tag_list(*patterns)
|
|
733
|
+
result = Git::Commands::Tag::List.new(@execution_context).call(
|
|
734
|
+
*patterns, format: Git::Parsers::Tag::FORMAT_STRING
|
|
735
|
+
)
|
|
736
|
+
Git::Parsers::Tag.parse_list(result.stdout)
|
|
737
|
+
end
|
|
738
|
+
|
|
739
|
+
# Option keys accepted by {#tag_create}
|
|
740
|
+
TAG_CREATE_ALLOWED_OPTS = %i[
|
|
741
|
+
annotate a sign s no_sign local_user u force f message m file F
|
|
742
|
+
edit e no_edit trailer cleanup create_reflog
|
|
743
|
+
].freeze
|
|
744
|
+
private_constant :TAG_CREATE_ALLOWED_OPTS
|
|
745
|
+
|
|
746
|
+
# Create a new tag and return its metadata
|
|
747
|
+
#
|
|
748
|
+
# @overload tag_create(name, options = {})
|
|
749
|
+
#
|
|
750
|
+
# @example Create a lightweight tag on HEAD
|
|
751
|
+
# repo.tag_create('v1.0.0')
|
|
752
|
+
# # => #<data Git::TagInfo name="v1.0.0", oid=nil, target_oid="abc123...", ...>
|
|
753
|
+
#
|
|
754
|
+
# @example Create an annotated tag on HEAD
|
|
755
|
+
# repo.tag_create('v1.0.0', annotate: true, message: 'Release 1.0.0')
|
|
756
|
+
# # => #<data Git::TagInfo name="v1.0.0", oid="def456...", message="Release 1.0.0", ...>
|
|
757
|
+
#
|
|
758
|
+
# @example Replace an existing tag on HEAD
|
|
759
|
+
# repo.tag_create('v1.0.0', force: true)
|
|
760
|
+
#
|
|
761
|
+
# @param name [String] the name of the tag to create
|
|
762
|
+
#
|
|
763
|
+
# @param options [Hash] options for creating the tag
|
|
764
|
+
#
|
|
765
|
+
# @option options [Boolean, nil] :annotate (nil) make an unsigned,
|
|
766
|
+
# annotated tag object; requires `:message` or `:file` (alias: `:a`)
|
|
767
|
+
#
|
|
768
|
+
# @option options [Boolean, nil] :a (nil) alias for `:annotate`
|
|
769
|
+
#
|
|
770
|
+
# @option options [Boolean, nil] :sign (nil) make a GPG-signed tag;
|
|
771
|
+
# requires `:message` or `:file` (alias: `:s`)
|
|
772
|
+
#
|
|
773
|
+
# @option options [Boolean, nil] :s (nil) alias for `:sign`
|
|
774
|
+
#
|
|
775
|
+
# @option options [Boolean, nil] :no_sign (nil) override `tag.gpgSign`
|
|
776
|
+
# config to disable signing
|
|
777
|
+
#
|
|
778
|
+
# @option options [String] :local_user (nil) make a signed tag using the
|
|
779
|
+
# given key (alias: `:u`)
|
|
780
|
+
#
|
|
781
|
+
# @option options [String] :u (nil) alias for `:local_user`
|
|
782
|
+
#
|
|
783
|
+
# @option options [Boolean, nil] :force (nil) replace an existing tag with
|
|
784
|
+
# the given name instead of failing (alias: `:f`)
|
|
785
|
+
#
|
|
786
|
+
# @option options [Boolean, nil] :f (nil) alias for `:force`
|
|
787
|
+
#
|
|
788
|
+
# @option options [String] :message (nil) use the given message as the tag
|
|
789
|
+
# message (alias: `:m`)
|
|
790
|
+
#
|
|
791
|
+
# @option options [String] :m (nil) alias for `:message`
|
|
792
|
+
#
|
|
793
|
+
# @option options [String] :file (nil) take the tag message from the given
|
|
794
|
+
# file; use `-` to read from standard input (alias: `:F`)
|
|
795
|
+
#
|
|
796
|
+
# @option options [String] :F (nil) alias for `:file`
|
|
797
|
+
#
|
|
798
|
+
# @option options [Boolean, nil] :edit (nil) open an editor to further edit
|
|
799
|
+
# the tag message (alias: `:e`)
|
|
800
|
+
#
|
|
801
|
+
# @option options [Boolean, nil] :e (nil) alias for `:edit`
|
|
802
|
+
#
|
|
803
|
+
# @option options [Boolean, nil] :no_edit (nil) suppress the editor
|
|
804
|
+
#
|
|
805
|
+
# @option options [Hash, Array<Array>] :trailer (nil) add trailers to the
|
|
806
|
+
# tag message
|
|
807
|
+
#
|
|
808
|
+
# @option options [String] :cleanup (nil) set how the tag message is
|
|
809
|
+
# cleaned up; one of `verbatim`, `whitespace`, or `strip`
|
|
810
|
+
#
|
|
811
|
+
# @option options [Boolean, nil] :create_reflog (nil) create a reflog for
|
|
812
|
+
# the tag
|
|
813
|
+
#
|
|
814
|
+
# @return [Git::TagInfo] the newly created tag
|
|
815
|
+
#
|
|
816
|
+
# @overload tag_create(name, target, options = {})
|
|
817
|
+
#
|
|
818
|
+
# @example Create a lightweight tag on a specific commit
|
|
819
|
+
# repo.tag_create('v1.0.0', 'abc123')
|
|
820
|
+
#
|
|
821
|
+
# @example Create an annotated tag on a specific commit
|
|
822
|
+
# repo.tag_create('v1.0.0', 'abc123', annotate: true, message: 'Release 1.0.0')
|
|
823
|
+
#
|
|
824
|
+
# @param name [String] the name of the tag to create
|
|
825
|
+
#
|
|
826
|
+
# @param target [String] the object to tag (commit SHA, branch name, etc.)
|
|
827
|
+
#
|
|
828
|
+
# @param options [Hash] options for creating the tag (same keys as the
|
|
829
|
+
# first overload)
|
|
830
|
+
#
|
|
831
|
+
# @return [Git::TagInfo] the newly created tag
|
|
832
|
+
#
|
|
833
|
+
# @raise [ArgumentError] if unsupported options are provided, including the
|
|
834
|
+
# `:d` and `:delete` keys; use {#tag_delete} to delete a tag
|
|
835
|
+
#
|
|
836
|
+
# @raise [ArgumentError] if an annotated or signed tag is requested without
|
|
837
|
+
# a message
|
|
838
|
+
#
|
|
839
|
+
# @raise [ArgumentError] if more than one positional argument follows the
|
|
840
|
+
# name (before any options hash)
|
|
841
|
+
#
|
|
842
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
843
|
+
#
|
|
844
|
+
# @raise [Git::UnexpectedResultError] if the tag listing cannot be parsed
|
|
845
|
+
# or does not contain the new tag (for example, it was deleted by another
|
|
846
|
+
# process before the lookup)
|
|
847
|
+
#
|
|
848
|
+
# @see https://git-scm.com/docs/git-tag git-tag
|
|
849
|
+
#
|
|
850
|
+
def tag_create(name, *args)
|
|
851
|
+
target, options = Private.tag_target_and_options(args)
|
|
852
|
+
SharedPrivate.assert_valid_opts!(TAG_CREATE_ALLOWED_OPTS, **options)
|
|
853
|
+
Private.create_tag(@execution_context, name, target, options)
|
|
854
|
+
tag_list(name).first ||
|
|
855
|
+
raise(Git::UnexpectedResultError, "tag was created but not found in the tag list: #{name}")
|
|
856
|
+
end
|
|
857
|
+
|
|
858
|
+
# Delete a tag
|
|
859
|
+
#
|
|
860
|
+
# @example Delete a tag
|
|
861
|
+
# repo.tag_delete('v1.0.0')
|
|
862
|
+
#
|
|
863
|
+
# @param name [String] the name of the tag to delete
|
|
864
|
+
#
|
|
865
|
+
# @return [String] git's stdout from the delete
|
|
866
|
+
#
|
|
867
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
868
|
+
#
|
|
869
|
+
def tag_delete(name)
|
|
870
|
+
result = Git::Commands::Tag::Delete.new(@execution_context).call(name)
|
|
871
|
+
raise Git::FailedError, result if result.status.exitstatus.positive?
|
|
872
|
+
|
|
873
|
+
result.stdout
|
|
874
|
+
end
|
|
875
|
+
|
|
876
|
+
# Private helpers
|
|
877
|
+
#
|
|
878
|
+
# @api private
|
|
879
|
+
#
|
|
880
|
+
module Private # rubocop:disable Metrics/ModuleLength
|
|
881
|
+
module_function
|
|
882
|
+
|
|
883
|
+
# Splits the variadic `*args` of {ObjectOperations#tag_create} into the
|
|
884
|
+
# target and the options hash
|
|
885
|
+
#
|
|
886
|
+
# `tag_create` accepts `(name, opts = {})` and `(name, target, opts = {})`,
|
|
887
|
+
# so a trailing `Hash` is the options and anything before it is the
|
|
888
|
+
# target.
|
|
889
|
+
#
|
|
890
|
+
# @param args [Array] the arguments after the tag name
|
|
891
|
+
#
|
|
892
|
+
# @return [Array((String, nil), Hash)] the two-element tuple
|
|
893
|
+
# `[target, options]`; `target` is `nil` when only options were given
|
|
894
|
+
#
|
|
895
|
+
# @raise [ArgumentError] if more than one positional argument precedes
|
|
896
|
+
# the options hash
|
|
897
|
+
#
|
|
898
|
+
# @api private
|
|
899
|
+
#
|
|
900
|
+
def tag_target_and_options(args)
|
|
901
|
+
args = args.dup
|
|
902
|
+
options = args.last.is_a?(Hash) ? args.pop : {}
|
|
903
|
+
if args.size > 1
|
|
904
|
+
raise ArgumentError,
|
|
905
|
+
"Expected at most one target before the options, got #{args.size}: #{args.inspect}"
|
|
906
|
+
end
|
|
907
|
+
|
|
908
|
+
[args.first, options]
|
|
909
|
+
end
|
|
910
|
+
|
|
911
|
+
# Validates the tag-creation options and runs `git tag`
|
|
912
|
+
#
|
|
913
|
+
# @param execution_context [Git::ExecutionContext::Repository] the
|
|
914
|
+
# execution context for git commands
|
|
915
|
+
#
|
|
916
|
+
# @param name [String] the name of the tag to create
|
|
917
|
+
#
|
|
918
|
+
# @param target [String, nil] the object to tag, or `nil` for HEAD
|
|
919
|
+
#
|
|
920
|
+
# @param options [Hash] the tag-creation options, already checked
|
|
921
|
+
# against the allowed keys (see {ObjectOperations#tag_create} for the
|
|
922
|
+
# full list)
|
|
923
|
+
#
|
|
924
|
+
# @option options [Boolean, nil] :annotate (nil) make an annotated tag;
|
|
925
|
+
# requires a message (alias: `:a`)
|
|
926
|
+
#
|
|
927
|
+
# @option options [Boolean, nil] :sign (nil) make a signed tag; requires
|
|
928
|
+
# a message (alias: `:s`)
|
|
929
|
+
#
|
|
930
|
+
# @option options [String] :local_user (nil) sign with the given key;
|
|
931
|
+
# requires a message (alias: `:u`)
|
|
932
|
+
#
|
|
933
|
+
# @option options [String] :message (nil) the tag message (alias: `:m`)
|
|
934
|
+
#
|
|
935
|
+
# @option options [String] :file (nil) a file to read the tag message
|
|
936
|
+
# from (alias: `:F`)
|
|
937
|
+
#
|
|
938
|
+
# @option options [Boolean, nil] :force (nil) replace an existing tag
|
|
939
|
+
# (alias: `:f`)
|
|
940
|
+
#
|
|
941
|
+
# @return [void]
|
|
942
|
+
#
|
|
943
|
+
# @raise [ArgumentError] when an annotated or signed tag is requested
|
|
944
|
+
# without a message
|
|
945
|
+
#
|
|
946
|
+
# @raise [Git::FailedError] if git exits with a non-zero exit status
|
|
947
|
+
#
|
|
948
|
+
# @api private
|
|
949
|
+
#
|
|
950
|
+
def create_tag(execution_context, name, target, options)
|
|
951
|
+
validate_tag_options!(options)
|
|
952
|
+
Git::Commands::Tag::Create.new(execution_context).call(name, target, **options)
|
|
953
|
+
end
|
|
954
|
+
|
|
955
|
+
# Validate that a message is present when an annotated or signed tag is
|
|
956
|
+
# requested
|
|
957
|
+
#
|
|
958
|
+
# @param opts [Hash] the tag-creation options
|
|
959
|
+
#
|
|
960
|
+
# @option opts [Boolean, nil] :annotate request an annotated tag
|
|
961
|
+
#
|
|
962
|
+
# @option opts [Boolean, nil] :a alias for `:annotate`
|
|
963
|
+
#
|
|
964
|
+
# @option opts [Boolean, nil] :sign request a signed tag
|
|
965
|
+
#
|
|
966
|
+
# @option opts [Boolean, nil] :s alias for `:sign`
|
|
967
|
+
#
|
|
968
|
+
# @option opts [String] :local_user key id used when signing
|
|
969
|
+
#
|
|
970
|
+
# @option opts [String] :u alias for `:local_user`
|
|
971
|
+
#
|
|
972
|
+
# @option opts [String] :message tag message text
|
|
973
|
+
#
|
|
974
|
+
# @option opts [String] :m alias for `:message`
|
|
975
|
+
#
|
|
976
|
+
# @option opts [String] :file path to a tag message file
|
|
977
|
+
#
|
|
978
|
+
# @option opts [String] :F alias for `:file`
|
|
979
|
+
#
|
|
980
|
+
# @return [void]
|
|
981
|
+
#
|
|
982
|
+
# @raise [ArgumentError] when an annotated or signed tag is requested
|
|
983
|
+
# without a `:message`/`:m`/`:file`/`:F` value
|
|
984
|
+
#
|
|
985
|
+
def validate_tag_options!(opts)
|
|
986
|
+
needs_message = %i[a annotate s sign u local_user].any? { |k| opts[k] }
|
|
987
|
+
has_message = opts[:m] || opts[:message] || opts[:F] || opts[:file]
|
|
988
|
+
|
|
989
|
+
return unless needs_message && !has_message
|
|
990
|
+
|
|
991
|
+
raise ArgumentError, 'Cannot create an annotated or signed tag without a message.'
|
|
992
|
+
end
|
|
993
|
+
|
|
994
|
+
# Read the SHA from a loose tag ref file without forking git
|
|
995
|
+
#
|
|
996
|
+
# Returns `nil` when the ref is not a loose file under `tags_dir` or when
|
|
997
|
+
# the file cannot be read, so the caller falls back to `git show-ref`.
|
|
998
|
+
#
|
|
999
|
+
# @param tags_dir [String] absolute path of the `refs/tags` directory
|
|
1000
|
+
#
|
|
1001
|
+
# @param head [String] absolute path of the candidate loose ref file
|
|
1002
|
+
#
|
|
1003
|
+
# @return [String, nil] the SHA in the file, or `nil` to fall back to git
|
|
1004
|
+
#
|
|
1005
|
+
# @api private
|
|
1006
|
+
#
|
|
1007
|
+
def loose_tag_sha(tags_dir, head)
|
|
1008
|
+
return nil unless head.start_with?("#{tags_dir}#{File::SEPARATOR}") && File.file?(head)
|
|
1009
|
+
|
|
1010
|
+
File.read(head).chomp
|
|
1011
|
+
rescue SystemCallError
|
|
1012
|
+
nil
|
|
1013
|
+
end
|
|
1014
|
+
|
|
1015
|
+
# Returns the direct SHA for a tag reference
|
|
1016
|
+
#
|
|
1017
|
+
# Returns the hash from `refs/tags/<name>` only. Returns an empty string
|
|
1018
|
+
# when the ref does not exist.
|
|
1019
|
+
#
|
|
1020
|
+
# @param execution_context [Git::ExecutionContext] for running
|
|
1021
|
+
# `git show-ref`
|
|
1022
|
+
#
|
|
1023
|
+
# @param tag_name [String] tag name without the `refs/tags/` prefix
|
|
1024
|
+
#
|
|
1025
|
+
# @return [String] direct ref SHA or an empty string when missing
|
|
1026
|
+
#
|
|
1027
|
+
# @api private
|
|
1028
|
+
#
|
|
1029
|
+
def show_ref_tag_sha(execution_context, tag_name)
|
|
1030
|
+
ref = "refs/tags/#{tag_name}"
|
|
1031
|
+
result = Git::Commands::ShowRef::List.new(execution_context).call(ref)
|
|
1032
|
+
return '' if result.status.exitstatus == 1
|
|
1033
|
+
|
|
1034
|
+
line = result.stdout.lines.find { |l| l.split[1] == ref }
|
|
1035
|
+
line ? line.split[0] : ''
|
|
1036
|
+
end
|
|
1037
|
+
|
|
1038
|
+
# Parses the result of a git grep command
|
|
1039
|
+
#
|
|
1040
|
+
# @param result [Git::CommandLine::Result] the result of a git grep command
|
|
1041
|
+
#
|
|
1042
|
+
# @return [Hash<String, Array<Array(Integer, String)>>] hash mapping "treeish:filename"
|
|
1043
|
+
# keys to arrays of [line_number, text] pairs
|
|
1044
|
+
#
|
|
1045
|
+
def parse_grep_result(result)
|
|
1046
|
+
exitstatus = result.status.exitstatus
|
|
1047
|
+
return {} if exitstatus == 1 && result.stderr.empty?
|
|
1048
|
+
raise Git::FailedError, result if exitstatus == 1
|
|
1049
|
+
|
|
1050
|
+
Git::Parsers::Grep.parse(result.stdout)
|
|
1051
|
+
end
|
|
1052
|
+
|
|
1053
|
+
# Resolve the staging directory for a git archive temp file
|
|
1054
|
+
#
|
|
1055
|
+
# Always returns `Dir.tmpdir` when `file` is nil, or the parent
|
|
1056
|
+
# directory of `file` otherwise. Staging the temp file in the same
|
|
1057
|
+
# directory as the destination keeps both paths on the same filesystem
|
|
1058
|
+
# so that {#atomic_replace} can use an atomic rename that
|
|
1059
|
+
# requires no extra disk space.
|
|
1060
|
+
#
|
|
1061
|
+
# @param file [String, nil] the explicit destination path, or nil
|
|
1062
|
+
#
|
|
1063
|
+
# @return [String] directory path to pass to `Tempfile.create`
|
|
1064
|
+
#
|
|
1065
|
+
# @api private
|
|
1066
|
+
#
|
|
1067
|
+
def staging_dir_for(file)
|
|
1068
|
+
return Dir.tmpdir unless file
|
|
1069
|
+
|
|
1070
|
+
File.dirname(File.expand_path(file))
|
|
1071
|
+
end
|
|
1072
|
+
|
|
1073
|
+
# Write a git archive, staging it in a temporary file first
|
|
1074
|
+
#
|
|
1075
|
+
# @param execution_context [Git::ExecutionContext] the execution context
|
|
1076
|
+
#
|
|
1077
|
+
# @param treeish [String] tree-ish to archive
|
|
1078
|
+
#
|
|
1079
|
+
# @param file [String, nil] destination path, or `nil` to keep the
|
|
1080
|
+
# temporary file
|
|
1081
|
+
#
|
|
1082
|
+
# @param opts [Hash] caller-supplied options (read-only)
|
|
1083
|
+
#
|
|
1084
|
+
# @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
|
|
1085
|
+
# or `'tgz'`)
|
|
1086
|
+
#
|
|
1087
|
+
# @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
|
|
1088
|
+
# to the generated archive
|
|
1089
|
+
#
|
|
1090
|
+
# @option opts [String] :prefix (nil) prefix for entries in the archive
|
|
1091
|
+
#
|
|
1092
|
+
# @option opts [String] :path (nil) path within `treeish` to archive
|
|
1093
|
+
#
|
|
1094
|
+
# @option opts [String] :remote (nil) remote repository from which to
|
|
1095
|
+
# retrieve the archive
|
|
1096
|
+
#
|
|
1097
|
+
# @return [String] path to the written archive file
|
|
1098
|
+
#
|
|
1099
|
+
# @api private
|
|
1100
|
+
#
|
|
1101
|
+
def write_archive(execution_context, treeish, file, opts)
|
|
1102
|
+
tmp = write_archive_tmp(execution_context, treeish, opts, dest_dir: staging_dir_for(file))
|
|
1103
|
+
return tmp unless file
|
|
1104
|
+
|
|
1105
|
+
atomic_replace(tmp, file)
|
|
1106
|
+
file
|
|
1107
|
+
rescue StandardError
|
|
1108
|
+
FileUtils.rm_f(tmp) if tmp
|
|
1109
|
+
raise
|
|
1110
|
+
end
|
|
1111
|
+
|
|
1112
|
+
# Write a git archive to a fresh temporary file and return its path
|
|
1113
|
+
#
|
|
1114
|
+
# Always writes to a new temporary file so that on error the caller's
|
|
1115
|
+
# destination file is never truncated. Format and gzip post-processing
|
|
1116
|
+
# are determined from `opts` via {#parse_archive_format_options}.
|
|
1117
|
+
#
|
|
1118
|
+
# @param execution_context [Git::ExecutionContext] for the git command
|
|
1119
|
+
#
|
|
1120
|
+
# @param treeish [String] tree-ish passed to `git archive`
|
|
1121
|
+
#
|
|
1122
|
+
# @param dest_dir [String] directory for the staging temp file; use
|
|
1123
|
+
# {#staging_dir_for} to select the optimal directory for the destination
|
|
1124
|
+
#
|
|
1125
|
+
# @param opts [Hash] caller-supplied options (read-only)
|
|
1126
|
+
#
|
|
1127
|
+
# @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
|
|
1128
|
+
# or `'tgz'`)
|
|
1129
|
+
#
|
|
1130
|
+
# @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
|
|
1131
|
+
# to the generated archive
|
|
1132
|
+
#
|
|
1133
|
+
# @option opts [String] :prefix (nil) prefix for entries in the archive
|
|
1134
|
+
#
|
|
1135
|
+
# @option opts [String] :path (nil) path within `treeish` to archive
|
|
1136
|
+
#
|
|
1137
|
+
# @option opts [String] :remote (nil) remote repository from which to
|
|
1138
|
+
# retrieve the archive
|
|
1139
|
+
#
|
|
1140
|
+
# @return [String] path to the populated temporary file
|
|
1141
|
+
#
|
|
1142
|
+
# @api private
|
|
1143
|
+
#
|
|
1144
|
+
def write_archive_tmp(execution_context, treeish, opts, dest_dir: Dir.tmpdir)
|
|
1145
|
+
format, gzip = parse_archive_format_options(opts)
|
|
1146
|
+
tmp_file = create_archive_tempfile(execution_context, treeish, opts, format, dest_dir)
|
|
1147
|
+
apply_gzip(tmp_file.path) if gzip
|
|
1148
|
+
tmp_file.path
|
|
1149
|
+
rescue StandardError
|
|
1150
|
+
tmp_file.close unless tmp_file.nil? || tmp_file.closed?
|
|
1151
|
+
FileUtils.rm_f(tmp_file.path) if tmp_file
|
|
1152
|
+
raise
|
|
1153
|
+
end
|
|
1154
|
+
|
|
1155
|
+
# Create a staging file, write the archive into it, close it, and return it
|
|
1156
|
+
#
|
|
1157
|
+
# Uses `Tempfile.create` (not `Tempfile.new`) so that no GC finalizer is
|
|
1158
|
+
# registered on the returned object — the file path remains valid after this
|
|
1159
|
+
# method returns and after the caller stores only the path string.
|
|
1160
|
+
#
|
|
1161
|
+
# @param execution_context [Git::ExecutionContext] for the git command
|
|
1162
|
+
#
|
|
1163
|
+
# @param treeish [String] tree-ish passed to `git archive`
|
|
1164
|
+
#
|
|
1165
|
+
# @param format [String] archive format string (e.g. `'zip'` or `'tar'`)
|
|
1166
|
+
#
|
|
1167
|
+
# @param dest_dir [String] directory in which to create the temp file
|
|
1168
|
+
#
|
|
1169
|
+
# @param opts [Hash] caller-supplied options (read-only; used for :prefix,
|
|
1170
|
+
# :remote, and :path)
|
|
1171
|
+
#
|
|
1172
|
+
# @option opts [String] :prefix (nil) prefix for entries in the archive
|
|
1173
|
+
#
|
|
1174
|
+
# @option opts [String] :path (nil) path within `treeish` to archive
|
|
1175
|
+
#
|
|
1176
|
+
# @option opts [String] :remote (nil) remote repository from which to
|
|
1177
|
+
# retrieve the archive
|
|
1178
|
+
#
|
|
1179
|
+
# @return [File] the closed file containing the archive
|
|
1180
|
+
#
|
|
1181
|
+
# @api private
|
|
1182
|
+
#
|
|
1183
|
+
def create_archive_tempfile(execution_context, treeish, opts, format, dest_dir)
|
|
1184
|
+
tmp_file = Tempfile.create('archive', dest_dir).tap(&:binmode)
|
|
1185
|
+
run_archive_command(execution_context, treeish, opts, format, tmp_file)
|
|
1186
|
+
tmp_file.close
|
|
1187
|
+
tmp_file
|
|
1188
|
+
rescue StandardError
|
|
1189
|
+
tmp_file&.close
|
|
1190
|
+
FileUtils.rm_f(tmp_file.path) if tmp_file
|
|
1191
|
+
raise
|
|
1192
|
+
end
|
|
1193
|
+
|
|
1194
|
+
# Invoke `git archive` and stream output into `tmp_file`
|
|
1195
|
+
#
|
|
1196
|
+
# @param execution_context [Git::ExecutionContext] for the git command
|
|
1197
|
+
#
|
|
1198
|
+
# @param treeish [String] tree-ish passed to `git archive`
|
|
1199
|
+
#
|
|
1200
|
+
# @param format [String] archive format to pass to `git archive --format`
|
|
1201
|
+
#
|
|
1202
|
+
# @param tmp_file [File] open, binary-mode IO to write archive data to
|
|
1203
|
+
#
|
|
1204
|
+
# @param opts [Hash] caller-supplied options (read-only; used for :prefix,
|
|
1205
|
+
# :remote, and :path)
|
|
1206
|
+
#
|
|
1207
|
+
# @option opts [String] :prefix (nil) prefix for entries in the archive
|
|
1208
|
+
#
|
|
1209
|
+
# @option opts [String] :path (nil) path within `treeish` to archive
|
|
1210
|
+
#
|
|
1211
|
+
# @option opts [String] :remote (nil) remote repository from which to
|
|
1212
|
+
# retrieve the archive
|
|
1213
|
+
#
|
|
1214
|
+
# @return [Git::CommandLine::Result] the result of the git command
|
|
1215
|
+
#
|
|
1216
|
+
# @api private
|
|
1217
|
+
#
|
|
1218
|
+
def run_archive_command(execution_context, treeish, opts, format, tmp_file)
|
|
1219
|
+
command_opts = opts.slice(:prefix, :remote).merge(format: format)
|
|
1220
|
+
path_args = opts[:path] ? [opts[:path]] : []
|
|
1221
|
+
Git::Commands::Archive.new(execution_context).call(treeish, *path_args, **command_opts, out: tmp_file)
|
|
1222
|
+
end
|
|
1223
|
+
|
|
1224
|
+
# Atomically rename the staging file `src` to `dest`, replacing any
|
|
1225
|
+
# existing file at `dest`. Both paths must be on the same filesystem
|
|
1226
|
+
# (guaranteed when `src` is created by {#staging_dir_for}).
|
|
1227
|
+
#
|
|
1228
|
+
# Before the rename, the staging file's permissions are set to the
|
|
1229
|
+
# existing file's numeric mode (if `dest` already existed) or to
|
|
1230
|
+
# `0666 & ~umask` (standard creation mode) for new files. The chmod
|
|
1231
|
+
# is applied to `src` before the rename so that, if chmod fails, `src`
|
|
1232
|
+
# is still present and can be cleaned up by the rescue. Only the
|
|
1233
|
+
# numeric permission bits are carried over; ownership, ACLs, and
|
|
1234
|
+
# extended attributes from an existing `dest` are not preserved.
|
|
1235
|
+
#
|
|
1236
|
+
# If `dest` is a symlink, the symlink itself is replaced by the renamed
|
|
1237
|
+
# staging file rather than writing through the link to its target.
|
|
1238
|
+
#
|
|
1239
|
+
# @param src [String] staging file path to rename; removed on success
|
|
1240
|
+
#
|
|
1241
|
+
# @param dest [String] destination file path
|
|
1242
|
+
#
|
|
1243
|
+
# @return [void]
|
|
1244
|
+
#
|
|
1245
|
+
# @api private
|
|
1246
|
+
#
|
|
1247
|
+
def atomic_replace(src, dest)
|
|
1248
|
+
mode = File.exist?(dest) ? (File.stat(dest).mode & 0o777) : (0o666 & ~File.umask)
|
|
1249
|
+
File.chmod(mode, src)
|
|
1250
|
+
File.rename(src, dest)
|
|
1251
|
+
rescue StandardError
|
|
1252
|
+
FileUtils.rm_f(src)
|
|
1253
|
+
raise
|
|
1254
|
+
end
|
|
1255
|
+
|
|
1256
|
+
# Determine the archive format and whether to apply gzip post-processing
|
|
1257
|
+
#
|
|
1258
|
+
# The `tgz` pseudo-format is not understood by `git archive` directly;
|
|
1259
|
+
# it is converted to `tar` and the gzip flag is set so that {#archive}
|
|
1260
|
+
# applies gzip compression after the archive is written.
|
|
1261
|
+
#
|
|
1262
|
+
# @param opts [Hash] caller-supplied options hash (read-only)
|
|
1263
|
+
#
|
|
1264
|
+
# @option opts [String] :format ('zip') archive format (`'tar'`, `'zip'`,
|
|
1265
|
+
# or `'tgz'`)
|
|
1266
|
+
#
|
|
1267
|
+
# @option opts [Boolean, nil] :add_gzip (nil) apply gzip post-processing
|
|
1268
|
+
# after archive generation
|
|
1269
|
+
#
|
|
1270
|
+
# @return [Array(String, Boolean)] a two-element array `[format, gzip]`
|
|
1271
|
+
#
|
|
1272
|
+
# `format` is the string to pass to `git archive --format`; `gzip` is
|
|
1273
|
+
# `true` when the caller should apply gzip post-processing after writing
|
|
1274
|
+
# the archive.
|
|
1275
|
+
#
|
|
1276
|
+
# @api private
|
|
1277
|
+
#
|
|
1278
|
+
def parse_archive_format_options(opts)
|
|
1279
|
+
format = opts[:format] || 'zip'
|
|
1280
|
+
gzip = opts[:add_gzip] == true || format == 'tgz'
|
|
1281
|
+
[format == 'tgz' ? 'tar' : format, gzip]
|
|
1282
|
+
end
|
|
1283
|
+
|
|
1284
|
+
# Apply gzip compression to the given file in place
|
|
1285
|
+
#
|
|
1286
|
+
# Streams from the source file through a {Zlib::GzipWriter} into a sibling
|
|
1287
|
+
# temporary file, then replaces the original. Peak memory is proportional
|
|
1288
|
+
# to the stream buffer rather than the full archive size.
|
|
1289
|
+
#
|
|
1290
|
+
# @param file [String] path to the file to compress in place
|
|
1291
|
+
#
|
|
1292
|
+
# @return [void]
|
|
1293
|
+
#
|
|
1294
|
+
# @raise [Git::Error] if zlib fails during compression, with the
|
|
1295
|
+
# `Zlib::Error` as `cause`
|
|
1296
|
+
#
|
|
1297
|
+
# @api private
|
|
1298
|
+
#
|
|
1299
|
+
def apply_gzip(file)
|
|
1300
|
+
gz_tmp = Tempfile.create('archive_gz', File.dirname(file)).tap(&:close).path
|
|
1301
|
+
gzip_file(file, gz_tmp)
|
|
1302
|
+
FileUtils.rm_f(file)
|
|
1303
|
+
File.rename(gz_tmp, file)
|
|
1304
|
+
rescue StandardError
|
|
1305
|
+
FileUtils.rm_f(gz_tmp) if gz_tmp
|
|
1306
|
+
raise
|
|
1307
|
+
end
|
|
1308
|
+
|
|
1309
|
+
# Stream `src` through a {Zlib::GzipWriter} into `dest`
|
|
1310
|
+
#
|
|
1311
|
+
# A `Zlib::Error` is not a `SystemCallError`, so {Git::SystemCallGuard}
|
|
1312
|
+
# does not convert it; this method does, per ADR-0008.
|
|
1313
|
+
#
|
|
1314
|
+
# @param src [String] path to the file to compress
|
|
1315
|
+
#
|
|
1316
|
+
# @param dest [String] path to write the gzip stream to
|
|
1317
|
+
#
|
|
1318
|
+
# @return [void]
|
|
1319
|
+
#
|
|
1320
|
+
# @raise [Git::Error] if zlib fails during compression, with the
|
|
1321
|
+
# `Zlib::Error` as `cause`
|
|
1322
|
+
#
|
|
1323
|
+
# @api private
|
|
1324
|
+
#
|
|
1325
|
+
def gzip_file(src, dest)
|
|
1326
|
+
Zlib::GzipWriter.open(dest) { |gz| File.open(src, 'rb') { |f| IO.copy_stream(f, gz) } }
|
|
1327
|
+
rescue Zlib::Error => e
|
|
1328
|
+
raise Git::Error, "Failed to gzip the archive: #{e.message}"
|
|
1329
|
+
end
|
|
1330
|
+
end
|
|
1331
|
+
private_constant :Private
|
|
1332
|
+
end
|
|
1333
|
+
end
|
|
1334
|
+
end
|