背景

ツールの補完を使う上でcompletionファイルの管理が必要です。

ただ生成AIやネット上ではbash-completionのv1なのかv2なのか情報が混ざっており、よく分からないことがあったので自分で整理することにしました。

環境

• macOS v15.7.2
• bash v5.3.8
• bash_completion v2.17

bash-completion@2の使い方

bashの設定

Macではライセンスの関係からデフォルトではbash 3までしか使えません。
（3.2 までのライセンスが GPLv2、4.0 から GPLv3 なため）

なので使う場合は自前でbrewからインストール＆デフォルトシェルの設定が必要です。

$ brew install bash

デフォルトシェルの設定

インストールされた場所を確認しておきます。

$ which bash
/opt/homebrew/bin/bash

シェル設定可能なシェルリストに先ほどのパスを追加します。

$ sudo vi /etc/shells

# List of acceptable shells for chpass(1).
# Ftpd will not allow users to connect who are not using
# one of these shells.

/bin/bash
/bin/csh
/bin/dash
/bin/ksh
/bin/sh
/bin/tcsh
/bin/zsh
/opt/homebrew/bin/bash  # 追加

ログインシェルの変更をします。

chsh -s /opt/homebrew/bin/bash

chsh: no changes made

が出る場合はターミナルで直接指定します。

bash-completion@2のインストール

bashの設定が終わったらbash-completion@2をインストールします。

brew install bash bash-completion@2

.bashrc設定

次に.bashrcに以下の設定を追記します。上記のbrew install後にもそのような旨が記載されているはずです。

HOMEBREW_PREFIX=$(brew --prefix)
if [[ -r "${HOMEBREW_PREFIX}/etc/profile.d/bash_completion.sh" ]]; then
    source "${HOMEBREW_PREFIX}/etc/profile.d/bash_completion.sh"
fi

completions設定の読み込みルール

completions設定の読み込みには「遅延ロード」と「即時ロード」の2つの仕組みがあります。
基本は遅延ロードを使います。

特徴	遅延ロード (推奨)	即時ロード (旧式/手動)
タイミング	コマンドを入力してTabを押した瞬間	シェルを起動した瞬間
特徴	シェル起動が高速。メモリ消費が少ない。	常に有効化されているが、起動が遅くなる
ファイル名	コマンド名と一致させる必須あり (例: docker コマンドならファイル名も docker)	自由（ただし自分で管理が必要）
配置方法	指定のディレクトリに置くだけ	.bashrc に source /path/to/file と書く。 ~/.bash_completionに書く

completionファイルの置き場

completionsの実体は以下のディレクトリに配置します。

システム全体（標準）

homebrewで入れるツールはここに配置します。

• ${HOMEBREW_PREFIX}/share/bash-completion/completions
  • git や docker などをbrewで入れるとここに補完ファイルが置かれる

ユーザ独自

GitHubで配布されているようなツールや、独自ツールはこちらに配置します。

• 第1候補: 環境変数 $BASH_COMPLETION_USER_DIR を設定していれば、その中の completions フォルダ。
• 第2候補: 環境変数 $XDG_DATA_HOME を設定していれば、その中の bash-completion/completions フォルダ。
• 第3候補（デフォルト）: 何も設定していなければ、~/.local/share/bash-completion/completions。

即時ロード用

上記の遅延ロードではなく、旧来の即時ロードの場合は以下の設定をします。

• .bashrc に source /path/to/file と書く
• ~/.bash_completionというファイルを作り、その中に直接補完コードを書く

bash_completionの検索ルール

コマンド（例: mycmd）を入力してTabキーを押した際、システムは以下の優先順位で補完ファイルを探してロードします。

1. ユーザディレクトリ
   • $BASH_COMPLETION_USER_DIR/completions 内の mycmd または mycmd.bash
2. bash_completion本体の場所
   • システムインストール先の completions ディレクトリ
3. コマンド自体の場所（v2.12以降）
   • 実行しようとしているコマンドが /bin にある場合、その親ディレクトリの share/bash-completion/completions も探す
4. XDGデータディレクトリ
   • システム標準パス（/usr/local/share 等）の bash-completion/completions

まとめ

bash_completionsを追加したいときに、どこに配置すべきかを理解することができました。

参考

• scop/bash-completion: Programmable completion functions for bash
• bash から zsh への移行 - Mac の使い方 - Swift による iOS 開発入門
• Macのデフォルトシェルを zsh から bash へ変更する｜Mac OSXを使いやすくする説明書