Module: Commands Private

Defined in:
commands.rb,
command_constants.rb

Overview

This module is part of a private API. This module may only be used in the Homebrew/brew repository. Third parties should avoid using this module if possible, as it may be removed or changed without warning.

Paths and aliases for built-in commands.

Constant Summary collapse

DESCRIPTION_SPLITTING_PATTERN =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

This pattern is used to split descriptions at full stops. We only consider a dot as a full stop if it is either followed by a whitespace or at the end of the description. In this way we can prevent cutting off a sentence in the middle due to dots in URLs or paths.

/\.(?>\s|$)/
HOMEBREW_CMD_PATH =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

T.let((HOMEBREW_LIBRARY_PATH/"cmd").freeze, Pathname)
HOMEBREW_DEV_CMD_PATH =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

T.let((HOMEBREW_LIBRARY_PATH/"dev-cmd").freeze, Pathname)
HOMEBREW_INTERNAL_COMMAND_ALIASES =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

If you are going to change anything in below hash, be sure to also update appropriate case statement in brew.sh

T.let({
  "ls"           => "list",
  "homepage"     => "home",
  "-S"           => "search",
  "up"           => "update",
  "ln"           => "link",
  "instal"       => "install", # gem does the same
  "uninstal"     => "uninstall",
  "post_install" => "postinstall",
  "rm"           => "uninstall",
  "remove"       => "uninstall",
  "abv"          => "info",
  "dr"           => "doctor",
  "--repo"       => "--repository",
  "environment"  => "--env",
  "--config"     => "config",
  "-v"           => "--version",
  "lc"           => "livecheck",
  "tc"           => "typecheck",
  "x"            => "exec",
}.freeze, T::Hash[String, String])

Class Method Summary collapse

Class Method Details

.args_method_name(cmd_path) ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



52
53
54
55
56
 
# File 'commands.rb', line 52

def self.args_method_name(cmd_path)
  cmd_path_basename = basename_without_extension(cmd_path)
  cmd_method_prefix = method_name(cmd_path_basename)
  :"#{cmd_method_prefix}_args"
end

.basename_without_extension(path) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



205
206
207
 
# File 'commands.rb', line 205

def self.basename_without_extension(path)
  path.basename(path.extname).to_s
end

.command_description(command, short: false) ⇒ String?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • command (String)
  • short (Boolean) (defaults to: false)

Returns:



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
310
 
# File 'commands.rb', line 283

def self.command_description(command, short: false)
  path = self.path(command)
  return unless path

  if (cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path))
    if short
      cmd_parser.description&.split(DESCRIPTION_SPLITTING_PATTERN)&.first
    else
      cmd_parser.description
    end
  else
    comment_lines = path.read.lines.grep(/^#:/)

    # skip the comment's initial usage summary lines
    comment_lines.slice(2..-1)&.each do |line|
      match_data = /^#:  (?<desc>\w.*+)$/.match(line)
      next unless match_data

      desc = match_data[:desc]
      next if desc.nil?

      return desc.split(DESCRIPTION_SPLITTING_PATTERN).first if short

      return desc
    end
    nil
  end
end

.command_options(command, subcommand: nil) ⇒ Array<Array<(String, String)>>?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • command (String)
  • subcommand (String, nil) (defaults to: nil)

Returns:



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
 
# File 'commands.rb', line 248

def self.command_options(command, subcommand: nil)
  return if command == "help"

  path = self.path(command)
  return unless path

  if (cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path))
    processed_options = if subcommand.nil? && cmd_parser.subcommands.present?
      cmd_parser.processed_options_for_root_command
    else
      cmd_parser.processed_options_for_subcommand(subcommand)
    end
    processed_options.filter_map do |short, long, desc, hidden|
      next if hidden

      option = long || short
      next if option.nil?

      [option, desc]
    end
  else
    options = []
    comment_lines = path.read.lines.grep(/^#:/)
    return options if comment_lines.empty?

    # skip the comment's initial usage summary lines
    comment_lines.slice(2..-1)&.each do |line|
      match_data = / (?<option>-[-\w]+) +(?<desc>.*)$/.match(line)
      options << [match_data[:option], match_data[:desc]] if match_data
    end
    options
  end
end

.command_subcommands(command) ⇒ Array<Homebrew::CLI::Parser::Subcommand>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



313
314
315
316
317
318
319
320
321
 
# File 'commands.rb', line 313

def self.command_subcommands(command)
  path = self.path(command)
  return [] unless path

  cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
  return [] if cmd_parser.blank?

  cmd_parser.subcommands
end

.commands(external: true, aliases: false) ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • external (Boolean) (defaults to: true)
  • aliases (Boolean) (defaults to: false)

Returns:



128
129
130
131
132
133
134
 
# File 'commands.rb', line 128

def self.commands(external: true, aliases: false)
  cmds = internal_commands
  cmds += internal_developer_commands
  cmds += external_commands if external
  cmds += internal_commands_aliases if aliases
  cmds.sort
end

.external_cmd_path(cmd) ⇒ Pathname?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



99
100
101
102
103
104
105
 
# File 'commands.rb', line 99

def self.external_cmd_path(cmd)
  return unless valid_cmd_name?(cmd)

  path = which("brew-#{cmd}", PATH.new(ENV.fetch("PATH")).append(tap_cmd_directories))
  require_trusted_command!(path, cmd)
  path
end

.external_commands ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'commands.rb', line 190

def self.external_commands
  tap_cmd_directories.flat_map do |path|
    commands = find_commands(path).select(&:executable?)
    if path.expand_path.ascend.any?(HOMEBREW_TAP_DIRECTORY)
      require "trust"
      commands = Homebrew::Trust.trusted_command_files(commands)
    end
    commands
      .map { |basename| basename_without_extension(basename) }
      .map { |p| p.to_s.delete_prefix("brew-").strip }
  end.map(&:to_s)
     .sort
end

.external_ruby_cmd_path(cmd) ⇒ Pathname?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Ruby commands which are run by being required.

Parameters:

Returns:



90
91
92
93
94
95
96
 
# File 'commands.rb', line 90

def self.external_ruby_cmd_path(cmd)
  return unless valid_cmd_name?(cmd)

  path = which("brew-#{cmd}.rb", PATH.new(ENV.fetch("PATH")).append(tap_cmd_directories))
  require_trusted_command!(path, cmd)
  path
end

.external_ruby_v2_cmd_path(cmd) ⇒ Pathname?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Ruby commands which can be required without being run.

Parameters:

Returns:



80
81
82
83
84
85
86
 
# File 'commands.rb', line 80

def self.external_ruby_v2_cmd_path(cmd)
  return unless valid_cmd_name?(cmd)

  path = which("#{cmd}.rb", tap_cmd_directories)
  require_trusted_command!(path, cmd)
  path if ENV.clear_sensitive_environment! { Utils::Ruby.require?(path) }
end

.find_commands(path) ⇒ Array<Pathname>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



210
211
212
213
214
 
# File 'commands.rb', line 210

def self.find_commands(path)
  Pathname.glob("#{path}/*")
          .select(&:file?)
          .sort
end

.find_internal_commands(path) ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

Raises:

  • (ArgumentError) 


179
180
181
182
183
184
185
186
187
 
# File 'commands.rb', line 179

def self.find_internal_commands(path)
  raise ArgumentError, "#{path} is not an official command path" \
    unless [HOMEBREW_CMD_PATH, HOMEBREW_DEV_CMD_PATH].include?(path)

  find_commands(path).map(&:basename)
                     .map { |basename| basename_without_extension(basename) }
                     .uniq
                     .reject { |name| Homebrew::CLI::Parser.from_cmd_path(path/"#{name}.rb")&.hide_from_man_page }
end

.internal_cmd_path(cmd) ⇒ Pathname?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



59
60
61
62
63
64
65
66
 
# File 'commands.rb', line 59

def self.internal_cmd_path(cmd)
  return unless valid_cmd_name?(cmd)

  [
    HOMEBREW_CMD_PATH/"#{cmd}.rb",
    HOMEBREW_CMD_PATH/"#{cmd}.sh",
  ].find(&:exist?)
end

.internal_commands ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



164
165
166
 
# File 'commands.rb', line 164

def self.internal_commands
  find_internal_commands(HOMEBREW_CMD_PATH).map(&:to_s)
end

.internal_commands_aliases ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



174
175
176
 
# File 'commands.rb', line 174

def self.internal_commands_aliases
  HOMEBREW_INTERNAL_COMMAND_ALIASES.keys
end

.internal_commands_paths ⇒ Array<Pathname>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



154
155
156
 
# File 'commands.rb', line 154

def self.internal_commands_paths
  find_commands HOMEBREW_CMD_PATH
end

.internal_dev_cmd_path(cmd) ⇒ Pathname?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



69
70
71
72
73
74
75
76
 
# File 'commands.rb', line 69

def self.internal_dev_cmd_path(cmd)
  return unless valid_cmd_name?(cmd)

  [
    HOMEBREW_DEV_CMD_PATH/"#{cmd}.rb",
    HOMEBREW_DEV_CMD_PATH/"#{cmd}.sh",
  ].find(&:exist?)
end

.internal_developer_commands ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



169
170
171
 
# File 'commands.rb', line 169

def self.internal_developer_commands
  find_internal_commands(HOMEBREW_DEV_CMD_PATH).map(&:to_s)
end

.internal_developer_commands_paths ⇒ Array<Pathname>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



159
160
161
 
# File 'commands.rb', line 159

def self.internal_developer_commands_paths
  find_commands HOMEBREW_DEV_CMD_PATH
end

.method_name(cmd) ⇒ Symbol

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



44
45
46
47
48
49
 
# File 'commands.rb', line 44

def self.method_name(cmd)
  cmd.to_s
     .tr("-", "_")
     .downcase
     .to_sym
end

.named_args_type(command, subcommand: nil) ⇒ Array<Symbol>, ...

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • command (String)
  • subcommand (String, nil) (defaults to: nil)

Returns:



327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'commands.rb', line 327

def self.named_args_type(command, subcommand: nil)
  path = self.path(command)
  return unless path

  cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
  return if cmd_parser.blank?

  args_type = if subcommand
    cmd_parser.named_args_type_for_subcommand(subcommand)
  else
    cmd_parser.named_args_type
  end
  Array(args_type)
end

.option_conflicts(command, option) ⇒ Array<String>?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns the conflicts of a given option for command.

Parameters:

Returns:



344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'commands.rb', line 344

def self.option_conflicts(command, option)
  path = self.path(command)
  return unless path

  cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
  return if cmd_parser.blank?

  hidden_options = cmd_parser.processed_options.filter_map do |short, long, _desc, hidden|
    next unless hidden

    option_name = long || short
    next unless option_name

    Homebrew::CLI::Parser.option_to_name(option_name).tr("_", "-")
  end

  cmd_parser.conflicts.map do |set|
    set = set.map { |s| s.tr "_", "-" } - hidden_options
    set - [option] if set.include? option
  end.flatten.compact
end

.path(cmd) ⇒ Pathname?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



117
118
119
120
121
122
123
124
125
 
# File 'commands.rb', line 117

def self.path(cmd)
  internal_cmd = HOMEBREW_INTERNAL_COMMAND_ALIASES.fetch(cmd, cmd)
  path ||= internal_cmd_path(internal_cmd)
  path ||= internal_dev_cmd_path(internal_cmd)
  path ||= external_ruby_v2_cmd_path(cmd)
  path ||= external_ruby_cmd_path(cmd)
  path ||= external_cmd_path(cmd)
  path
end

.rebuild_commands_completion_list ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'commands.rb', line 231

def self.rebuild_commands_completion_list
  require "completions"

  # Ensure that the cache exists so we can build the commands list
  HOMEBREW_CACHE.mkpath

  # Don't reject `command_hidden_from_manpage?` commands here: internal ones
  # are already excluded and checking externals loads every tap command file.
  cmds = commands - Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST

  all_commands_file = HOMEBREW_CACHE/"all_commands_list.txt"
  external_commands_file = HOMEBREW_CACHE/"external_commands_list.txt"
  all_commands_file.atomic_write("#{cmds.sort.join("\n")}\n")
  external_commands_file.atomic_write("#{external_commands.sort.join("\n")}\n")
end

.rebuild_internal_commands_completion_list ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'commands.rb', line 217

def self.rebuild_internal_commands_completion_list
  require "completions"

  cmds = internal_commands + internal_developer_commands
  cmds.reject! do |cmd|
    Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST.include?(cmd) ||
      Homebrew::Completions.command_hidden_from_manpage?(cmd)
  end

  file = HOMEBREW_REPOSITORY/"completions/internal_commands_list.txt"
  file.atomic_write("#{cmds.sort.join("\n")}\n")
end

.require_trusted_command!(path, cmd) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



108
109
110
111
112
113
114
 
# File 'commands.rb', line 108

def self.require_trusted_command!(path, cmd)
  return unless path
  return if path.expand_path.ascend.none?(HOMEBREW_TAP_DIRECTORY)

  require "trust"
  Homebrew::Trust.require_trusted_command!(path, cmd)
end

.suggestion_message(cmd) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



137
138
139
140
141
142
143
144
145
 
# File 'commands.rb', line 137

def self.suggestion_message(cmd)
  require "did_you_mean"

  suggestions = DidYouMean::SpellChecker.new(dictionary: commands(external: false, aliases: true)).correct(cmd)
  suggestions = DidYouMean::SpellChecker.new(dictionary: commands(aliases: true)).correct(cmd) if suggestions.empty?
  return "" if suggestions.empty?

  "\nDid you mean #{Utils::Text.to_sentence(suggestions, conjunction: "or")}?"
end

.tap_cmd_directories ⇒ Array<Pathname>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

An array of all tap cmd directory Pathnames.

Returns:



149
150
151
 
# File 'commands.rb', line 149

def self.tap_cmd_directories
  Pathname.glob HOMEBREW_TAP_DIRECTORY/"*/*/cmd"
end

.valid_cmd_name?(cmd) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Keep in sync with the command name check in brew.sh.

Parameters:

Returns:

  • (Boolean) 


23
24
25
 
# File 'commands.rb', line 23

def self.valid_cmd_name?(cmd)
  cmd.exclude?("/") && %w[. ..].exclude?(cmd)
end

.valid_internal_cmd?(cmd) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


28
29
30
 
# File 'commands.rb', line 28

def self.valid_internal_cmd?(cmd)
  valid_cmd_name?(cmd) && Utils::Ruby.require?(HOMEBREW_CMD_PATH/cmd)
end

.valid_internal_dev_cmd?(cmd) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


33
34
35
 
# File 'commands.rb', line 33

def self.valid_internal_dev_cmd?(cmd)
  valid_cmd_name?(cmd) && Utils::Ruby.require?(HOMEBREW_DEV_CMD_PATH/cmd)
end

.valid_ruby_cmd?(cmd) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


38
39
40
41
 
# File 'commands.rb', line 38

def self.valid_ruby_cmd?(cmd)
  (valid_internal_cmd?(cmd) || valid_internal_dev_cmd?(cmd) || external_ruby_v2_cmd_path(cmd).present?) &&
    (Homebrew::AbstractCommand.command(cmd)&.ruby_cmd? == true)
end