README lacks any uninstall options documentation

[dolmen]

What you were trying to do (and why)

New Mac with M2 chip. I did use the Apple Migration Assistant to migrate everything from my x86 Mac. Including Homebrew.

I have not yet installed Rosetta as my aim is to have native binaries.

Of course the x86 Homebrew didn't work on M2, so wanted to migrate, reinstalling the list of installed packages with amd64 binaries.

What happened (include command output)

After the Migration Assistant work:

• brew didn't work (expected): bad CPU type for the ruby binary
• The uninstaller command in the README from this repo didn't work (unexpected): it tried to uninstall Homebrew from /opt/homebrew while I needed to uninstall the x86 one from /usr/local. The README has no information to clean /usr/local.
• Installer succeeded but wasn't in PATH (because the amd64 brew requires to add /opt/homebrew), so the brew command was still using ruby from /usr/local.

I have been able to reinstall Homebrew by removing (rm) /usr/local/Homebrew and adding eval "$(/opt/homebrew/bin/brew shellenv)" to my shell profile. But I have still dangling symlinks. I'll try to rebuild my package list from the links in /usr/local/bin (ls -l /usr/local/bin | grep Cellar).

After successful install:

$ brew config
brew config
HOMEBREW_VERSION: 4.1.19
ORIGIN: https://github.com/Homebrew/brew
HEAD: 7f745d04d90eaec76c8d5830d6ce6a0d7db888b3
Last commit: 2 days ago
Core tap JSON: 08 Nov 10:03 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_MAKE_JOBS: 8
Homebrew Ruby: 2.6.10 => /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby
CPU: octa-core 64-bit arm_blizzard_avalanche
Clang: 14.0.3 build 1403
Git: 2.39.2 => /Library/Developer/CommandLineTools/usr/bin/git
Curl: 7.88.1 => /usr/bin/curl
macOS: 13.4-arm64
CLT: 14.3.1.0.1.1683849156
Xcode: N/A
Rosetta 2: false

What you expected to happen

I understand that my case is a niche.

But I wanted to see in README at list some manual steps:

1. to export the list of packages installed with x86 brew
2. to cleanup /usr/local with a amd64 chip
3. to reinstall homebrew
4. remind me to do the .zshrc change required (that wasn't required on x86)
5. to reinstall package using list from 1.

Maybe all this should be listed in a dedicated page, but I expect at least a link from the README here and from https://docs.brew.sh/Installation.

[dolmen]

To recover a list of the Homebrew packages which installed a binary into /usr/local/bin:

$ ls -l /usr/local/bin | sed -n '/Cellar/ s!^.*/Cellar/\([^/]*\)/.*!\1!p' | sort -u

Edit: better

$ ls /usr/local/Cellar
$ ls /usr/local/Caskroom

[SMillerDev]

The recommended way to keep packages the same between macs is using brew bundle, which makes all steps redundant.

[iMichka]

Is there still something actionable on our side? Is a documentation update still necessary?

It's the first complaint we get about that lack of documentation (thanks by the way :)), so I am wondering how much effort we should put into this.

[dolmen]

I think that the fact that the uninstaller doesn't work in the arch migration case is very confusing. When you have a broken Homebrew install, the last recourse is to cleanup everything and restart from fresh, but in the migration case that doesn't work as the uninstaller is locked on the current system arch. This failure is adding insult to injury.

I know that even if someone was writing a migration tool (I would be tempted to do it for my own usage, but it is just short term), no one would be interested in maintaining it, so that would only lead to more pain for users.

So, it would be appreciated to have:

• tooling to cleanup Homebrew whether it is installed into /usr/local/bin or /opt/homebrew independently of the native arch (that might be just shell commands documented in the README)
• instructions in README or FAQ to document that tooling and link to the use cases (What to do in case of "Bad CPU type in executable"?)

With some guidance about where to submit changes and in which format, I could submit some of the changes myself.

[SMillerDev]

I think that the fact that the uninstaller doesn't work in the arch migration case is very confusing.

By default it uninstalls the default Homebrew, https://github.com/Homebrew/install?tab=readme-ov-file#uninstall-homebrew suggests running it with --help though. That shows how to "cleanup Homebrew whether it is installed into /usr/local/bin or /opt/homebrew independently of the native arch"

[MikeMcQuaid]

By default it uninstalls the default Homebrew, https://github.com/Homebrew/install?tab=readme-ov-file#uninstall-homebrew suggests running it with --help though. That shows how to "cleanup Homebrew whether it is installed into /usr/local/bin or /opt/homebrew independently of the native arch"

I could see an argument that some of the uninstall options could be spelled out in the README so am rescoping this issue to that goal.

[zhisme]

I have run on the same issue.

rm -rf /usr/local/bin/brew
rm -rf /opt/homebrew/*
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

and then reinstall and run

eval "$(/opt/homebrew/bin/brew shellenv)"

and this requires me to run the command above each time I open new terminal session, should I modify my .zshrc with some PATH modification or what is right way?

[osalbahr]

[…], should I modify my .zshrc with some PATH modification or what is right way?

The recommended way is to add eval "$(/opt/homebrew/bin/brew shellenv)" to your ~/.zshrc.

For reference:

install/install.sh

Lines 1044 to 1046 in 3d2b88b

	- Run these two commands in your terminal to add Homebrew to your ${tty_bold}PATH${tty_reset}:
	(echo; echo 'eval "\$(${HOMEBREW_PREFIX}/bin/brew shellenv)"') >> ${shell_rcfile}
	eval "\$(${HOMEBREW_PREFIX}/bin/brew shellenv)"