Common Homebrew issues 🍻

Question

Common Homebrew issues 🍻

jthegedus opened this issue 4 years ago · 27 comments

Background information and why this issue exists

Background

We regularly see issues raised by Homebrew users where the solution is a missing installation step. I believe this is due to the flow Homebrew users follow which does not include the documentation site:

hear about asdf
install via Homebrew as they do other tools on their system
try using asdf and it does not work
go to GitHub and search/raise an Issue

This is understandable since few Homebrew tools require additional steps, though not considered a caveat to installing asdf via Homebrew and so we're unable to use the Homebrew post-install hook to direct users to the documentation site - see Homebrew/homebrew-core#54315

Additionally, the asdf core team do not want to edit your Shell configurations with a curl | bash install script as used in tools like ZSH or nvm. It is a choice, and it comes with pros and cons.

Solution

Ideally, we would use the aforementioned post-install log from Homebrew to direct users to complete the setup via our Documentation site. Short of this, we must capture users where they end up, GitHub Issues, before they raise an issue and direct them to the documentation site.

After brew install asdf asdf must be added to your Shell.

The documentation asdf-vm.com shows all instructions for your OS and Shell combination.

If we're missing some information or steps let us know and we'll fix ASAP, we want a smooth experience for all!

Common Homebrew Issues 🍻

These apply to macOS with Homebrew asdf installations.

Issue	Solution	Information	Original Issue/Sources
`asdf help` or `asdf <command>` does not work with Homebrew installation	✔ Ensure `asdf` is added to shell config	docs: add to shell	#394, #607
`with_shim_executable: command not found` after `brew upgrade asdf` and macOS BigSur upgrade	✔ Reinstall CLI Tools for XCode Tools and reinstall `asdf`	Homebrew macOS installation guide	#730 (comment) & Homebrew/brew#7803 (comment)
`command not found: complete`	✔ Do not use the OMZSH `asdf` plugin with Homebrew installation	OMZSH `asdf` plugin still relies upon the Bash completions. Use the Homebrew installed completions	#692 discusses `zcompdump` and `compinit` further. Help solving the OMZSH `asdf` plugin issue is welcome, with prior discussion here ohmyzsh/ohmyzsh#8837
`brew test <some-tool>` fails with `unknown command: <asdf-installed-tool>. Perhaps you have to reshim`	⚠️ Do not rely on `asdf` installed resources for Homebrew tests	Homebrew rewrites `$HOME` during `brew test` which breaks `asdf`. Workarounds reveal a deeper issue of `asdf` dependencies like `sed` not being available in the `brew test` environment. See original issue for more details	#794

If you identify a problem not covered here, please open a new Issue to discuss and attempt to resolve before we add it here!

Answer 1 · 2020-08-21T03:01:03.000Z

I am going to close this as it's not a new issue, but we will leave it pinned to improve visibility and direct people to the documentation site. If you identify a problem not covered here, please open a new Issue to discuss and attempt to resolve before we add it here!

Answer 2 · 2020-09-26T07:11:04.000Z

These links are all 404 at the moment, seems like most of the documentation URLs have been renamed from this scheme:

https://asdf-vm.com/#/core-manage-asdf-vm?id=add-to-your-shell

to this

https://asdf-vm.com/#/core-manage-asdf?id=add-to-your-shell

Answer 3 · 2020-09-27T03:41:27.000Z

Indeed, I was hoping to fix this before someone noticed ;) Thanks @actual-size I have fixed this here

Answer 4 · 2021-03-15T04:57:58.000Z

I added a fix here Homebrew/homebrew-core#73173 for the first issue.

Answer 5 · 2021-03-15T06:11:06.000Z

Homebrew/homebrew-core#54315 notwithstanding, a caveat that says something like

For asdf to work, add the following to your .zshrc:
  source #{prefix}/asdf.h

This seems to fit the requirement that caveats must be Homebrew-specific. (Indeed, this is what justifies many other similar caveats.)

Answer 6 · 2021-03-15T07:03:04.000Z

@carlocab I agree, but it was declined. Feel free to PR that change to Homebrew and open up a new discussion there.

Answer 7 · 2021-03-15T07:13:20.000Z

Are you sure?

Note that the PR I linked to (Homebrew/homebrew-core#54315) proposes a different change than what I suggested. That change is a caveat linking to the documentation, which isn't considered Homebrew-specific.

Answer 8 · 2021-03-15T07:26:32.000Z

The reason for the link to the docs being proposed is because we don't just have one Homebrew specific setup.

If I am on Ubuntu with Fish and using Linuxbrew, and you are on macOS with ZSH using Homebrew, how will we show the correct config for each of use. The Shell configs etc are different, something the docs is good for helping people identify with the drop-down menus.

Some people are still on OXS with Bash and so it would be different again.

I am hopeful of the change @seivan proposed.

Answer 9 · 2021-03-15T07:37:27.000Z

Zsh is the default shell on macOS, so those are the users who probably need the most help with configuration/are least likely to read the docs. Essentially the same instructions seem to work for bash.

But, ok, up to you. Was just trying to suggest a caveat that likely would get accepted. I figured that was better than none at all.

Answer 10 · 2021-03-15T07:47:37.000Z

I am open to the suggestion and further discussion. I am only one user of asdf, if you PR your idea, a discussion can be had there about the efficacy.

My personal opinion is if we add your proposition, it may resolve the issue for the fraction of users who do not read the docs, but will definitely suggest the wrong thing (however almost correct) to another set of users.

I ere on the side that we should encourage people to read the docs and become familiar with their systems.

Answer 11 · 2021-03-15T19:48:42.000Z

You're right that it'll be the right advice for some, but the wrong advice for others. However, it'll be a signal to those for whom it's the wrong advice that they should be reading the docs to get the right one. At the moment, they don't get this at all.

Anyway, I'm not even an asdf user. Just a Homebrew maintainer trying to find a solution that works for us both. If you're not keen on pursuing one, then I'm happy to leave this be.

Answer 12 · 2021-03-15T21:44:56.000Z

I am very keen to find a solution and happy to have your input.

Answer 13 · 2021-03-15T22:00:34.000Z

Great. I should mention that this is just my personal opinion, so another maintainer may disagree (but I hope not), but I think a caveat that looks like this would be acceptable in Homebrew:

For asdf to work, add the following line at the end of your .zshrc or .bash_profile:
  source #{opt_prefix}/asdf.sh

If you use fish, you need to add this at the end of config.fish:
  source #{opt_prefix}/asdf.fish

It may not cover everything, but it covers enough information to be useful to (I think) the vast majority of your users. And, as mentioned, it's a signal that there's more configuration needed, so it may help in preventing duplicate issues from being opened.

Answer 14 · 2021-03-16T08:15:44.000Z

@carlocab That solution looks fine to me. Is {opt_prefix} precomputed or computed each shell execution?

Answer 15 · 2021-03-16T08:25:23.000Z

opt_prefix should be something like /usr/local/opt/asdf. The /usr/local part will be different if a user has Homebrew installed somewhere else (e.g. /opt/homebrew on ARM).

Do you want to open a PR? It'll be easier to merge if I don't open one.

Answer 16 · 2021-03-16T08:38:26.000Z

I would like to soon, time permitting.

Answer 17 · 2021-03-16T15:29:13.000Z

I don't understand why that is still a discussion, the current installation of Homebrew is broken and causes issues like this #892 because the instructions are unclear. Those instructions derive from a faulty Homebrew formula and installation.

Don't ask people to source some file that modifies their $PATH instead tell them to just add the shim folder there.
export PATH="$HOME/.asdf/shims:$PATH"

Even worse the script also adds the asdf executable into their path as well, which is unnecessary, it's already there.

ASDF_BIN="${ASDF_DIR}/bin"
ASDF_USER_SHIMS="${ASDF_DATA_DIR:-$HOME/.asdf}/shims"
[[ ":$PATH:" == *":${ASDF_BIN}:"* ]] && PATH="${PATH//$ASDF_BIN:/}"
[[ ":$PATH:" == *":${ASDF_USER_SHIMS}:"* ]] && PATH="${PATH//$ASDF_USER_SHIMS:/}"

Whatever checks it does, doesn't seem to work, it adds it anyway.

Answer 18 · 2021-03-16T17:40:11.000Z

Don't ask people to source some file that modifies their $PATH instead tell them to just add the shim folder there.
export PATH="$HOME/.asdf/shims:$PATH"

This would no longer be a Homebrew-specific recommendation and would be rejected as a caveat for the reasons outlined in Homebrew/homebrew-core#54315. And we would be back where we started, where users file issues because they didn't read the docs.

Answer 19 · 2021-03-16T18:27:50.000Z

This would no longer be a Homebrew-specific recommendation and would be rejected as a caveat for the reasons outlined in Homebrew/homebrew-core#54315. And we would be back where we started, where users file issues because they didn't read the docs.

I didn't say it's a caveat, I'm saying the caveat would be redundant if you fixed your installation.
People can't even run $ asdf or do $ asdf help when they install it, you could technically just put it in $ asdf help.
Focus on fixing the installation first.

Answer 20 · 2021-03-16T18:30:28.000Z

Well, you were a little unclear about what

tell them to just add the shim folder there

meant exactly, as the discussion was about communicating things to users via caveats. But, fair enough, I'm happy with whatever you think works.

Answer 21 · 2021-03-16T20:49:13.000Z

@seivan I think @carlocab proposition is a good stopgap until your proposed changes in the Homebrew installation are understood and merged.

We need to flesh out the migration for the inevitable influx of Homebrew users who's setups will break and need manual intervention when they update from current Homebrew to your proposed update. I understand you have written about some of these (I am yet to re-read all the discussion on the PR and fully understand), but I would think we would need to update our docs here / create an issue to capture these users when they search for answers as to why their system worked and now does not.

@carlocab could we use caveats to warn users about changes from one version of the formulae to another? Is there a mechanism within Homebrew we can use to communicate this breaking change?

10k installs via Homebrew in the last 30 days isn't much on the scale of Homebrew usage, but it's a lot of users setups to break, and I would like to have something in place before the Homebrew change goes out

Answer 22 · 2021-03-16T20:53:48.000Z

could we use caveats to warn users about changes from one version of the formulae to another?

Caveats aren't really meant to change regularly, so I think other maintainers may find using them to communicate breaking changes not acceptable.

If it's a one-time thing, however, that might be fine. Note that the caveat would probably have to be crafted as if it were going to become a permanent fixture in the formula (as it's likely to stay there for a very long time).

Answer 23 · 2021-03-16T21:44:24.000Z

@seivan I think @carlocab proposition is a good stopgap until your proposed changes in the Homebrew installation are understood and merged.

Again, it proposes something erroneous based on a faulty installation. You've had a discussion since August about how you can justify the caveat because Homebrew requires it be tied to the quirks of the package manager, when in reality its tied to the faulty installation and not Homebrew's fault.

I totally see why they have that requirement, because everyone would otherwise just ship something broken and demand to shove text into the caveat to justify it.

We need to flesh out the migration for the inevitable influx of Homebrew users who's setups will break and need manual intervention when they update from current Homebrew to your proposed update.

That's most unfortunate, but it needs to be done.

I understand you have written about some of these (I am yet to re-read all the discussion on the PR and fully understand), but I would think we would need to update our docs here / create an issue to capture these users when they search for answers as to why their system worked and now does not.

I can't speak for Fish, but for Zsh and Bash it's pretty straight forward.

Add the shims path to their .zshenv, .profile, or .bashrc

export PATH="$HOME/.asdf/shims:$PATH"

$ rm -rf ~/.asdf/shims; asdf reshim

Could potentially skip step 2 if #893 was merged and released a new version at the same time, but I don't fully understand the consequences of that, something you I'm guessing would know better of.

I took the liberty of adding asdf reshim as a post installation hook, but it doesn't really do anything know until it gets fixed.

Current implementation of $ asdf reshim doesn't properly check if the asdf path is correct, though my advice is always rewrite the shims instead of whatever is going on now doesn't justify the issues it causes when the asdf binary moves for some reason.

The Homebrew upgrade will change the path, so the shims will be pointing to nothing and $ asdf reshim doesn't manage that, hence delete and $ asdf reshim.

Answer 24 · 2021-09-30T21:10:48.000Z

The biggest issue with the documentation is probably too obvious, but after you edit your .bash_profile (or whatever shell), you need to resource it, otherwise the installations will all fail on reshim.

Answer 25 · 2021-10-01T05:01:36.000Z

The biggest issue with the documentation is probably too obvious, but after you edit your .bash_profile (or whatever shell), you need to resource it, otherwise the installations will all fail on reshim.

The docs currently state in the 3. install asdf section:

Restart your shell so that PATH changes take effect. Opening a new terminal tab will usually do it.

Is that not enough information? We could include the word "source", but this isn't the root cause of this issue IMO

Answer 26 · 2022-04-22T22:29:33.000Z

Brew just updated asdf for me and broke my commits in VSCode with Husky.

I had to run rm -rf ~/.asdf/shims; asdf reshim and now it is back to working.

I know there's another topic on this where I provide a solution, but now I cannot find it 😂 , but I landed here and it's stickied so I'll leave this answer here 🤪 (maybe for myself next time & others).

Answer 27 · 2022-06-23T20:25:50.000Z

Brew just updated asdf for me and broke my commits in VSCode with Husky.

I had to run rm -rf ~/.asdf/shims; asdf reshim and now it is back to working.

I know there's another topic on this where I provide a solution, but now I cannot find it 😂 , but I landed here and it's stickied so I'll leave this answer here 🤪 (maybe for myself next time & others).

PERFECT!