Improve the messaging around `brew install` when there's a possible user
action such as an `upgrade` or `link` and don't tell people to
`install --force` when it's unnecessary.
While I did this, tweak the output and function usage in a couple of
related places.
Some example output before this change:
```
Warning: openssl is a keg-only and another version is linked to opt.
Use `brew install --force` if you want to install this version
Warning: mysql@5.6 is a keg-only and another version is linked to opt.
Use `brew install --force` if you want to install this version
Warning: analog-6.0_1 already installed
Warning: bash-completion@2-2.5 already installed, it's just not linked.
```
Some example output after this change:
```
Error: openssl 1.0.2k is already installed
To upgrade to 1.0.2l, run `brew upgrade openssl`
Warning: mysql@5.6 5.6.36_1 is already installed
Warning: analog 6.0_1 is already installed
Warning: bash-completion@2 2.5 is already installed, it's just not linked.
You can use `brew link bash-completion@2` to link this version.
```
Only likely to kick in when environment filtering is enabled.
Otherwise we need to tediously add a dramatic number of PATHs to tests
or recurse through the runtime formulae dependencies and add all them.
CC @ilovezfs
Also, don't delete them after that. This means that `brew postinstall`
becomes a way to easily reinstall configuration files for any formula
without needing any changes to any bottles or requiring a reinstall.
Hide these tokens to avoid malicious subprocesses e.g. sending them
over the network. Also, support using these tokens with environment
filtering and clear `HOMEBREW_PATH` from subprocesses to stop them
sniffing it. Finally, use `HOMEBREW_PATH` to detect Homebrew’s user’s
PATH for e.g. `brew doctor` etc.
Deprecate more methods. Internal APIs have been verified to be unused
elsewhere and removed. External APIs have had deprecation methods added.
Existing deprecations have been either upgraded to produce warnings or
no longer deprecated and the reasoning documented.
This is used to indicate a formula is a version of another formula.
This will be used to provide a consistent interface for older formulae
versions and replaces the use of `conflicts_with`.
If you specify a formula more than once or it exists in the Cellar with
an alias name and the main name (e.g. `qt` and `qt5`) you can see the
same formula showing up more than once. Instead, resolve these output
lists of formulae such that they are unique based on their `name`. This
doesn't use `full_name` as it's `name` that's use for the `Cellar`.
Return `opt_prefix` if it exists and `prefix` is not called from within
the same formula's `install` or `post_install` methods. Otherwise, fall
back to the existing functionality.
This avoids the need to use `opt_prefix` etc. everywhere and generally
means we don't expose an implementation detail (i.e. the full Cellar
path) to dependents that have a habit of hard-coding it.
