FAQ.md: Suggested improvements #20335
Conversation
Added mention of some environment variables to already mentioned command line examples. Expanded section for dealing with keg-only libraries by providing a c'n'p-able configuration snippets that should fit most use cases. Fix some formatting inconsistencies (like disable being written like bolded in one example but not for another within the same section of the FAQ right after each other. Mention disabling automatic updates and upgrades using environment variables. Add note about a bunch of packages requiring sudo despite it being mentioned as no-go right now. Mention manual alternative of just removing the xattr property for unblocking "unknown developer" applications. So that users know how this protection feature works. Add mention of HOMEBREW_UPGRADE_GREEDY where currently only the CLI version is mentioned.
| @@ -25,7 +25,11 @@ Upgrade everything with: | |||
|
|
|||
| brew upgrade | |||
|
|
|||
| Or upgrade a specific formula with: | |||
| Upgrade everything __including__ casks with `auto_update: true` and `version :latest` | |||
There was a problem hiding this comment.
Don't think the various __ usage added here aids readability and it's inconsistent with existing style
| To __disable__ these automatic upgrades: | ||
|
|
||
| export HOMEBREW_NO_INSTALL_UPGRADE=1 | ||
|
|
||
| Additionally there is also the automatic update of all package definitions (formulae) and Homebrew itself (e.g. automatic `brew update`) when certain actions like `brew upgrade`, `brew install`, or `brew tap` are run. This may look like brew is updating other things but doesn't change the installed versions of packages. | ||
|
|
||
| To __disable__ these automatic updates of the package definitions and Homebrew itself: | ||
|
|
||
| export HOMEBREW_NO_AUTO_UPDATE=1 |
There was a problem hiding this comment.
Would rather not recommend these here. They break things.
There was a problem hiding this comment.
Will think about rewording it. It is a quite common question and I think it is better people look here than in some random Gemini generated google response so I'd kinda like to have it in here.
I'm open to suggestions, I'm using them as I work mostly on Linux systems and there you also have to invoke it as a separate command. It's always quite unexpected and I always Ctrl+C immediately as I think I accidentally approved the dependency resolver to either install the entire world or to remove the entire system...
There was a problem hiding this comment.
so I'd kinda like to have it in here.
I would like to not have it here, please remove it.
| @@ -124,6 +138,8 @@ Did you `chown root /Applications/TextMate.app`? Probably not. So is it that imp | |||
|
|
|||
| If you need to run Homebrew in a multi-user environment, consider creating a separate user account specifically for use of Homebrew. | |||
|
|
|||
| Some formulae or casks however may require elevation using `sudo` and therefore the installation or upgrade of these may block and ask for your password, fingerprint, or smartcard pin to authorize. This happens for apps like e.g. Microsoft Teams that install things like an additional audio device or similar. | |||
There was a problem hiding this comment.
No formalae use sudo. Just say credentials and don't mention Teams specifically.
There was a problem hiding this comment.
You're right they're all casks. Should have looked more closely at the search results over in the homebrew-core repo I had earlier.
However I could have sworn that I've seen some formulae requesting sudo as well...
Also why I used the Teams example is I wanted to show why it may be desired and unavoidable. E.g. for installing a pseudo device driver. Will think about how to reword this as well.
| A kinda generic to use libraries from "keg-only" packages like e.g. zlib would be: | ||
|
|
||
| # set temporary variables: | ||
| _brew_package_name="zlib" | ||
| _brew_package_prefix="$(brew --prefix $_brew_package_name)" | ||
| # For the C and C++ linker (lld): | ||
| export LDFLAGS="-L$_brew_package_prefix/lib $LDFLAGS" | ||
| # For the C and C++ pre-processor: | ||
| export CPPFLAGS="-I$_brew_package_prefix/include $CPPFLAGS" | ||
| # For the Rust: | ||
| export RUSTFLAGS="-L$_brew_package_prefix/lib $RUSTFLAGS" | ||
| # For pkg-config: | ||
| export PKG_CONFIG_PATH="$_brew_package_prefix/lib/pkgconfig${PKG_CONFIG_PATH:+:${PKG_CONFIG_PATH}}" | ||
| export PKG_CONFIG_LIBDIR="$_brew_package_prefix/lib/pkgconfig${PKG_CONFIG_LIBDIR:+:${PKG_CONFIG_LIBDIR}}" | ||
| # If the package also contains binaries uncomment the following line: | ||
| #export PATH="$_brew_package_prefix/bin:/homebrew/sbin:/usr/local/sbin${PATH:+:${PATH}}" | ||
| # unset temporary variables again | ||
| unset _brew_package_name _brew_package_prefix | ||
|
|
||
| **NOTE**: The above example is written in a way that allows you to put multiple copies of it into your .zshrc (or .bashrc) and only having to | ||
| change the package name within the first line without them overwriting each other. | ||
| Similarly it won't overwrite any existing ones you may already have. | ||
| All of them will be merged together properly in the end. | ||
| This way your file stays neath and tidy and you'll be able to easily find the lines for a specific package should you want to remove them later on again. | ||
|
|
There was a problem hiding this comment.
Remove all of this, this is overkill
There was a problem hiding this comment.
Hmm, either this or some kind of command line flag to auto generate it like e.g. PIPX does.
I wrote these commands already generic enough that we could do that as well and a --create-shell-profile-env-overwrite.
I'd like to have something here at least. Especially for non-programmer managing to identify the correct Environment variable to set so that some script works on macOS can be quite a challenging task...
There was a problem hiding this comment.
I'd like to have something here at least.
Please remove it for now.
| For consolle application, granting your terminal emulator (e.g. iTerm2.app) the "Developer Tools" permission can also help as this allows it to run untrusted applications. **Note**: It is not recommended to do this for the builtin macOS Terminal app, as this may also allow other application and scripts to bypass this protection. | ||
|
|
||
| Finally, of course it is also possible to remove the `com.apple.quarantine`-flag from the affected files using tools like `xattr` manually. | ||
|
|
There was a problem hiding this comment.
Let's not recommend this please
There was a problem hiding this comment.
It's not a recommendation. I intentionally didn't write the actual command. My goal was to explain how this works. Maybe could be shortened or reworded though.
There was a problem hiding this comment.
Anything implicitly in the official documentation can be interpreted as a recommendation. Please remove.
There was a problem hiding this comment.
While I totally agree this shouldn't be in the official docs, it is worth noting that there are lots of new formula doing this since the Goreleaser Formula → cask change (https://github.com/orgs/goreleaser/discussions/5563#discussioncomment-13368648)
Added mention of some environment variables to already mentioned command line examples.
Expanded section for dealing with keg-only libraries by providing a c'n'p-able configuration snippets that should fit most use cases.
Fix some formatting inconsistencies (like disable being written like bolded in one example but not for another within the same section of the FAQ right after each other.
Mention disabling automatic updates and upgrades using environment variables.
Add note about a bunch of packages requiring sudo despite it being mentioned as no-go right now.
Mention manual alternative of just removing the xattr property for unblocking "unknown developer" applications. So that users know how this protection feature works.
Add mention of HOMEBREW_UPGRADE_GREEDY where currently only the CLI version is mentioned.
brew stylewith your changes locally?brew typecheckwith your changes locally?brew testswith your changes locally?