Class: Tap

Inherits:
Object
  • Object
show all
Extended by:
Cachable, Enumerable
Defined in:
Library/Homebrew/tap.rb

Overview

A Tap is used to extend the formulae provided by Homebrew core. Usually, it's synced with a remote Git repository. And it's likely a GitHub repository with the name of user/homebrew-repo. In such cases, user/repo will be used as the #name of this Tap, where #user represents the GitHub username and #repo represents the repository name without the leading homebrew-.

Direct Known Subclasses

CoreTap

Constant Summary collapse

TAP_DIRECTORY = 
(HOMEBREW_LIBRARY/"Taps").freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Cachable

cache

Instance Attribute Details

#full_name ⇒ Object (readonly)

The full name of this Tap, including the homebrew- prefix. It combines #user and 'homebrew-'-prefixed #repo with a slash. e.g. user/homebrew-repo


68
69
70
 
# File 'Library/Homebrew/tap.rb', line 68

def full_name
  @full_name
end

#name ⇒ Object (readonly)

The name of this Tap. It combines #user and #repo with a slash. #name is always in lowercase. e.g. user/repo


63
64
65
 
# File 'Library/Homebrew/tap.rb', line 63

def name
  @name
end

#path ⇒ Object (readonly)

The local path to this Tap. e.g. /usr/local/Library/Taps/user/homebrew-repo


72
73
74
 
# File 'Library/Homebrew/tap.rb', line 72

def path
  @path
end

#repo ⇒ Object (readonly)

The repository name of this Tap without the leading homebrew-.


58
59
60
 
# File 'Library/Homebrew/tap.rb', line 58

def repo
  @repo
end

#user ⇒ Object (readonly)

The user name of this Tap. Usually, it's the GitHub username of this Tap's remote repository.


55
56
57
 
# File 'Library/Homebrew/tap.rb', line 55

def user
  @user
end

Class Method Details

.cmd_directories ⇒ Object

An array of all tap cmd directory Pathnames.


571
572
573
 
# File 'Library/Homebrew/tap.rb', line 571

def self.cmd_directories
  Pathname.glob TAP_DIRECTORY/"*/*/cmd"
end

.default_cask_tap ⇒ Object 


47
48
49
 
# File 'Library/Homebrew/tap.rb', line 47

def self.default_cask_tap
  @default_cask_tap ||= fetch("Homebrew", "cask")
end

.each(&block) ⇒ Object 


553
554
555
556
557
558
559
560
561
562
563
 
# File 'Library/Homebrew/tap.rb', line 553

def self.each(&block)
  return unless TAP_DIRECTORY.directory?

  return to_enum unless block_given?

  TAP_DIRECTORY.subdirs.each do |user|
    user.subdirs.each do |repo|
      block.call fetch(user.basename.to_s, repo.basename.to_s)
    end
  end
end

.fetch(*args) ⇒ Object 


19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'Library/Homebrew/tap.rb', line 19

def self.fetch(*args)
  case args.length
  when 1
    user, repo = args.first.split("/", 2)
  when 2
    user = args.first
    repo = args.second
  end

  raise "Invalid tap name '#{args.join("/")}'" if [user, repo].any? { |part| part.nil? || part.include?("/") }

  # We special case homebrew and linuxbrew so that users don't have to shift in a terminal.
  user = user.capitalize if ["homebrew", "linuxbrew"].include? user
  repo = repo.sub(HOMEBREW_OFFICIAL_REPO_PREFIXES_REGEX, "")

  return CoreTap.instance if ["Homebrew", "Linuxbrew"].include?(user) && ["core", "homebrew"].include?(repo)

  cache_key = "#{user}/#{repo}".downcase
  cache.fetch(cache_key) { |key| cache[key] = Tap.new(user, repo) }
end

.from_path(path) ⇒ Object 


40
41
42
43
44
45
 
# File 'Library/Homebrew/tap.rb', line 40

def self.from_path(path)
  match = File.expand_path(path).match(HOMEBREW_TAP_PATH_REGEX)
  return if match.blank? || match[:user].blank? || match[:repo].blank?

  fetch(match[:user], match[:repo])
end

.names ⇒ Object

An array of all installed Tap names.


566
567
568
 
# File 'Library/Homebrew/tap.rb', line 566

def self.names
  map(&:name).sort
end

Instance Method Details

#==(other) ⇒ Object 


548
549
550
551
 
# File 'Library/Homebrew/tap.rb', line 548

def ==(other)
  other = Tap.fetch(other) if other.is_a?(String)
  self.class == other.class && name == other.name
end

#cask_dir ⇒ Object

Path to the directory of all Cask files for this Tap.


359
360
361
 
# File 'Library/Homebrew/tap.rb', line 359

def cask_dir
  @cask_dir ||= path/"Casks"
end

#cask_files ⇒ Object

An array of all Cask files of this Tap.


391
392
393
394
395
396
397
 
# File 'Library/Homebrew/tap.rb', line 391

def cask_files
  @cask_files ||= if cask_dir.directory?
    cask_dir.children.select(&method(:ruby_file?))
  else
    []
  end
end

#cask_tokens ⇒ Object

An array of all Cask tokens of this Tap.


429
430
431
 
# File 'Library/Homebrew/tap.rb', line 429

def cask_tokens
  @cask_tokens ||= cask_files.map(&method(:formula_file_to_name))
end

#clear_cache ⇒ Object

Clear internal cache.


87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'Library/Homebrew/tap.rb', line 87

def clear_cache
  @remote = nil
  @repo_var = nil
  @formula_dir = nil
  @cask_dir = nil
  @command_dir = nil
  @formula_files = nil
  @alias_dir = nil
  @alias_files = nil
  @aliases = nil
  @alias_table = nil
  @alias_reverse_table = nil
  @command_files = nil
  @formula_renames = nil
  @tap_migrations = nil
  @config = nil
  remove_instance_variable(:@private) if instance_variable_defined?(:@private)
end

#command_dir ⇒ Object 


476
477
478
 
# File 'Library/Homebrew/tap.rb', line 476

def command_dir
  @command_dir ||= path/"cmd"
end

#command_files ⇒ Object

An array of all commands files of this Tap.


481
482
483
484
485
486
487
 
# File 'Library/Homebrew/tap.rb', line 481

def command_files
  @command_files ||= if command_dir.directory?
    Commands.find_commands(command_dir)
  else
    []
  end
end

#config ⇒ Object

TapConfig of this Tap.


200
201
202
203
204
205
206
 
# File 'Library/Homebrew/tap.rb', line 200

def config
  @config ||= begin
    raise TapUnavailableError, name unless installed?

    TapConfig.new(self)
  end
end

#contents ⇒ Object 


363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'Library/Homebrew/tap.rb', line 363

def contents
  contents = []

  if (command_count = command_files.count).positive?
    contents << "#{command_count} #{"command".pluralize(command_count)}"
  end

  if (cask_count = cask_files.count).positive?
    contents << "#{cask_count} #{"cask".pluralize(cask_count)}"
  end

  if (formula_count = formula_files.count).positive?
    contents << "#{formula_count} #{"formula".pluralize(formula_count)}"
  end

  contents
end

#custom_remote? ⇒ Boolean

True if the #remote of Tap is customized.

Returns:

  • (Boolean) 

343
344
345
346
347
 
# File 'Library/Homebrew/tap.rb', line 343

def custom_remote?
  return true unless remote

  remote.casecmp(default_remote).nonzero?
end

#default_remote ⇒ Object

The default remote path to this Tap.


115
116
117
 
# File 'Library/Homebrew/tap.rb', line 115

def default_remote
  "https://github.com/#{full_name}"
end

#formula_dir ⇒ Object

Path to the directory of all Formula files for this Tap.


350
351
352
 
# File 'Library/Homebrew/tap.rb', line 350

def formula_dir
  @formula_dir ||= potential_formula_dirs.find(&:directory?) || path/"Formula"
end

#formula_files ⇒ Object

An array of all Formula files of this Tap.


382
383
384
385
386
387
388
 
# File 'Library/Homebrew/tap.rb', line 382

def formula_files
  @formula_files ||= if formula_dir.directory?
    formula_dir.children.select(&method(:ruby_file?))
  else
    []
  end
end

#formula_names ⇒ Object

An array of all Formula names of this Tap.


424
425
426
 
# File 'Library/Homebrew/tap.rb', line 424

def formula_names
  @formula_names ||= formula_files.map(&method(:formula_file_to_name))
end

#formula_renames ⇒ Object

Hash with tap formula renames.


527
528
529
530
531
532
533
534
535
 
# File 'Library/Homebrew/tap.rb', line 527

def formula_renames
  require "json"

  @formula_renames ||= if (rename_file = path/"formula_renames.json").file?
    JSON.parse(rename_file.read)
  else
    {}
  end
end

#git? ⇒ Boolean

True if this Tap is a Git repository.

Returns:

  • (Boolean) 

127
128
129
 
# File 'Library/Homebrew/tap.rb', line 127

def git?
  path.git?
end

#git_branch ⇒ Object

git branch for this Tap.

Raises:


132
133
134
135
136
 
# File 'Library/Homebrew/tap.rb', line 132

def git_branch
  raise TapUnavailableError, name unless installed?

  path.git_branch
end

#git_head ⇒ Object

git HEAD for this Tap.

Raises:


139
140
141
142
143
 
# File 'Library/Homebrew/tap.rb', line 139

def git_head
  raise TapUnavailableError, name unless installed?

  path.git_head
end

#git_last_commit ⇒ Object

Time since last git commit for this Tap.

Raises:


153
154
155
156
157
 
# File 'Library/Homebrew/tap.rb', line 153

def git_last_commit
  raise TapUnavailableError, name unless installed?

  path.git_last_commit
end

#git_last_commit_date ⇒ Object

Last git commit date for this Tap.

Raises:


160
161
162
163
164
 
# File 'Library/Homebrew/tap.rb', line 160

def git_last_commit_date
  raise TapUnavailableError, name unless installed?

  path.git_last_commit_date
end

#git_short_head ⇒ Object

git HEAD in short format for this Tap.

Raises:


146
147
148
149
150
 
# File 'Library/Homebrew/tap.rb', line 146

def git_short_head
  raise TapUnavailableError, name unless installed?

  path.git_short_head
end

#install(full_clone: true, quiet: false, clone_target: nil, force_auto_update: nil) ⇒ Object

Install this Tap.

Parameters:

  • clone_target (String) (defaults to: nil) —

    If passed, it will be used as the clone remote.

  • force_auto_update (Boolean, nil) (defaults to: nil) —

    If present, whether to override the logic that skips non-GitHub repositories during auto-updates.

  • full_clone (Boolean) (defaults to: true) —

    If set as true, full clone will be used. If unset/nil, means "no change".

  • quiet (Boolean) (defaults to: false) —

    If set, suppress all output.


230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'Library/Homebrew/tap.rb', line 230

def install(full_clone: true, quiet: false, clone_target: nil, force_auto_update: nil)
  require "descriptions"
  require "readall"

  if official? && DEPRECATED_OFFICIAL_TAPS.include?(repo)
    odie "#{name} was deprecated. This tap is now empty and all its contents were either deleted or migrated."
  elsif user == "caskroom" || name == "phinze/cask"
    new_repo = repo == "cask" ? "cask" : "cask-#{repo}"
    odie "#{name} was moved. Tap homebrew/#{new_repo} instead."
  end

  requested_remote = clone_target || default_remote

  if installed?
    raise TapRemoteMismatchError.new(name, @remote, requested_remote) if clone_target && requested_remote != remote
    raise TapAlreadyTappedError, name if force_auto_update.nil? && !shallow?
  end

  # ensure git is installed
  Utils::Git.ensure_installed!

  if installed?
    unless force_auto_update.nil?
      config["forceautoupdate"] = force_auto_update
      return if !full_clone || !shallow?
    end

    $stderr.ohai "Unshallowing #{name}" unless quiet
    args = %w[fetch --unshallow]
    args << "-q" if quiet
    path.cd { safe_system "git", *args }
    return
  end

  clear_cache

  $stderr.ohai "Tapping #{name}" unless quiet
  args =  %W[clone #{requested_remote} #{path}]
  args << "--depth=1" unless full_clone
  args << "-q" if quiet

  begin
    safe_system "git", *args
    if !Readall.valid_tap?(self, aliases: true) && !Homebrew::EnvConfig.developer?
      raise "Cannot tap #{name}: invalid syntax in tap!"
    end
  rescue Interrupt, RuntimeError
    ignore_interrupts do
      # wait for git to possibly cleanup the top directory when interrupt happens.
      sleep 0.1
      FileUtils.rm_rf path
      path.parent.rmdir_if_possible
    end
    raise
  end

  config["forceautoupdate"] = force_auto_update unless force_auto_update.nil?

  Commands.rebuild_commands_completion_list
  link_completions_and_manpages

  formatted_contents = contents.presence&.to_sentence&.dup&.prepend(" ")
  $stderr.puts "Tapped#{formatted_contents} (#{path.abv})." unless quiet
  CacheStoreDatabase.use(:descriptions) do |db|
    DescriptionCacheStore.new(db)
                         .update_from_formula_names!(formula_names)
  end

  return if clone_target
  return unless private?
  return if quiet

  $stderr.puts <<~EOS
    It looks like you tapped a private repository. To avoid entering your
    credentials each time you update, you can use git HTTP credential
    caching or issue the following command:
      cd #{path}
      git remote set-url origin [email protected]:#{full_name}.git
  EOS
end

#installed? ⇒ Boolean

True if this Tap has been installed.

Returns:

  • (Boolean) 

209
210
211
 
# File 'Library/Homebrew/tap.rb', line 209

def installed?
  path.directory?
end

#issues_url ⇒ Object

The issues URL of this Tap. e.g. https://github.com/user/homebrew-repo/issues


168
169
170
171
172
 
# File 'Library/Homebrew/tap.rb', line 168

def issues_url
  return unless official? || !custom_remote?

  "#{default_remote}/issues"
end

#link_completions_and_manpages ⇒ Object 


311
312
313
314
315
 
# File 'Library/Homebrew/tap.rb', line 311

def link_completions_and_manpages
  command = "brew tap --repair"
  Utils::Link.link_manpages(path, command)
  Utils::Link.link_completions(path, command)
end

#official? ⇒ Boolean

True if this Tap is an official Homebrew tap.

Returns:

  • (Boolean) 

188
189
190
 
# File 'Library/Homebrew/tap.rb', line 188

def official?
  user == "Homebrew"
end

#pinned? ⇒ Boolean

True if this Tap has been pinned.

Returns:

  • (Boolean) 

496
497
498
499
500
 
# File 'Library/Homebrew/tap.rb', line 496

def pinned?
  return @pinned if instance_variable_defined?(:@pinned)

  @pinned = pinned_symlink_path.directory?
end

#potential_formula_dirs ⇒ Object 


354
355
356
 
# File 'Library/Homebrew/tap.rb', line 354

def potential_formula_dirs
  @potential_formula_dirs ||= [path/"Formula", path/"HomebrewFormula", path].freeze
end

#private? ⇒ Boolean

True if the remote of this Tap is a private repository.

Returns:

  • (Boolean) 

193
194
195
196
197
 
# File 'Library/Homebrew/tap.rb', line 193

def private?
  return @private if instance_variable_defined?(:@private)

  @private = read_or_set_private_config
end

#remote ⇒ Object

The remote path to this Tap. e.g. https://github.com/user/homebrew-repo

Raises:


108
109
110
111
112
 
# File 'Library/Homebrew/tap.rb', line 108

def remote
  raise TapUnavailableError, name unless installed?

  @remote ||= path.git_origin
end

#repo_var ⇒ Object 


119
120
121
122
123
124
 
# File 'Library/Homebrew/tap.rb', line 119

def repo_var
  @repo_var ||= path.to_s
                    .delete_prefix(TAP_DIRECTORY.to_s)
                    .tr("^A-Za-z0-9", "_")
                    .upcase
end

#shallow? ⇒ Boolean

True if this Tap is not a full clone.

Returns:

  • (Boolean) 

214
215
216
 
# File 'Library/Homebrew/tap.rb', line 214

def shallow?
  (path/".git/shallow").exist?
end

#tap_migrations ⇒ Object

Hash with tap migrations.


538
539
540
541
542
543
544
545
546
 
# File 'Library/Homebrew/tap.rb', line 538

def tap_migrations
  require "json"

  @tap_migrations ||= if (migration_file = path/"tap_migrations.json").file?
    JSON.parse(migration_file.read)
  else
    {}
  end
end

#to_hash ⇒ Object 


502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
 
# File 'Library/Homebrew/tap.rb', line 502

def to_hash
  hash = {
    "name"          => name,
    "user"          => user,
    "repo"          => repo,
    "path"          => path.to_s,
    "installed"     => installed?,
    "official"      => official?,
    "formula_names" => formula_names,
    "formula_files" => formula_files.map(&:to_s),
    "cask_tokens"   => cask_tokens,
    "cask_files"    => cask_files.map(&:to_s),
    "command_files" => command_files.map(&:to_s),
  }

  if installed?
    hash["remote"] = remote
    hash["custom_remote"] = custom_remote?
    hash["private"] = private?
  end

  hash
end

#to_s ⇒ Object 


174
175
176
 
# File 'Library/Homebrew/tap.rb', line 174

def to_s
  name
end

#uninstall ⇒ Object

Uninstall this Tap.

Raises:


318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'Library/Homebrew/tap.rb', line 318

def uninstall
  require "descriptions"
  raise TapUnavailableError, name unless installed?

  $stderr.puts "Untapping #{name}..."

  abv = path.abv
  formatted_contents = contents.presence&.to_sentence&.dup&.prepend(" ")

  unpin if pinned?
  CacheStoreDatabase.use(:descriptions) do |db|
    DescriptionCacheStore.new(db)
                         .delete_from_formula_names!(formula_names)
  end
  Utils::Link.unlink_manpages(path)
  Utils::Link.unlink_completions(path)
  path.rmtree
  path.parent.rmdir_if_possible
  $stderr.puts "Untapped#{formatted_contents} (#{abv})."

  Commands.rebuild_commands_completion_list
  clear_cache
end

#version_string ⇒ Object 


178
179
180
181
182
183
184
185
 
# File 'Library/Homebrew/tap.rb', line 178

def version_string
  return "N/A" unless installed?

  pretty_revision = git_short_head
  return "(no git repository)" unless pretty_revision

  "(git revision #{pretty_revision}; last commit #{git_last_commit_date})"
end