From eba4121bf19b529f0509747038e1227e4a9d7b58 Mon Sep 17 00:00:00 2001 From: Colin Dean Date: Thu, 15 Feb 2024 17:06:14 -0500 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Patrick Linnane --- docs/Common-Issues.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md index eed0b43f12..d6442eb472 100644 --- a/docs/Common-Issues.md +++ b/docs/Common-Issues.md @@ -136,20 +136,19 @@ brew upgrade ## Unintentional dual Homebrew installations When using tools such as Apple's _Migration Assistant_ (MA), it's possible to have two Homebrew installations unintentionally. -This most commonly results in MA copying `/usr/local` and `/Applications` from an Intel-based Mac to these same paths on an AS-based Mac. -This is problematic because `/Applications` may contain x86_64-only apps, especially common terminal emulators such as iTerm2. +This most commonly results in MA copying `/usr/local` and `/Applications` from an Intel-based Mac to these same paths on an Apple Silicon-based Mac. +This is problematic because `/Applications` may contain x86_64-only apps. Using an x86_64 terminal emulator will cause the shell to use the `/usr/local` installation of Homebrew instead of a new installation in `/opt/homebrew`, which is the correct path for an arm64 Homebrew installation on macOS. -Continuing with this setup will cause problems eventually, so it's best to migrate your Homebrew installation. -Or, really, reinstall it. +Continuing with this setup may eventually cause problems, so it's best to migrate your Homebrew installation. Follow these steps to do this. 1. Run `arch -x86_64 /usr/local/bin/brew bundle dump --global` to dump your current installed formulae list to `~/.Brewfile`. 1. Review the contents of `~/.Brewfile` to remove things you no longer want to have installed. 1. Verify that your terminal emulator is running in arm64 mode by checking that the output of `arch` is `arm64`. * If it is not, use a different terminal emulator, such as Apple's Terminal.app, that will run in `arm64` mode. -1. [Reinstall Homebrew](https://brew.sh/) under the correct prefix (`/opt/homebrew`), +1. Reinstall Homebrew under the correct prefix (`/opt/homebrew`), which will happen by default when the terminal is running in arm64 mode. * **Follow the _Next Steps_ instructions** listed at the end of the installation process; @@ -159,7 +158,7 @@ Follow these steps to do this. Note that if it's been a long time since you ran `brew upgrade`, you may encounter some package renaming that will require manual resolution. Expect errors. Expect to spend some time [searching Homebrew's formulae and cask list](https://formulae.brew.sh/) -for replacements for deprecated, disabled, and just plain _missing_ formulae. +for replacements for deprecated, disabled, or removed formulae. Once you are satisfied with the state of your new `/opt/homebrew` Homebrew installation, you can uninstall the old `/usr/local` installation with these next steps.