mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve discovery of some environment variables

Browse Source 
There's a few bits of functionality that Homebrew has changed over the
years, makes sense as a sensible default but some people find really
annoying:

- automatically running `brew update`
- automatically running `brew cleanup`
- automatically upgrading outdated dependents
- automatically reinstalling broken dependents

For each of these: let's improve the documentation of the commands
whose behaviour is changed and the environment variables themselves.
This commit is contained in:
Mike McQuaid 2021-11-25 09:10:59 +00:00
parent 49e232429e
commit 11c5f8f05a
No known key found for this signature in database
GPG Key ID: 3338A31AFDB1D829
15 changed files with 95 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Library/Homebrew/.rubocop.yml
View File

@ -16,7 +16,7 @@ Lint/NestedMethodDefinition:
Metrics/AbcSize:
Max: 280
Metrics/BlockLength:
Max: 100
Max: 102
Exclude:
# TODO: extract more of the bottling logic
- "dev-cmd/bottle.rb"

11
Library/Homebrew/brew.rb
View File

@ -179,10 +179,13 @@ rescue MethodDeprecatedError => e
exit 1
rescue Exception => e # rubocop:disable Lint/RescueException
onoe e
if internal_cmd && defined?(OS::ISSUES_URL) &&
!Homebrew::EnvConfig.no_auto_update?
$stderr.puts "#{Tty.bold}Please report this issue:#{Tty.reset}"
$stderr.puts " #{Formatter.url(OS::ISSUES_URL)}"
if internal_cmd && defined?(OS::ISSUES_URL)
if Homebrew::EnvConfig.no_auto_update?
$stderr.puts "#{Tty.bold}Do not report this issue until you've run `brew update` and tried again.#{Tty.reset}"
else
$stderr.puts "#{Tty.bold}Please report this issue:#{Tty.reset}"
$stderr.puts " #{Formatter.url(OS::ISSUES_URL)}"
end
end
$stderr.puts e.backtrace
exit 1

6
Library/Homebrew/cleanup.rb
View File

@ -161,6 +161,7 @@ module Homebrew
if cleanup.periodic_clean_due?
cleanup.periodic_clean!
elsif f.latest_version_installed? && !cleanup.skip_clean_formula?(f)
ohai "Running `brew cleanup #{f}`..."
cleanup.cleanup_formula(f)
end
end
@ -191,8 +192,11 @@ module Homebrew
ohai "Would run `brew cleanup` which has not been run in the last #{CLEANUP_DEFAULT_DAYS} days"
else
ohai "`brew cleanup` has not been run in the last #{CLEANUP_DEFAULT_DAYS} days, running now..."
clean!(quiet: true, periodic: true)
end
return if dry_run?
clean!(quiet: true, periodic: true)
end
def clean!(quiet: false, periodic: false)

6
Library/Homebrew/cmd/install.rb
View File

@ -27,8 +27,14 @@ module Homebrew
Install a <formula> or <cask>. Additional options specific to a <formula> may be
appended to the command.
Unless `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK` is set, `brew upgrade` or `brew reinstall` will be run for
outdated dependents and dependents with broken linkage, respectively.
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
the installed formulae or, every 30 days, for all formulae.
Unless `HOMEBREW_NO_INSTALL_UPGRADE` is set, `brew install <formula>` will upgrade <formula> if it
is already installed but outdated.
EOS
switch "-d", "--debug",
description: "If brewing fails, open an interactive debugging session with access to IRB " \

3
Library/Homebrew/cmd/reinstall.rb
View File

@ -26,6 +26,9 @@ module Homebrew
Uninstall and then reinstall a <formula> or <cask> using the same options it was
originally installed with, plus any appended options specific to a <formula>.
Unless `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK` is set, `brew upgrade` or `brew reinstall` will be run for
outdated dependents and dependents with broken linkage, respectively.
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
reinstalled formulae or, every 30 days, for all formulae.
EOS

3
Library/Homebrew/cmd/upgrade.rb
View File

@ -23,6 +23,9 @@ module Homebrew
installed with, plus any appended brew formula options. If <cask> or <formula> are specified,
upgrade only the given <cask> or <formula> kegs (unless they are pinned; see `pin`, `unpin`).
Unless `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK` is set, `brew upgrade` or `brew reinstall` will be run for
outdated dependents and dependents with broken linkage, respectively.
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
upgraded formulae or, every 30 days, for all formulae.
EOS

2
Library/Homebrew/dev-cmd/pr-pull.rb
View File

@ -301,7 +301,7 @@ module Homebrew
def changed_formulae(tap, original_commit)
if Homebrew::EnvConfig.disable_load_formula?
opoo "Can't check if updated bottles are necessary as formula loading is disabled!"
opoo "Can't check if updated bottles are necessary as HOMEBREW_DISABLE_LOAD_FORMULA is set!"
return
end

4
Library/Homebrew/download_strategy.rb
View File

@ -520,7 +520,7 @@ class CurlDownloadStrategy < AbstractFileDownloadStrategy
if Homebrew::EnvConfig.no_insecure_redirect? &&
url.start_with?("https://") && !resolved_url.start_with?("https://")
$stderr.puts "HTTPS to HTTP redirect detected & HOMEBREW_NO_INSECURE_REDIRECT is set."
$stderr.puts "HTTPS to HTTP redirect detected and HOMEBREW_NO_INSECURE_REDIRECT is set."
raise CurlDownloadStrategyError, url
end
@ -1029,6 +1029,7 @@ class GitHubGitDownloadStrategy < GitDownloadStrategy
end
def github_last_commit
# TODO: move to Utils::GitHub
return if Homebrew::EnvConfig.no_github_api?
output, _, status = curl_output(
@ -1045,6 +1046,7 @@ class GitHubGitDownloadStrategy < GitDownloadStrategy
end
def multiple_short_commits_exist?(commit)
# TODO: move to Utils::GitHub
return if Homebrew::EnvConfig.no_github_api?
output, _, status = curl_output(

21
Library/Homebrew/env_config.rb
View File

@ -26,7 +26,9 @@ module Homebrew
"`http://localhost:8080/example.com/foo.tar.gz`.",
},
HOMEBREW_AUTO_UPDATE_SECS: {
description: "Automatically check for updates once per this seconds interval.",
description: "Run `brew update` once every `HOMEBREW_AUTO_UPDATE_SECS` seconds before some commands, " \
"e.g. `brew install`, `brew upgrade` and `brew tap`. Alternatively, " \
"disable auto-update entirely with HOMEBREW_NO_AUTO_UPDATE.",
default: 300,
},
HOMEBREW_BAT: {
@ -221,8 +223,9 @@ module Homebrew
boolean: true,
},
HOMEBREW_NO_AUTO_UPDATE: {
description: "If set, do not automatically update before running some commands e.g. " \
"`brew install`, `brew upgrade` and `brew tap`.",
description: "If set, do not automatically update before running some commands, e.g. " \
"`brew install`, `brew upgrade` and `brew tap`. Alternatively, " \
"run this less often by setting HOMEBREW_AUTO_UPDATE_SECS to a value higher than the default.",
boolean: true,
},
HOMEBREW_NO_BOOTSNAP: {
@ -230,8 +233,10 @@ module Homebrew
boolean: true,
},
HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: {
description: "If set, do not check for broken dependents after installing, upgrading or reinstalling " \
"formulae.",
description: "If set, do not check for broken linkage of dependents or outdated dependents after " \
"installing, upgrading or reinstalling formulae. This will result in fewer dependents " \
" (and their dependencies) being upgraded or reinstalled but may result in more breakage " \
"from running `brew install <formula>` or `brew upgrade <formula>`.",
boolean: true,
},
HOMEBREW_NO_CLEANUP_FORMULAE: {
@ -266,11 +271,13 @@ module Homebrew
HOMEBREW_NO_INSTALL_CLEANUP: {
description: "If set, `brew install`, `brew upgrade` and `brew reinstall` will never automatically " \
"cleanup installed/upgraded/reinstalled formulae or all formulae every " \
"`HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS` days.",
"`HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS` days. Alternatively, HOMEBREW_NO_CLEANUP_FORMULAE " \
"allows specifying specific formulae to not clean up.",
boolean: true,
},
HOMEBREW_NO_INSTALL_UPGRADE: {
description: "If set, `brew install` will not automatically upgrade installed but outdated formulae",
description: "If set, `brew install <formula>` will not upgrade `<formula>` if it is installed but " \
"outdated.",
boolean: true,
},
HOMEBREW_PRY: {

6
Library/Homebrew/formula_installer.rb
View File

@ -1302,7 +1302,8 @@ class FormulaInstaller
next unless SPDX.licenses_forbid_installation? dep_f.license, forbidden_licenses
raise CannotInstallFormulaError, <<~EOS
The installation of #{formula.name} has a dependency on #{dep.name} where all its licenses are forbidden:
The installation of #{formula.name} has a dependency on #{dep.name} where all
its licenses are forbidden by HOMEBREW_FORBIDDEN_LICENSES:
#{SPDX.license_expression_to_string dep_f.license}.
EOS
end
@ -1312,7 +1313,8 @@ class FormulaInstaller
return unless SPDX.licenses_forbid_installation? formula.license, forbidden_licenses
raise CannotInstallFormulaError, <<~EOS
#{formula.name}'s licenses are all forbidden: #{SPDX.license_expression_to_string formula.license}.
#{formula.name}'s licenses are all forbidden by HOMEBREW_FORBIDDEN_LICENSES:
#{SPDX.license_expression_to_string formula.license}.
EOS
end
end

7
Library/Homebrew/install.rb
View File

@ -125,7 +125,10 @@ module Homebrew
# dependencies. Therefore before performing other checks we need to be
# sure --force flag is passed.
if f.outdated?
return true unless Homebrew::EnvConfig.no_install_upgrade?
unless Homebrew::EnvConfig.no_install_upgrade?
puts "#{f.name} #{f.linked_version} is already installed but outdated (so it will be upgraded)."
return true
end
optlinked_version = Keg.for(f.opt_prefix).version
onoe <<~EOS
@ -213,7 +216,7 @@ module Homebrew
message = "#{f.name} #{f.linked_version} is already installed"
if f.outdated? && !head
unless Homebrew::EnvConfig.no_install_upgrade?
puts "#{message} but outdated"
puts "#{message} but outdated (so it will be upgraded)."
return true
end

2
Library/Homebrew/manpages/brew.1.md.erb
View File

@ -57,6 +57,8 @@ For the full command list, see the [COMMANDS](#commands) section.
With `--verbose` or `--debug`, many commands print extra debugging information.
Note that these options should only appear after a command.
Some command behaviour can be customised with environment variables; see the [ENVIRONMENT](#environment) section.
### `install` <formula>
Install <formula>.

3
Library/Homebrew/upgrade.rb
View File

@ -318,6 +318,7 @@ module Homebrew
# Assess the dependents tree again now we've upgraded.
oh1 "Checking for dependents of upgraded formulae..." unless dry_run
broken_dependents = check_broken_dependents(installed_formulae)
if broken_dependents.blank?
if dry_run
@ -354,7 +355,7 @@ module Homebrew
else
count = reinstallable_broken_dependents.count
plural = "dependent".pluralize(reinstallable_broken_dependents.count)
ohai "Reinstalling #{count} broken #{plural} from source:"
ohai "Reinstalling #{count} #{plural} with broken linkage from source:"
puts reinstallable_broken_dependents.map(&:full_specified_name)
.join(", ")
end

24
docs/Manpage.md
View File

@ -41,6 +41,8 @@ For the full command list, see the [COMMANDS](#commands) section.
With `--verbose` or `--debug`, many commands print extra debugging information.
Note that these options should only appear after a command.
Some command behaviour can be customised with environment variables; see the [ENVIRONMENT](#environment) section.
### `install` *`formula`*
Install *`formula`*.
@ -301,9 +303,15 @@ If a *`formula`* or *`cask`* is provided, show summary of information about it.
Install a *`formula`* or *`cask`*. Additional options specific to a *`formula`* may be
appended to the command.
Unless `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK` is set, `brew upgrade` or `brew reinstall` will be run for
outdated dependents and dependents with broken linkage, respectively.
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
the installed formulae or, every 30 days, for all formulae.
Unless `HOMEBREW_NO_INSTALL_UPGRADE` is set, `brew install *`formula`*` will upgrade *`formula`* if it
is already installed but outdated.
* `-d`, `--debug`:
If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory.
* `-f`, `--force`:
@ -507,6 +515,9 @@ all items or checking if any current formulae/casks have Ruby issues.
Uninstall and then reinstall a *`formula`* or *`cask`* using the same options it was
originally installed with, plus any appended options specific to a *`formula`*.
Unless `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK` is set, `brew upgrade` or `brew reinstall` will be run for
outdated dependents and dependents with broken linkage, respectively.
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
reinstalled formulae or, every 30 days, for all formulae.
@ -683,6 +694,9 @@ Upgrade outdated casks and outdated, unpinned formulae using the same options th
installed with, plus any appended brew formula options. If *`cask`* or *`formula`* are specified,
upgrade only the given *`cask`* or *`formula`* kegs (unless they are pinned; see `pin`, `unpin`).
Unless `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK` is set, `brew upgrade` or `brew reinstall` will be run for
outdated dependents and dependents with broken linkage, respectively.
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the
upgraded formulae or, every 30 days, for all formulae.
@ -1898,7 +1912,7 @@ example, run `export HOMEBREW_NO_INSECURE_REDIRECT=1` rather than just
<br>Prefix all download URLs, including those for bottles, with this value. For example, `HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080` will cause a formula with the URL `https://example.com/foo.tar.gz` to instead download from `http://localhost:8080/example.com/foo.tar.gz`.
- `HOMEBREW_AUTO_UPDATE_SECS`
<br>Automatically check for updates once per this seconds interval.
<br>Run `brew update` once every `HOMEBREW_AUTO_UPDATE_SECS` seconds before some commands, e.g. `brew install`, `brew upgrade` and `brew tap`. Alternatively, disable auto-update entirely with HOMEBREW_NO_AUTO_UPDATE.
*Default:* `300`.
@ -2057,13 +2071,13 @@ example, run `export HOMEBREW_NO_INSECURE_REDIRECT=1` rather than just
<br>If set, do not send analytics. For more information, see: <https://docs.brew.sh/Analytics>
- `HOMEBREW_NO_AUTO_UPDATE`
<br>If set, do not automatically update before running some commands e.g. `brew install`, `brew upgrade` and `brew tap`.
<br>If set, do not automatically update before running some commands, e.g. `brew install`, `brew upgrade` and `brew tap`. Alternatively, run this less often by setting HOMEBREW_AUTO_UPDATE_SECS to a value higher than the default.
- `HOMEBREW_NO_BOOTSNAP`
<br>If set, do not use Bootsnap to speed up repeated `brew` calls.
- `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK`
<br>If set, do not check for broken dependents after installing, upgrading or reinstalling formulae.
<br>If set, do not check for broken linkage of dependents or outdated dependents after installing, upgrading or reinstalling formulae. This will result in fewer dependents (and their dependencies) being upgraded or reinstalled but may result in more breakage from running `brew install *`formula`*` or `brew upgrade *`formula`*`.
- `HOMEBREW_NO_CLEANUP_FORMULAE`
<br>A comma-separated list of formulae. Homebrew will refuse to clean up a formula if it appears on this list.
@ -2090,10 +2104,10 @@ example, run `export HOMEBREW_NO_INSECURE_REDIRECT=1` rather than just
*Note:* While ensuring your downloads are fully secure, this is likely to cause from-source SourceForge, some GNU & GNOME-hosted formulae to fail to download.
- `HOMEBREW_NO_INSTALL_CLEANUP`
<br>If set, `brew install`, `brew upgrade` and `brew reinstall` will never automatically cleanup installed/upgraded/reinstalled formulae or all formulae every `HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS` days.
<br>If set, `brew install`, `brew upgrade` and `brew reinstall` will never automatically cleanup installed/upgraded/reinstalled formulae or all formulae every `HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS` days. Alternatively, HOMEBREW_NO_CLEANUP_FORMULAE allows specifying specific formulae to not clean up.
- `HOMEBREW_NO_INSTALL_UPGRADE`
<br>If set, `brew install` will not automatically upgrade installed but outdated formulae
<br>If set, `brew install *`formula`*` will not upgrade `*`formula`*` if it is installed but outdated.
- `HOMEBREW_PRY`
<br>If set, use Pry for the `brew irb` command.

25
manpages/brew.1
View File

@ -61,6 +61,9 @@ For the full command list, see the \fICOMMANDS\fR section\.
.P
With \fB\-\-verbose\fR or \fB\-\-debug\fR, many commands print extra debugging information\. Note that these options should only appear after a command\.
.
.P
Some command behaviour can be customised with environment variables; see the \fIENVIRONMENT\fR section\.
.
.SS "\fBinstall\fR \fIformula\fR"
Install \fIformula\fR\.
.
@ -389,8 +392,14 @@ Treat all named arguments as casks\.
Install a \fIformula\fR or \fIcask\fR\. Additional options specific to a \fIformula\fR may be appended to the command\.
.
.P
Unless \fBHOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK\fR is set, \fBbrew upgrade\fR or \fBbrew reinstall\fR will be run for outdated dependents and dependents with broken linkage, respectively\.
.
.P
Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the installed formulae or, every 30 days, for all formulae\.
.
.P
Unless \fBHOMEBREW_NO_INSTALL_UPGRADE\fR is set, \fBbrew install <formula>\fR will upgrade \fIformula\fR if it is already installed but outdated\.
.
.TP
\fB\-d\fR, \fB\-\-debug\fR
If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory\.
@ -691,6 +700,9 @@ Syntax\-check all of Homebrew\'s Ruby files (if no \fB<tap>\fR is passed)\.
Uninstall and then reinstall a \fIformula\fR or \fIcask\fR using the same options it was originally installed with, plus any appended options specific to a \fIformula\fR\.
.
.P
Unless \fBHOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK\fR is set, \fBbrew upgrade\fR or \fBbrew reinstall\fR will be run for outdated dependents and dependents with broken linkage, respectively\.
.
.P
Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the reinstalled formulae or, every 30 days, for all formulae\.
.
.TP
@ -933,6 +945,9 @@ Fetch and reset Homebrew and all tap repositories (or any specified \fIrepositor
Upgrade outdated casks and outdated, unpinned formulae using the same options they were originally installed with, plus any appended brew formula options\. If \fIcask\fR or \fIformula\fR are specified, upgrade only the given \fIcask\fR or \fIformula\fR kegs (unless they are pinned; see \fBpin\fR, \fBunpin\fR)\.
.
.P
Unless \fBHOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK\fR is set, \fBbrew upgrade\fR or \fBbrew reinstall\fR will be run for outdated dependents and dependents with broken linkage, respectively\.
.
.P
Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the upgraded formulae or, every 30 days, for all formulae\.
.
.TP
@ -2684,7 +2699,7 @@ Prefix all download URLs, including those for bottles, with this value\. For exa
\fBHOMEBREW_AUTO_UPDATE_SECS\fR
.
.br
Automatically check for updates once per this seconds interval\.
Run \fBbrew update\fR once every \fBHOMEBREW_AUTO_UPDATE_SECS\fR seconds before some commands, e\.g\. \fBbrew install\fR, \fBbrew upgrade\fR and \fBbrew tap\fR\. Alternatively, disable auto\-update entirely with HOMEBREW_NO_AUTO_UPDATE\.
.
.IP
\fIDefault:\fR \fB300\fR\.
@ -2981,7 +2996,7 @@ If set, do not send analytics\. For more information, see: \fIhttps://docs\.brew
\fBHOMEBREW_NO_AUTO_UPDATE\fR
.
.br
If set, do not automatically update before running some commands e\.g\. \fBbrew install\fR, \fBbrew upgrade\fR and \fBbrew tap\fR\.
If set, do not automatically update before running some commands, e\.g\. \fBbrew install\fR, \fBbrew upgrade\fR and \fBbrew tap\fR\. Alternatively, run this less often by setting HOMEBREW_AUTO_UPDATE_SECS to a value higher than the default\.
.
.TP
\fBHOMEBREW_NO_BOOTSNAP\fR
@ -2993,7 +3008,7 @@ If set, do not use Bootsnap to speed up repeated \fBbrew\fR calls\.
\fBHOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK\fR
.
.br
If set, do not check for broken dependents after installing, upgrading or reinstalling formulae\.
If set, do not check for broken linkage of dependents or outdated dependents after installing, upgrading or reinstalling formulae\. This will result in fewer dependents (and their dependencies) being upgraded or reinstalled but may result in more breakage from running \fBbrew install <formula>\fR or \fBbrew upgrade <formula>\fR\.
.
.TP
\fBHOMEBREW_NO_CLEANUP_FORMULAE\fR
@ -3044,13 +3059,13 @@ If set, forbid redirects from secure HTTPS to insecure HTTP\.
\fBHOMEBREW_NO_INSTALL_CLEANUP\fR
.
.br
If set, \fBbrew install\fR, \fBbrew upgrade\fR and \fBbrew reinstall\fR will never automatically cleanup installed/upgraded/reinstalled formulae or all formulae every \fBHOMEBREW_CLEANUP_PERIODIC_FULL_DAYS\fR days\.
If set, \fBbrew install\fR, \fBbrew upgrade\fR and \fBbrew reinstall\fR will never automatically cleanup installed/upgraded/reinstalled formulae or all formulae every \fBHOMEBREW_CLEANUP_PERIODIC_FULL_DAYS\fR days\. Alternatively, HOMEBREW_NO_CLEANUP_FORMULAE allows specifying specific formulae to not clean up\.
.
.TP
\fBHOMEBREW_NO_INSTALL_UPGRADE\fR
.
.br
If set, \fBbrew install\fR will not automatically upgrade installed but outdated formulae
If set, \fBbrew install <formula>\fR will not upgrade \fB<formula>\fR if it is installed but outdated\.
.
.TP
\fBHOMEBREW_PRY\fR