From 1ad0f550b10d4adfc2d3a22828fd264b1c5f15e1 Mon Sep 17 00:00:00 2001
From: Colin Dean <colindean@users.noreply.github.com>
Date: Thu, 13 Feb 2025 19:50:10 +0000
Subject: [PATCH] Adds post-installation steps to installation with extend
 version in tips

Inspired by @jvns' [post][1], I realized that I've had this problem on multiple teams, where someone missed the step at the end and didn't know how to recover. Typically, I've provided a version like what I've added to the Tips 'n' Tricks page so that I didn't have to think about what OS-arch pair my users are using.

I've tested the loader added to tips and tricks with both bash and zsh and it passes both shellcheck and shfmt in posix mode.

[1]: https://mastodon.social/@b0rk@jvns.ca/113997565198024027
---
 docs/Installation.md   | 22 ++++++++++++++++++++++
 docs/Tips-N'-Tricks.md | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/docs/Installation.md b/docs/Installation.md
index 959585a118..eeeb5817f5 100644
--- a/docs/Installation.md
+++ b/docs/Installation.md
@@ -93,6 +93,28 @@ Make sure you avoid installing into:
 
 Create a Homebrew installation wherever you extract the tarball. Whichever `brew` command is called is where the packages will be installed. You can use this as you see fit, e.g. to have a system set of libs in the default prefix and tweaked formulae for development in `~/homebrew`.
 
+## Post-installation steps
+
+Before completing installation, Homebrew installer will provide some required "Next steps" instructions.
+These instructions configure your shell to evaluate the output of `brew shellenv`,
+which will load `brew` into your shell environment for use.
+
+While it's difficult to document the precise path for every shell,
+typically, what follows must be in your shell's `rc` or `profile` file:
+
+```sh
+eval "${HOMEBREW_PREFIX}/bin/brew shellenv)"
+```
+
+where `${HOMEBREW_PREFIX}` is the Homebrew installation directory.
+Replace this with the installation directory on your system.
+
+For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/deacfa6a6e62e5f4002baf9e1fac7a96e9aa5d41/install.sh#L1072-L1088)
+to see how the installer constructs the path it recommends.
+
+See [Tips N' Tricks > Loading Homebrew from the same dotfiles on different operating systems](Tips-N'-Tricks.md#Loading-Homebrew-from-the-same-dotfiles-on-different-operating-systems)
+for another way to handle this across multiple operating systems.
+
 ## Uninstallation
 
 Uninstallation is documented in the [FAQ](FAQ.md#how-do-i-uninstall-homebrew).
diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md
index 85dde92c86..9606d37b0e 100644
--- a/docs/Tips-N'-Tricks.md
+++ b/docs/Tips-N'-Tricks.md
@@ -140,3 +140,42 @@ export HOMEBREW_ARTIFACT_DOMAIN=https://artifacts.example.com/artifactory/homebr
 export HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK=1
 export HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN="$(printf 'anonymous:' | base64)"
 ```
+
+## Loading Homebrew from the same dotfiles on different operating systems
+
+Some users may want to use the same shell initialization files on macOS and Linux.
+Use this to detect the likely Homebrew installation directory and load Homebrew when it's found.
+You may need to adapt this to your particular shell or other particulars of your environment.
+
+```sh
+# Execute only if brew isn't already available.
+if ! [ -x "$(command -v brew)" ]; then
+  OS="$(uname)"
+  UNAME_MACHINE="$(uname -m)"
+  if [ "${OS}" = "Linux" ]; then
+    # Linux
+    HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
+  elif [ "${OS}" = "Darwin" ]; then
+    if [ "${UNAME_MACHINE}" = "arm64" ]; then
+      # M-series ARM64 macOS
+      HOMEBREW_PREFIX="/opt/homebrew"
+    else
+      # Intel macOS
+      HOMEBREW_PREFIX="/usr/local"
+    fi
+  fi
+
+  if [ -d "${HOMEBREW_PREFIX}" ]; then
+    BREW_BIN="${HOMEBREW_PREFIX}/bin/brew"
+    if [ -x "${BREW_BIN}" ]; then
+      eval "\$(${BREW_BIN} shellenv)"
+    else
+      >&2 printf "Homebrew possibly found at %s but %s is not executable. Check the permissions.\n" "${HOMEBREW_PREFIX}" "${BREW_BIN}"
+    fi
+  else
+    >&2 printf "Homebrew not found where expected in %s on %s %s\n" "${HOMEBREW_PREFIX}" "${OS}" "${UNAME_MACHINE}"
+    >&2 printf "Double-check that it's installed or run the following command to install it\n\n\t%s\n" \
+      '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
+  fi
+fi
+```