~/.zshrc を置かない dotfiles：ZDOTDIR と chezmoi

ZDOTDIR で設定を移動する#

macOS の interactive login shell は、おおむね次の順で設定を読む。

1
/etc/zshenv      →  ~/.zshenv      (always, every shell)
2
/etc/zprofile    →  ~/.zprofile    (login shells)
3
/etc/zshrc       →  ~/.zshrc       (interactive shells)
4
/etc/zlogin      →  ~/.zlogin      (login shells)

~/.zshenv はすべての zsh で最初に読まれる。ここで ZDOTDIR を設定すると、.zprofile、.zshrc、.zlogin の探索先が $HOME から $ZDOTDIR に変わる。

1
# ~/.zshenv — the only zsh file allowed to live in $HOME
2
export ZDOTDIR="${XDG_CONFIG_HOME:-$HOME/.config}/zsh"

これは zsh が正式にサポートする仕組みだ。VS Code の integrated terminal も ~/.zshenv を読む。古いツールの一部は ~/.zshrc を決め打ちしているが、私の環境では問題になることは少なかった。

長い一ファイルを作らない#

移動先で再び巨大な .zshrc を作らないよう、.zshrc 自体は番号順に fragment を読むだけにした。

1
# ~/.config/zsh/.zshrc — loads every fragment in numeric order
2
for _file in "${ZDOTDIR}"/conf.d/*.zsh(N); do
3
  source "$_file"
4
done
5
unset _file

(N) は、対象がないときにエラーではなく空へ展開する zsh の glob qualifier。

1
~/.config/zsh/conf.d/
2
├── 00-env.zsh          # exported env vars, PATH base
3
├── 10-completion.zsh   # compinit and completion styles
4
├── 20-aliases.zsh      # short renames of existing commands
5
├── 30-functions.zsh    # shell functions that do real work
6
├── 35-tools.zsh        # eval-hooks for external CLIs (mise, zoxide, …)
7
├── 40-lang.zsh         # language/runtime-specific setup
8
├── 50-plugins.zsh      # zsh-ecosystem plugins
9
└── 90-local.zsh        # machine-specific, not tracked in git

環境変数、関数、外部 CLI が生成する hook、言語設定、プラグインの順に分ける。prompt が runtime 情報を使う場合は mise の activation より後に読み、syntax highlighting は line editor を wrap するので最後に置く。

PATH を重複させない#

~/.zshenv は子 shell でも実行されるため、

1
export PATH="$HOME/.local/bin:$PATH"

をそのまま置くと tmux、subshell、exec zsh のたびに同じパスが増える。

1
# Prepend to PATH only if not already present.
2
path_prepend() {
3
  case ":$PATH:" in
4
    *":$1:"*) ;;            # already there — do nothing
5
    *) PATH="$1:$PATH" ;;
6
  esac
7
}
8

9
path_prepend "$HOME/.local/bin"

PATH の両端にもコロンを付けることで、先頭と末尾の要素も完全一致で確認できる。この関数は 00-env.zsh に置く。

chezmoi の source と target#

Git リポジトリを $HOME に直接 symlink する代わりに chezmoi を使う。source directory からホームディレクトリへレンダリングし、source 側のファイル名で属性も宣言する。

• dot_：先頭にドットを付ける。
• private_：結果を 0600 にする。
• executable_：実行 bit を付ける。
• exact_：宣言されていないディレクトリ内容を削除する。
• run_onchange_：内容が変わったときにスクリプトを実行する。アプリの記事では Brewfile の変更時に使う。

1
chezmoi source repo            →  rendered into $HOME
2
├── dot_zshenv                 →  ~/.zshenv
3
├── dot_config/
4
│   └── zsh/
5
│       ├── dot_zshrc          →  ~/.config/zsh/.zshrc
6
│       └── conf.d/
7
│           ├── 00-env.zsh     →  ~/.config/zsh/conf.d/00-env.zsh
8
│           └── 20-aliases.zsh →  ~/.config/zsh/conf.d/20-aliases.zsh
9
└── dot_local/
10
    └── bin/
11
        └── executable_zhealth →  ~/.local/bin/zhealth  (chmod +x)

zhealth で勝手に増えた設定を探す#

構成後、$HOME にある zsh ファイルは ~/.zshenv だけになる。~/.zshrc が復活したら、インストーラーが書いた可能性が高い。

1
# 30-functions.zsh — flag stray zsh files in $HOME
2
zhealth() {
3
  local stray=(~/.zshrc(N) ~/.zprofile(N) ~/.zlogin(N) ~/.zshrc.*(N))
4
  if (( ${#stray} )); then
5
    print -u2 "zhealth: unexpected zsh files in \$HOME:"
6
    printf '  %s\n' "${stray[@]}" >&2
7
    return 1
8
  fi
9
  print "zhealth: \$HOME is clean — only ~/.zshenv expected"
10
}

新しいツールを入れたあとに実行すれば、数か月後にシェルの挙動から原因を推測せずに済む。メンテナンスの記事でも同じ health check の考え方を使う。

追跡しないもの#

~/.zsh_history は設定ではなく状態で、内容も private。.zcompdump* は再生成できる cache。credential や token も通常の dotfiles リポジトリには置かない。

1
.config/zsh/.zcompdump*
2
.zsh_history

マシン固有の proxy や local alias は 90-local.zsh に置く。最後に読み込むので上書きできるが、Git では管理しない。

結果として $HOME には入口が一つ、設定本体は順序付きの小さな fragment、期待状態は chezmoi、勝手に増えたファイルの確認は zhealth という形になった。