Common Homebrew issues 🍻

[jthegedus]

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:

1. hear about asdf
2. install via Homebrew as they do other tools on their system
3. try using asdf and it does not work
4. 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!

[jthegedus]

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!

[r-tae]

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

[jthegedus]

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

[seivan]

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

[carlocab]

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.)

[jthegedus]

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

[carlocab]

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.

[jthegedus]

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.

[carlocab]

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.

[jthegedus]

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.

[carlocab]

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.

[jthegedus]

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

[carlocab]

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.

[jthegedus]

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

[carlocab]

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.

[jthegedus]

I would like to soon, time permitting.

[seivan]

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.

[carlocab]

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.

[seivan]

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.

[carlocab]

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.

[jthegedus]

@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

[carlocab]

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).

[seivan]

@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.

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

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

2. $ 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.

[richtong]

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.

[jthegedus]

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

[ctsstc]

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).

[rogeriomq]

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!