最近CLIツールが好んで設定を書き込む ~/.config ディレクトリとは何か？

はじめに

最近、CLIツールの設定ファイルが ~/.config/ 配下に置かれているのをよく見かけるようになりました。

たとえば、私のmacOSで確認したところ、以下が該当しました。

• Gitの場合: ~/.config/git
• miseの場合: ~/.config/mise
• GitHub CLIの場合: ~/.config/gh
• Ghosttyの場合: ~/.config/ghostty

以前はツールごとにホームディレクトリ直下へ ~/.foorc や ~/.foo/ を勝手に作るのが普通だったのに、いつの間にこうなったんでしょうか？

調べてみたところ、XDG Base Directory Specification という仕様に基づくものだったので、この記事にメモしておきます。

XDG Base Directory Specification とは

XDG は "X Desktop Group" の略で、現在は freedesktop.org として知られるデスクトップ環境の相互運用性を推進する団体です。そのXDGが策定した仕様のひとつが Base Directory Specification で、アプリやツールの設定ファイル等をどこに置くかを定めています。

今の仕様では主なユーザ固有の環境変数として4つとそのデフォルトパスが定義されています¹。XDG対応ツールはこれらの環境変数を参照するので、環境変数を設定すればファイルの保存先を変更できます。未設定の場合はデフォルトパスが使われます。

環境変数	デフォルト	用途	例
XDG_CONFIG_HOME	~/.config	設定ファイル	git, fish, gh, mise, ghostty
XDG_DATA_HOME	~/.local/share	永続データ	mise, uv, direnv
XDG_STATE_HOME	~/.local/state	状態データ（ログ・履歴）	mise, pnpm
XDG_CACHE_HOME	~/.cache	キャッシュ（消えてもよい）	uv, huggingface, semgrep

つまり ~/.config は「XDG仕様上のユーザの設定ファイルを置くデフォルトパス」です。ホームディレクトリのドットファイル乱立（dotfile pollution）を整理しようという動きで、xdgbasedirectoryspecification.com のような布教サイトもあります。

これらについて環境変数を変えることで設定可能ということなので、試しに pnpm (Node.js のパッケージマネージャ) のキャッシュ参照位置(XDG_CACHE_HOME)を変えて pnpm install してみます。

XDG_CACHE_HOME を変えて pnpm install してみる

$ mkdir -p /tmp/pnpm-xdg-test && cd /tmp/pnpm-xdg-test
$ echo '{"dependencies":{"is-odd":"3.0.1"}}' > package.json

$ XDG_CACHE_HOME=/tmp/test-xdg-cache pnpm install
Packages: +2
++
Done in 363ms using pnpm v10.28.2

$ find /tmp/test-xdg-cache/pnpm
/tmp/test-xdg-cache/pnpm
/tmp/test-xdg-cache/pnpm/metadata-v1.3
/tmp/test-xdg-cache/pnpm/metadata-v1.3/registry.npmjs.org
/tmp/test-xdg-cache/pnpm/metadata-v1.3/registry.npmjs.org/is-number.json
/tmp/test-xdg-cache/pnpm/metadata-v1.3/registry.npmjs.org/is-odd.json

指定した /tmp/test-xdg-cache/pnpm/ にレジストリのメタデータキャッシュが作られました。（なおパッケージ本体は pnpm store path に別途保存されるため、ここには含まれません。）

XDGに対応する必要があるか？

各言語のライブラリとXDG対応

各言語のライブラリがXDG環境変数を参照するようになっている場合があります。

• Go: os.UserConfigDir() (標準ライブラリ)
• Rust: dirs クレート
• Python: platformdirs
• Node.js: env-paths

ただし後述の通り、これらのライブラリの多くは macOS ではOS固有パスを返します。

そもそもXDGはLinuxの仕組みでは？　Windows / macOS ではどうなっている？

XDG はもともと Linux (freedesktop.org) の仕様ですが、Windows や macOS には以前から似た仕組みがあります。

用途	XDG (Linux)	Windows	macOS
設定	~/.config	%APPDATA%	~/Library/Application Support
データ	~/.local/share	%LOCALAPPDATA%	~/Library/Application Support
キャッシュ	~/.cache	%LOCALAPPDATA%	~/Library/Caches

ここで面白いのは、前述のライブラリの多くは macOS では OS固有のパスを返すという点です。たとえば Go の os.UserConfigDir() は macOS では ~/Library/Application Support を返し、XDG_CONFIG_HOME を設定しても無視されます。

Go の os.UserConfigDir() を macOS で試す

$ go run -e <(echo 'package main; import ("fmt";"os"); func main() { d, _ := os.UserConfigDir(); fmt.Println(d) }')
/Users/.../Library/Application Support

$ XDG_CONFIG_HOME=/tmp/custom go run -e <(echo 'package main; import ("fmt";"os"); func main() { d, _ := os.UserConfigDir(); fmt.Println(d) }')
/Users/.../Library/Application Support

XDG_CONFIG_HOME を設定しても無視されているのが分かります。

にもかかわらず、冒頭で挙げた gh や mise は macOS でも ~/.config を使っています。たとえばghについて実際に確認してみると：

macOSでの実際のパス

$ ls ~/.config/gh/
config.yml  hosts.yml

$ ls ~/Library/Application\ Support/gh/
ls: /Users/.../Library/Application Support/gh/: No such file or directory

これらのツールはOS固有パスではなく、あえて XDG のパスを直接参照する実装を選んでいます。

私のツールはXDGに対応すべき？

Linuxっぽい文化のCLIツールはOS固有パスよりXDGを優先したほうがいいという意見が多いかもしれません。

Ghostty でも Using XDG_CONFIG_HOME or .config isn't right on mac #2567 というディスカッションスレッドがあることからわかるように、ツールによってまちまちのようです。

Plenty of macOS software supports XDG directories too (usually cross-platform tools and not GUI tools). I think it'd be good for Ghostty to continue supporting it. So I think my main question is: what do we do if the user has a config file in both XDG and Application Support?

Ghostty supports config merging so we can load both, but then what order?
...
I'm thinking of the following order where later values overwrite earlier:

1. Defaults (builtins)
2. XDG
3. Application Support

自分のツール向けには、たとえば、以下のようにすればいいかもしれません。

• GUIアプリ: OS固有のパス（~/Library/..., %APPDATA%）を使う
• CLIツール: いわゆるLinuxライクなCUIツールであれば、macOS/Windows でも ~/.config を使ったほうが親切かも
  • もちろん前述の通り、ライブラリ関数はOS標準のストアを返すことがあるので、あえてXDGを優先する実装をする必要があるかも

まとめ

• ~/.config は XDG Base Directory Specification で定義された設定ファイルの標準置き場
  • ホームディレクトリ直下に設定ファイルを置くより好まれる
  • 他にもデータ・キャッシュなど用途別にディレクトリや環境変数が存在している
• Windows / macOS には以前から同等の仕組みがあり、各言語のライブラリはクロスプラットフォームで対応してくれるが、自作CLIツールなどあえてOS標準パスを無視してXDGを選ぶ場合には、それ用の実装が必要

1. 他に XDG_RUNTIME_DIR, XDG_DATA_DIRS, XDG_CONFIG_DIRS もあります ↩