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