チュートリアル（macOS・Linux）

なにも管理していない状態から始めて，dotfilesをRigoの管理下に置き，2台目のマシンと同期するまでをステップバイステップで進めます。その先の整理（OS別・マシン別・secrets）と日々の運用までを一通り体験します。Windows Terminalで進める場合はチュートリアル（Windows）を参照してください。

前提は次の2つだけです。

• インストールが済んでいること
• マシン間でディレクトリを同期する手段（Syncthing・Dropbox・iCloud Driveなど）があること。Rigoは同期機構に関知しないので，どれでも構いません。まだ用意していなくても，1台のマシンで試す分には不要です

以下の例ではVaultを ~/Sync/Vault に置きます。同期ツールが同期しているディレクトリに読み替えてください。また，実行例に現れる絶対パスはmacOSの表記（/Users/ada）です。たいていのLinuxではホームディレクトリが /home/ada になるので，適宜読み替えてください。

Step 1 — Vaultを作る

Vaultはただのディレクトリです。設定ファイル rigo.toml の置き場所だけが決まっています（<vault>/.config/rigo/rigo.toml）。中身は空で構いません。

mkdir -p ~/Sync/Vault/.config/rigo
touch ~/Sync/Vault/.config/rigo/rigo.toml

初回だけ -f でこの rigo.toml を直接指定して apply を実行します。

rigo -f ~/Sync/Vault/.config/rigo/rigo.toml apply

linked    .config/rigo/rigo.toml

1 linked, 0 conflict, 0 broken, 0 failed, 0 excluded

この時点でVault内の rigo.toml 自身が ~/.config/rigo/rigo.toml へリンクされました。RigoはこのsymlinkをたどってVaultの場所を発見するので，以降は -f が不要になります。

rigo status

host: mymac (mode: exclude)

linked    .config/rigo/rigo.toml

ヘッダの mymac がこのマシンのホスト名（後でマシンごとの選択に使う識別子）です。

Step 2 — 最初のファイルを管理する

rigo add は実体をVaultへ移動し，元の場所へsymlinkを張り戻します。

rigo add ~/.zshrc

added .zshrc

なにが起きたか確認してみます。

ls -l ~/.zshrc

lrwxr-xr-x  1 ada  staff  28 Jul 18 10:00 /Users/ada/.zshrc -> /Users/ada/Sync/Vault/.zshrc

~/.zshrc を今までどおりエディタで開いて編集すれば，実際に書き換わるのはVault側の実体です。変更はそのまま同期ツールに乗って他のマシンへ届きます。「編集 → applyで反映」のような追加操作はありません。

Step 3 — ディレクトリを管理する

ディレクトリを add するときは，2つの扱いから選びます。

• --dir
  ディレクトリ全体を1本のsymlinkとして展開します。中に新しいファイルを作っても自動で管理下に入ります。設定やプラグインが一体のもの（.vim/ や .hammerspoon/ など）に向きます。
• --files
  ディレクトリ単位ではなく，中のファイルを個別に移動・リンクします。中身の一部だけ後からOS別にしたい場合など，個別に制御したいものに向きます。

# ~/.vim を1本のsymlinkとして管理し，タグにまとめる
rigo add --dir --tag vim ~/.vim

added .vim/ (directory unit)

フラグを付けずにディレクトリを add すると，対話でどちらかを選べます。

  d) whole directory: one symlink, new files follow automatically
  f) files: move and link each file individually
  a) abort
choice:

--dir で追加したディレクトリは rigo.toml の dirs（--tag を付けた場合は [tags]）に自動で記録されます。--tag はエントリをタグにまとめ，後で rigo tag link vim のような一括操作を可能にします。

手作業と併用できる

ここまで rigo add を使ってきましたが，これは必須の経路ではありません。Rigoは隠れた状態ファイルやデータベースを持たず，Vaultのディレクトリ木と実際のファイルの状態だけを情報源にします。同じ結果になるなら，手作業で行っても壊れません。

• ファイルを自分でVault内の対応する場所へ移動し，symlinkも自分で張る。次の rigo status はそれを linked と認識します
• Vaultへ置くだけでsymlinkを張らない。エントリは pending（移動した場合）または unlinked（コピーして原本を残し，内容が同一の場合）として現れ，rigo apply が拾ってリンクします
• rigo.toml を直接編集する。--dir / --tag による自動追記は省力化にすぎず，手で書いても同じです（実際，この後のStepでは手で編集します）

各コマンドは，実体の退避とロールバック・conflictの確認・設定への自動追記といった手間を省くために用意されているものです。手作業と混ぜて使って構いません。

Step 4 — 2台目のマシンをつなぐ

2台目でもRigoをインストールし，同期ツールがVaultを同期し終えるのを待ちます。あとは初回ブートストラップだけです。

rigo -f ~/Sync/Vault/.config/rigo/rigo.toml apply

linked    .config/rigo/rigo.toml
linked    .vim
conflict  .zshrc  (resolve with "rigo link .zshrc")

2 linked, 1 conflict, 0 broken, 0 failed, 0 excluded

まだ存在しなかったファイル（pending）はそのままリンクされました。一方，2台目にすでに別内容の ~/.zshrc があったため，conflict として報告されています。Rigoがconflictを黙って解決することはありません。指示どおり解決します。

rigo link .zshrc

conflict: .zshrc
  vault: 1234 B, modified 2026-07-18 10:00:12
  local: 987 B, modified 2026-07-01 08:15:44
  +12 -3

diffが40行以内ならこの下にそのまま表示され，続けて選択肢が出ます。

  1) take the vault version (local content is replaced)
  2) adopt the local content into the vault, then link
  3) abort
choice:

• 1台目の内容に揃えるなら 1
• 2台目の内容のほうを正としてVaultに取り込むなら 2

を選びます。マシンをまとめてセットアップするスクリプトなどでは，rigo link --force .zshrc でVault側を採る解決を非対話で行えます。

これで2台のマシンが同じ実体を共有しました。どちらで編集しても，同期ツール経由でもう一方に反映されます。日々の確認は rigo status，同期されてきた新しいエントリの展開は rigo apply です。

Step 5 — OS別のファイルを扱う

macOSとLinuxで内容を変えたいファイルは，--os を付けて add します。エントリはVaultの .os/<darwin|linux|windows>/ 配下に置かれ，そのOSのマシンにだけ展開されます。

# Mac側で: このKarabiner設定はmacOSでしか意味を持たない
rigo add --os --dir ~/.config/karabiner

同じ論理パスを共通レイヤーとOSレイヤーの両方に置くと，OSレイヤーが優先されます。「基本は共通，macOSだけ差し替え」といった構成は，共通に .zshrc，.os/darwin/.zshrc に差し替え版を置くだけです。詳細は仕組みを参照してください。

Step 6 — マシンごとに展開を選ぶ

仕事用マシンには持ち込みたくないエントリ，サーバーには最小限だけ置きたい，といった選択は rigo.toml で宣言します。rigo.toml 自身も管理対象なので，どのマシンで編集しても全マシンに行き渡ります。

[groups]                     # グループ → ホスト（Ansibleインベントリ流）
work = ["workpc", "buildbox"]

[include]                    # ホスト/グループ → これだけを展開（allowlist）
servers = ["zsh", ".gitconfig"]

[exclude]                    # ホスト/グループ → これは展開しない
work = ["vim"]

• ホスト名は rigo status のヘッダに出る識別子（ホスト名の最初のドットまで・小文字）です。
• リストの項目はタグ名でもパスでも構いません。
• include を持つホストはallowlistモードになり，挙げたものだけが展開されます。

対象外になったエントリは status で excluded と表示され，apply が触ることはありません。

Step 7 — secretsを扱う

APIトークンや .netrc のような機微情報は，Vaultに実体を置かずパスワードマネージャーから実体化します。参照だけを rigo.toml に書きます（現在のバックエンドは1Passwordの op:// 参照で，op CLIが必要です）。

[secrets]                    # 書き出し先パス → パスワードマネージャー参照
".netrc"           = { ref = "op://Personal/netrc/notesPlain", mode = 0o600 }
".config/gh/token" = "op://Personal/GitHub/token"

rigo secrets apply

applied  .config/gh/token
applied  .netrc

2 secret(s) written

書き出されたファイルはsymlinkではなく実体で，Vaultには入りません（同期にも乗りません）。正は常にパスワードマネージャー側で，値を更新したら各マシンで rigo secrets apply を再実行します。存在確認は rigo secrets status，マシンを手放すときの削除は rigo secrets remove です。

Step 8 — 日々の運用

最後に，運用でよく使うコマンドをまとめます。

# ドリフトはないか（読み取り専用。差分があれば終了コード1）
rigo diff

# 同期ツールが新しいエントリを届けたら収束させる
rigo apply

# 一時的に実体化する（ローカルで実験したいときなど）
rigo unlink .zshrc
rigo link .zshrc          # 共有版に戻す

# 管理をやめる（ローカルの実体は残り，Vault側はトラッシュへ）
rigo forget .zshrc

# トラッシュはforgetのundo
rigo trash ls
rigo trash restore .zshrc

# 壊れたリンクを掃除する（他マシンでのforget後など）
rigo clean

forget したエントリの実体はVault内のトラッシュに残るため，やり直しがききます。トラッシュは全マシン共通の安全網なので，rigo trash empty は本当に不要になってから実行してください（--older-than 30d のような期限指定もできます）。

ここまでで，Rigoの日常操作は一通り押さえました。個々のコマンドの全フラグと挙動はコマンドリファレンス，rigo.toml の全項目は設定リファレンスを参照してください。