Update docs for Homebrew (#189)

* Update docs for Homebrew * Extend title underline * Add notes for git-config insteadOf
ustclug · Oct 14, 2021 · 1f1bfe6 · 1f1bfe6
1 parent b0bc126
commit 1f1bfe6
Show file tree

Hide file tree

Showing 7 changed files with 114 additions and 58 deletions.
diff --git a/source/brew.git.rst b/source/brew.git.rst
@@ -19,45 +19,59 @@ Homebrew 源代码仓库
 
 ::
 
-    cd "$(brew --repo)"
-    git remote set-url origin https://mirrors.ustc.edu.cn/brew.git
+    export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
+    brew update
+
+.. note::
+    若用户设置了环境变量 ``HOMEBREW_BREW_GIT_REMOTE``，则每次运行 ``brew update`` 时将会自动设置远程。
+    推荐用户将环境变量 ``HOMEBREW_BREW_GIT_REMOTE`` 加入 shell 的 profile 设置中。
+
+    ::
+
+        # 对于 bash 用户
+        echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"' >> ~/.bash_profile
+
+        # 对于 zsh 用户
+        echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"' >> ~/.zshrc
 
 重置为官方地址：
 
 ::
 
-    cd "$(brew --repo)"
-    git remote set-url origin https://github.com/Homebrew/brew.git
+    unset HOMEBREW_BREW_GIT_REMOTE
+    git -C "$(brew --repo)" remote set-url origin https://github.com/Homebrew/brew
 
 .. note::
-    初次安装 homebrew/linuxbrew 时，如果无法下载安装脚本，
-    可以使用 `jsDelivr CDN <https://cdn.jsdelivr.net/gh/Homebrew/install@master/install.sh>`_ 
-    下载 ``install.sh``，然后将脚本中的 ``HOMEBREW_BREW_GIT_REMOTE`` 
-    变量对应的值修改为 ``https://mirrors.ustc.edu.cn/brew.git``。
-
-    如有需要，脚本中的 ``HOMEBREW_CORE_GIT_REMOTE`` 变量可以修改为 :doc:`homebrew-core.git` 
-    (macOS) 或 :doc:`linuxbrew-core.git` (Linux) 中对应的地址，以加快核心软件仓库索引下载的速度。
+    重置回默认远程后，用户应该删除 shell 的 profile 设置中的环境变量 ``HOMEBREW_BREW_GIT_REMOTE`` 以免运行 ``brew update`` 时远程再次被更换。
 
-    由于 brew 安装脚本此前多次修改相关的变量名，也可以参考以下命令，让 Git 将脚本访问的所有 GitHub 的 URL 替换为科大源:
+    若之前使用的 ``git config url.<URL>.insteadOf URL`` 的方式设置的镜像，请手动删除 ``config`` 文件（一般为 ``~/.gitconfig`` 或仓库目录下的 ``.git/config``）中的对应字段。
 
-    ::
+使用科大源安装 Homebrew / Linuxbrew
+=====================================
 
-        git config --global url."https://mirrors.ustc.edu.cn/homebrew-core.git".insteadOf "https://github.com/Homebrew/homebrew-core"
-        git config --global url."https://mirrors.ustc.edu.cn/linuxbrew-core.git".insteadOf "https://github.com/Homebrew/linuxbrew-core"
-        git config --global url."https://mirrors.ustc.edu.cn/brew.git".insteadOf "https://github.com/Homebrew/brew"
-        chmod +x install.sh
-        # macOS
-        HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles ./install.sh
-        # Linux
-        HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/linuxbrew-bottles ./install.sh
+首先在命令行运行如下几条命令设置环境变量：
 
-    初次安装完成后，若想从 GitHub 官方仓库获取后续更新，需要恢复上面步骤中修改过的 ``git config``：
+::
+
+    if [[ "$(uname -s)" == "Linux" ]]; then BREW_TYPE="linuxbrew"; else BREW_TYPE="homebrew"; fi
+    export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
+    export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/${BREW_TYPE}-core.git"
+    export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/${BREW_TYPE}-bottles"
+
+之后在命令行运行 Homebrew 安装脚本：
+
+::
+
+    /bin/bash -c "$(curl -fsSL https://github.com/Homebrew/install/raw/HEAD/install.sh)"
+
+.. note::
+    初次安装 Homebrew / Linuxbrew 时，如果无法下载安装脚本，
+    可以使用 `jsDelivr CDN <https://cdn.jsdelivr.net/gh/Homebrew/install@HEAD/install.sh>`_
+    下载 ``install.sh``。
 
     ::
 
-        git config --global --unset url."https://mirrors.ustc.edu.cn/homebrew-core.git".insteadOf
-        git config --global --unset url."https://mirrors.ustc.edu.cn/linuxbrew-core.git".insteadOf
-        git config --global --unset url."https://mirrors.ustc.edu.cn/brew.git".insteadOf
+        /bin/bash -c "$(curl -fsSL https://cdn.jsdelivr.net/gh/Homebrew/install@HEAD/install.sh)"
 
 相关镜像
 ========

diff --git a/source/homebrew-bottles.rst b/source/homebrew-bottles.rst
@@ -20,21 +20,23 @@ Homebrew 预编译二进制软件包
 使用说明
 ========
 
-请在运行 brew 前设置环境变量 ``HOMEBREW_BOTTLE_DOMAIN`` ，值为 ``https://mirrors.ustc.edu.cn/homebrew-bottles`` 。
+请在运行 ``brew`` 前设置环境变量 ``HOMEBREW_BOTTLE_DOMAIN``，值为 ``https://mirrors.ustc.edu.cn/homebrew-bottles`` 。
 
-对于 bash 用户：
+临时替换：
 
 ::
 
-    echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles' >> ~/.bash_profile
-    source ~/.bash_profile
+    export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
 
-对于 zsh 用户：
+永久替换：
 
 ::
 
-    echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles' >> ~/.zshrc
-    source ~/.zshrc
+    # 对于 bash 用户
+    echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"' >> ~/.bash_profile
+
+    # 对于 zsh 用户
+    echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"' >> ~/.zshrc
 
 相关镜像
 ========

diff --git a/source/homebrew-cask-versions.git.rst b/source/homebrew-cask-versions.git.rst
@@ -15,19 +15,23 @@ Homebrew cask 其他版本 (alternative versions) 软件仓库，提供使用人
 使用说明
 ========
 
-替换为 USTC 镜像：
+使用 USTC 镜像安装：
 
 ::
 
-    cd "$(brew --repo)"/Library/Taps/homebrew/homebrew-cask-versions
-    git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask-versions.git
+    brew tap --force-auto-update homebrew/cask-versions https://mirrors.ustc.edu.cn/homebrew-cask-versions.git
+
+如果已安装，则使用如下命令将远程替换为 USTC 镜像：
+
+::
+
+    git -C "$(brew --repo homebrew/cask-versions)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask-versions.git
 
 重置为官方地址：
 
 ::
 
-    cd "$(brew --repo)"/Library/Taps/homebrew/homebrew-cask-versions
-    git remote set-url origin https://github.com/Homebrew/homebrew-cask-versions.git
+    git -C "$(brew --repo homebrew/cask-versions)" remote set-url origin https://github.com/Homebrew/homebrew-cask-versions
 
 
 相关镜像

diff --git a/source/homebrew-cask.git.rst b/source/homebrew-cask.git.rst
@@ -15,20 +15,24 @@ Homebrew cask 软件仓库，提供 macOS 应用和大型二进制文件
 使用说明
 ========
 
-替换为 USTC 镜像：
+使用 USTC 镜像安装：
 
 ::
 
-    cd "$(brew --repo)"/Library/Taps/homebrew/homebrew-cask
-    git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git
+    brew tap --force-auto-update homebrew/cask https://mirrors.ustc.edu.cn/homebrew-cask.git
+
+如果已安装，则使用如下命令将远程替换为 USTC 镜像：
+
+::
+
+    git -C "$(brew --repo homebrew/cask)" remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git
 
 重置为官方地址：
 
 ::
 
-    cd "$(brew --repo)"/Library/Taps/homebrew/homebrew-cask
-    git remote set-url origin https://github.com/Homebrew/homebrew-cask
-    
+    git -C "$(brew --repo homebrew/cask)" remote set-url origin https://github.com/Homebrew/homebrew-cask
+
 .. note::
     Caskroom 的 Git 地址在 2018 年 5 月 25 日从 https://github.com/caskroom/homebrew-cask 迁移到了
     https://github.com/Homebrew/homebrew-cask 。

diff --git a/source/homebrew-core.git.rst b/source/homebrew-core.git.rst
@@ -19,15 +19,30 @@ Homebrew 核心软件仓库
 
 ::
 
-    cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core"
-    git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git
+    export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
+    brew update
+
+.. note::
+    若用户设置了环境变量 ``HOMEBREW_CORE_GIT_REMOTE``，则每次运行 ``brew update`` 时将会自动设置远程。
+    推荐用户将环境变量 ``HOMEBREW_CORE_GIT_REMOTE`` 加入 shell 的 profile 设置中。
+
+    ::
+
+        # 对于 bash 用户
+        echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"' >> ~/.bash_profile
+
+        # 对于 zsh 用户
+        echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"' >> ~/.zshrc
 
 重置为官方地址：
 
 ::
 
-    cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core"
-    git remote set-url origin https://github.com/Homebrew/homebrew-core
+    unset HOMEBREW_CORE_GIT_REMOTE
+    git -C "$(brew --repo homebrew/core)" remote set-url origin https://github.com/Homebrew/homebrew-core
+
+.. note::
+    重置回默认远程后，用户应该删除 shell 的 profile 设置中的环境变量 ``HOMEBREW_CORE_GIT_REMOTE`` 以免运行 ``brew update`` 时远程再次被更换。
 
 相关镜像
 ========

diff --git a/source/linuxbrew-bottles.rst b/source/linuxbrew-bottles.rst
@@ -20,21 +20,23 @@ Linuxbrew 预编译二进制软件包
 使用说明
 ========
 
-请在运行 brew 前设置环境变量 ``HOMEBREW_BOTTLE_DOMAIN`` ，值为 ``https://mirrors.ustc.edu.cn/linuxbrew-bottles`` 。
+请在运行 ``brew`` 前设置环境变量 ``HOMEBREW_BOTTLE_DOMAIN``，值为 ``https://mirrors.ustc.edu.cn/linuxbrew-bottles`` 。
 
-对于 bash 用户：
+临时替换：
 
 ::
 
-    echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/linuxbrew-bottles' >> ~/.bash_profile
-    source ~/.bash_profile
+    export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/linuxbrew-bottles"
 
-对于 zsh 用户：
+永久替换：
 
 ::
 
-    echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/linuxbrew-bottles' >> ~/.zshrc
-    source ~/.zshrc
+    # 对于 bash 用户
+    echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/linuxbrew-bottles"' >> ~/.bash_profile
+
+    # 对于 zsh 用户
+    echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/linuxbrew-bottles"' >> ~/.zshrc
 
 相关镜像
 ========

diff --git a/source/linuxbrew-core.git.rst b/source/linuxbrew-core.git.rst
@@ -19,15 +19,30 @@ Linuxbrew 核心软件仓库
 
 ::
 
-    cd "$(brew --repo homebrew/core)"
-    git remote set-url origin https://mirrors.ustc.edu.cn/linuxbrew-core.git
+    export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/linuxbrew-core.git"
+    brew update
+
+.. note::
+    若用户设置了环境变量 ``HOMEBREW_CORE_GIT_REMOTE``，则每次运行 ``brew update`` 时将会自动设置远程。
+    推荐用户将环境变量 ``HOMEBREW_CORE_GIT_REMOTE`` 加入 shell 的 profile 设置中。
+
+    ::
+
+        # 对于 bash 用户
+        echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/linuxbrew-core.git"' >> ~/.bash_profile
+
+        # 对于 zsh 用户
+        echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/linuxbrew-core.git"' >> ~/.zshrc
 
 重置为官方地址：
 
 ::
 
-    cd "$(brew --repo homebrew/core)"
-    git remote set-url origin https://github.com/Homebrew/linuxbrew-core
+    unset HOMEBREW_CORE_GIT_REMOTE
+    git -C "$(brew --repo homebrew/core)" remote set-url origin https://github.com/Homebrew/linuxbrew-core
+
+.. note::
+    重置回默认远程后，用户应该删除 shell 的 profile 设置中的环境变量 ``HOMEBREW_CORE_GIT_REMOTE`` 以免运行 ``brew update`` 时远程再次被更换。
 
 相关镜像
 ========