[Mac] HomebrewでGitアップデートできないエラー => Error: The `brew link` step did not complete successfully The formula built, but is not symlinked

副題： HomebrewでGitのバージョンをアップグレードしたのに git --version で確認するとバージョンが変わらない件

環境

• macOS 10.14.6
• git version 2.22.0
• Homebrew 2.2.0

（2019年12月3日時点）

結論

パスの通し方（環境変数）に問題がないとすれば、Homebrewで何らかのパッケージをインストール/アップデート/アップグレード時、シンボリックリンクが貼られなかったことが原因。以下のコマンドで解決。

ターミナル

$ brew link --overwrite git

Git以外のパッケージのsymlinksを解決したいときは、上記コマンドの git の部分を適宜変更して実行。
記事タイトルに「HomebrewでGitアップデートできないエラー」と書いたものの、厳密には「Gitのアップデートはできているがシンボリックリンクが適切に貼られないため、コマンドで呼び出すとアプデされていないように見える」が正しい。

エラー発生までの流れと状況調査

そもそもはGitを最新版にアップグレードしたい！と思ったのが始まりでした。

1. 現在のGitのバージョンを確認

ターミナル

$ git --version
git version 2.22.0
# 最新版は 2.24.0

2. Homebrewでアップグレード

ターミナル

$ brew upgrade git

この後 git --version でちゃんとバージョンアップできたか確認するも、
2.22.0 からバージョンが変わらないという状況が発生。
Homebrewで管理できてなかった、パスが通ってなかった？などを調査。

3. which で、 git コマンドがどこを参照しているか確認

ターミナル

$ which git
/usr/local/bin/git

Homebrewでインストールした場所にあるようには見えるが・・・確実ではないので引き続き調査。

4. brew ls で、Homebrewからインストールしたパッケージを確認

ターミナル

$ brew ls
autoconf                glib                    libde265                little-cms2             openssl@1.1             x265
automake                heroku                  libffi                  mysql                   pcre                    xz
cmake                   heroku-node             libheif                 node                    python                  yarn
freetype                icu4c                   libomp                  nodebrew                readline
gdbm                    ilmbase                 libpng                  openexr                 shared-mime-info
gettext                 imagemagick             libtiff                 openjpeg                sqlite
git                     jpeg                    libtool                 openssl                 webp

やっぱりGitあるもよう。
インストール済みのパッケージが多すぎてリストが見づらい場合は、 grep のコマンドで絞り込みも可能。

ターミナル

$ brew ls | grep git
git

5. brew list git で、Homebrewでのインストール先 ＝ HomebrewでインストールしたGitの本体がある場所を確認

ターミナル

$ brew list git
/usr/local/Cellar/git/2.18.0/.bottle/etc/gitconfig
/usr/local/Cellar/git/2.18.0/bin/git
/usr/local/Cellar/git/2.18.0/bin/git-cvsserver
/usr/local/Cellar/git/2.18.0/bin/git-receive-pack
/usr/local/Cellar/git/2.18.0/bin/git-shell
/usr/local/Cellar/git/2.18.0/bin/git-upload-archive
/usr/local/Cellar/git/2.18.0/bin/git-upload-pack
/usr/local/Cellar/git/2.18.0/bin/gitk
/usr/local/Cellar/git/2.18.0/etc/bash_completion.d/ (2 files)
/usr/local/Cellar/git/2.18.0/libexec/git-core/ (196 files)
/usr/local/Cellar/git/2.18.0/share/doc/ (847 files)
/usr/local/Cellar/git/2.18.0/share/emacs/ (2 files)
/usr/local/Cellar/git/2.18.0/share/git-core/ (158 files)
/usr/local/Cellar/git/2.18.0/share/git-gui/ (61 files)
/usr/local/Cellar/git/2.18.0/share/gitk/ (13 files)
/usr/local/Cellar/git/2.18.0/share/gitweb/ (5 files)
/usr/local/Cellar/git/2.18.0/share/man/ (171 files)
/usr/local/Cellar/git/2.18.0/share/perl5/ (19 files)
/usr/local/Cellar/git/2.18.0/share/zsh/ (2 files)

やはりちゃんとあるようだが、バージョン2.18.0・・・？雲行きが怪しくなってきた。

6. gitコマンドのショートカット（エイリアス）ではなくフルパスを指定して複数のGitのバージョンを確認

ターミナル

$ /usr/bin/git --version
git version 2.20.1 (Apple Git-117)

ターミナル

$ /usr/local/bin/git --version
git version 2.22.0

バージョンからしてもgitコマンドは /usr/local/bin/git を向いていることを再度確認。

6. brew upgrade git したときにエラーがなかったかもう一度確認

ターミナル

$ brew upgrade git
==> Upgrading 1 outdated package:
git 2.18.0 -> 2.24.0_2
==> Upgrading git 
==> Installing dependencies for git: pcre2
==> Installing git dependency: pcre2
==> Downloading https://homebrew.bintray.com/bottles/pcre2-10.34.mojave.bottle.tar.gz
==> Downloading from https://akamai.bintray.com/9b/9bc0815c6c4c584ef16e93e5ecf37aa786303d88f9321274a29b4f60876d583f?__gda__=exp=1575368945~hmac=5a828a3607
######################################################################## 100.0%
==> Pouring pcre2-10.34.mojave.bottle.tar.gz
🍺  /usr/local/Cellar/pcre2/10.34: 230 files, 5.9MB
==> Installing git
==> Downloading https://homebrew.bintray.com/bottles/git-2.24.0_2.mojave.bottle.tar.gz
==> Downloading from https://akamai.bintray.com/34/343c1a0b842b84095aa0632ea7ca3f1717103fe4f393a6014c7f6165b079c849?__gda__=exp=1575368950~hmac=f533430d65
######################################################################## 100.0%
==> Pouring git-2.24.0_2.mojave.bottle.tar.gz
Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink bin/git
Target /usr/local/bin/git
already exists. You may want to remove it:
  rm '/usr/local/bin/git'

To force the link and overwrite all conflicting files:
  brew link --overwrite git

To list all files that would be deleted:
  brew link --overwrite --dry-run git

Possible conflicting files are:
/usr/local/bin/git -> /usr/local/git/bin/git

（〜中略〜）

/usr/local/share/man/man7/gitworkflows.7 -> /usr/local/git/share/man/man7/gitworkflows.7
==> Caveats
Bash completion has been installed to:
  /usr/local/etc/bash_completion.d

zsh completions and functions have been installed to:
  /usr/local/share/zsh/site-functions

Emacs Lisp files have been installed to:
  /usr/local/share/emacs/site-lisp/git
==> Summary
🍺  /usr/local/Cellar/git/2.24.0_2: 1,547 files, 45.1MB
Removing: /usr/local/Cellar/git/2.10.2... (1,445 files, 31.8MB)
Removing: /usr/local/Cellar/git/2.18.0... (1,488 files, 35.5MB)
==> Checking for dependents of upgraded formulae...
==> No dependents found!
==> Caveats
==> git
Bash completion has been installed to:
  /usr/local/etc/bash_completion.d

zsh completions and functions have been installed to:
  /usr/local/share/zsh/site-functions

Emacs Lisp files have been installed to:
  /usr/local/share/emacs/site-lisp/git

7. エラー内容が書いてあった...！！

ターミナル

Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink bin/git
Target /usr/local/bin/git
already exists. You may want to remove it:
  rm '/usr/local/bin/git'

To force the link and overwrite all conflicting files:
  brew link --overwrite git

要するに、 /usr/local/bin/git に対してgitコマンドのシンボリックリンク（ショートカットのようなもの）を作成しようとしたけど対象がすでに存在するため、エラーになってシンボリックリンク作れなかったよ、ということのようだ。
「対象ファイルを削除したいときはこうしてね」と rm リムーブのコマンドが親切に書かれているが、その次に書かれた brew link --overwrite git のコマンドでシンボリックリンクの上書きをすれば良さそうである。

8. シンボリックリンクのオーバーライトを実施

ターミナル

$ brew link --overwrite git
Linking /usr/local/Cellar/git/2.24.0_2... 206 symlinks created

$ git --version
git version 2.24.0

あらためて、無事にGitのバージョンアップができました！

まとめ

• ログとエラー内容はよく読む。
• GitなどのパッケージはひとつのPCに複数インストールされている可能性がある。
• いま自分がどこに保存したどのバージョンのどのパッケージを触っているのかを把握する。
• Error: The brew link step did not complete successfully ... The formula built, but is not symlinked ... というエラーはシンボリックリンクのエラーなので、内容をよく読みながら対応する。

以上！

参考URL

【Homebrew】インストールしたパッケージのシンボリックリンクが作成されない場合
今さらだけどHomebrewのコマンドをちゃんと理解して使おう
【 whereis 】コマンド――コマンド本体と関連ファイルを検索する
PATHを理解して、コマンドの在りかを探してみよう (1/3)
Homebrew使い方まとめ
homebrewインストール時にリンクが貼られない問題
HomebrewでGitをインストールする
brew install nmap で発生したインストール時のエラーをchownで解決
MacのGitのバージョンをアップデート！Homebrewでの管理に切り替える
Git のインストール 〜Git をMacにインストールしよう〜