設定の基本

vig には完全な組み込み設定が入っていて、設定ファイルを書く必要はありません。何かを変えたくなったら（テーマ、キー、タブ、レイアウト）、 1 つの KDL ファイルに変更点だけを書けば、vig がデフォルトの上にマージします。変えたい部分だけを書けばよい、ということです。

この章では、設定ファイルの場所、レイヤの重なり方、vig config サブコマンド、ファイルを読み書きするのに必要な最低限の KDL、そしてマージ規則を説明します。次の設定レシピの章は実例集で、掲載しているすべてのスニペットはそのまま動く完全な設定です。

3 つのレイヤ

vig は最大 3 つのレイヤを順に重ねて、有効な設定を組み立てます:

3. リポジトリローカル   worktree ルートの .vig.kdl   （個人用・リポジトリごと）
2. ユーザー             ~/.config/vig/config.kdl     （自分用・全リポジトリ共通）
1. 組み込み             埋め込まれたデフォルト        （常に存在）

vig config path を実行すると、3 つのレイヤそれぞれのパスと、見つかったか・読み込まれたかの状態がいつでも確認できます。

1 — 組み込み

デフォルトはバイナリに埋め込まれています。それ自体が完全な KDL 設定 — vig config dump が出力するのと同じ assets/default.kdl — なので、設定できるものすべてがコメント付きで 1 か所にまとまっています。

2 — ユーザー

あなた自身の設定ファイルです。vig は次の順で探します:

コマンドラインフラグ --config <path>
環境変数 $VIG_CONFIG
$XDG_CONFIG_HOME/vig/config.kdl。XDG_CONFIG_HOME が未設定なら ~/.config/vig/config.kdl — macOS を含む すべての OS で同じです（vig は意図的に ~/Library/Application Support を使いません。 zellij / helix などのユーザーがどのプラットフォームでも期待するのは ~/.config/vig だからです）

デフォルトの場所にファイルが無ければ単に「デフォルトを使う」ですが、 --config や $VIG_CONFIG で明示したパスは存在しなければなりません — 無ければ vig は起動を拒否するので、パスのタイポが黙って別の設定にすり替わることはありません。なお --config / $VIG_CONFIG はユーザーレイヤを置き換えるものであって、4 つ目のレイヤを増やすものではありません。

3 — リポジトリローカル（`.vig.kdl`）

vig は現在の worktree のルートにある個人用 .vig.kdl も読み、ユーザー設定の上にマージします。これにより、リポジトリごとに別のテーマ・タブ・キーバインドを持たせられます。スキーマはユーザー設定とまったく同じで、 gitignore しておく想定のファイルです — プロジェクトのものではなく、あなたのファイルです。何を書くかはリポジトリごとの設定レシピを参照してください。

クローンしたリポジトリがコミット済みの .vig.kdl を同梱している可能性があるため、信頼するかどうかは git の追跡状態で決まります:

未追跡の .vig.kdl はあなた自身のファイルです。黙って読み込まれ、起動時にステータスバーへ loaded .vig.kdl と一度表示されます。
追跡中の .vig.kdl はリポジトリ由来です。アプリが組み立てられる前に信頼ダイアログが表示されます（回答次第でどのページ・どのキーバインドが存在するかまで変わるためです）。y で読み込んで記憶、 n で無視して記憶、v でファイルの中身を確認してから判断、Esc は今回だけ無視して何も記憶しません。

決定は $XDG_STATE_HOME/vig/trust.json （~/.local/state/vig/trust.json）に、worktree パスとファイル内容のハッシュをキーとして保存されます — ファイルが変わると（pull の後など）古い決定は適用されず、もう一度確認されます。vig config trust で記憶済みの決定を一覧でき、vig config trust --forget <path> で 1 件を忘れさせられます。

このレイヤには、どちらも意図的な性質が 2 つあります:

中断せず、劣化する。 .vig.kdl のエラーが vig の起動を妨げることはありません。組み込み + ユーザーの設定で起動し、ステータスバーに ignored .vig.kdl: <理由>（stderr にも 1 行）が出ます。
自分のスイッチを自分で操作できない。 ユーザー設定に repo-config "off" と書けばこのレイヤは完全に無効になります — 読み込みもダイアログもなし。有効なのはユーザー設定の値だけで、 .vig.kdl 自身に repo-config を書くことは（"on" でも）拒否されます。

`vig config` サブコマンド

コマンド	内容
`vig config path`	レイヤごとに 1 行 — 組み込み / ユーザー / リポジトリローカル — でパスと状態（`loaded`、`not found`、`ignored (…)`、`pending trust decision`）を表示。
`vig config dump`	組み込みデフォルト設定を出力。コメント付きの完全なスキーマで、自分のファイルの最良の出発点。
`vig config themes`	利用可能なシンタックスハイライトのテーマを一覧。`*` が現在有効なもの。
`vig config trust`	記憶済みの `.vig.kdl` 信頼決定を一覧（worktree、決定、日時）。
`vig config trust --forget <path>`	1 つの worktree の決定を忘れ、次回また確認させる。

どのサブコマンドも --config / $VIG_CONFIG を尊重するので、 vig --config ./try.kdl config path でそのファイルがどう扱われるかを確かめられます。

dump をコピーして、削る

最初の設定ファイルを書く快適な方法:

mkdir -p ~/.config/vig
vig config dump > ~/.config/vig/config.kdl

ファイルを開き、変えたいところを変えたら、変えなかった部分をすべて削除してください。あなたのファイルは部分上書きです: 書かれていないものはデフォルトのままです。削ることが大事な理由はもう 1 つあります: dump の完全コピーはすべてのデフォルトを今日の値で凍結してしまうので、将来の vig がデフォルトのバインドやレイアウトを改善しても、「触っていないのにコピーされた」値が黙ってそれを上書きします。削った設定はあなたの意見だけを、それ以外は何も語りません。

削り終えたファイルは、たいていこのくらい小さくなります:

theme "Solarized (dark)"
icons "none"
pages "git" "github" "worktrees"

vig は起動時にファイルを検証するので、編集 → vig 実行 → エラーを読む → 直す、のループを素早く回せます。本物の設定に触らず実験するには別ファイルを指せば安全です: vig --config ./try.kdl。

最低限の KDL

設定は KDL ドキュメントです。読み書きに必要な考え方は 5 つだけです:

ノードは名前 + 引数: theme "Solarized (dark)"。
引数はダブルクォートの文字列で、複数並べられます: pages "git" "files" "worktrees"。（例外が 1 つだけ裸の整数を取ります: projects-board 2。）
プロパティはノードに付く名前付きの値: split direction="horizontal"。
ノードは { … } の子ブロックを持て、何段でもネストできます。
コメント: 行末までの //、範囲の /* … */、そして KDL 特有の slashdash /- — 直後のノードを子ごと丸ごとコメントアウトします。

5 つ全部を 6 行で:

theme "Solarized (dark)"        // 文字列引数 1 つのノード
/- icons "none"                 // slashdash: このノードは無視される
page "git" {                    // 子ブロック
    layout {
        split direction="horizontal" {      // プロパティ
            place "file_tree" size="30"
            place "diff_view" size="min:20"
        }
    }
}

（この例は実際に読み込めます — 同時に Git ビューのレイアウトをファイルツリーと diff だけに置き換える例にもなっています。詳しくはレイアウトのレシピを参照。）

マージの仕組み

あなたのファイルはノード単位でデフォルトにマージされ、ノードによってマージのされ方が違います。3 つのクラスがあります:

クラス	ノード	規則
丸ごと置換	`theme`、`icons`、`image-preview`、`procs-refresh-interval`、`procs-history`、`github-poll-interval`、`projects-board`、`pages`、`repo-config`	あなたのノードがデフォルトのノードを丸ごと置き換える。
キー単位マージ	`app { }`、`page "…" { pane "…" { keys { } } }`	書いたキーだけがそのキーのデフォルトを置き換え、書かなかったキーはデフォルトのまま。`preset` 行は常に追加される。
ページ内で丸ごと置換	`page "…" { layout { } }`、`tabs`、`bind`	ページブロックに `layout` があれば、そのページのレイアウト全体を置き換える。`tabs` も、`bind` 行の集合も同様。

その帰結を具体的に:

トップレベルの値はオール・オア・ナッシング — それぞれが単一の値なので自然な規則です。pages のリストはデフォルトのリストを 丸ごと置き換えます: 書かなかったページは移動ではなく無効化です。
キーのブロックは追記式。 page "git" { pane "file_tree" { keys { "o" "ExpandOrOpen" } } } はバインドを 1 つ足すだけで、file_tree の他のキーはすべてデフォルトのままです。特別なアクション "None" に割り当てるとキーを削除できます。キーバインドの微調整が、40 個のデフォルトの書き直しではなく 2 行で済むのはこのためです。
レイアウトは追記式ではありません。 ページに layout を書いたら、それはそのページのレイアウト全体です — 木を書き直さずに 1 つのペインのサイズだけ動かす方法はありません。vig config dump の該当ブロックをコピーして編集してください。tabs（ペインの巡回順）と bind（選択→詳細の接続）も同じで、ユーザーの bind を 1 行でも書くと、そのページのデフォルトの bind 行はすべて置き換わります。

ページ名とペイン名は固定です — 並べ替え・リサイズ・リバインドはできますが、新しく発明することはできません。有効なページは git、 github、files、docker、procs、worktrees、projects で、各ページのペインは vig config dump で確認できます。

リポジトリローカルの .vig.kdl もまったく同じ規則で、1 段あとにマージされます: 組み込み → ユーザー → リポジトリローカル、でリポジトリローカルが勝ちます。

エラーは大声で

ユーザー設定に問題があれば — 構文エラー、未知のノード、存在しないテーマ名、同じペインを 2 回置く・何も置かないレイアウト — vig は起動せず、ファイル名（構文エラーなら行:桁も）を含むメッセージを出します。設定ファイルがあるのに黙ってデフォルトへフォールバックすることはないので、タイポが見過ごされることはありません:

theem "Solarized (dark)"
// → invalid config file ~/.config/vig/config.kdl:
//   unknown top-level block "theem" (expected `theme`, `icons`, ...)

唯一の例外はリポジトリローカルレイヤで、前述の通り中断せず劣化します。

Keyboard shortcuts

vig ユーザーガイド