twin-cli 0.2.0

Git worktree wrapper with side effects (symlinks and hooks)
Documentation

Twin - Git Worktree Wrapper with Side Effects

Twin は Git worktree の薄いラッパーで、シンボリックリンクやフックなどの副作用を追加した CLI ツールです。

概要

Git worktree コマンドをベースに、以下の副作用を追加しました：

  • シンボリックリンクの自動作成・削除
  • worktree 作成・削除時のフック実行
  • 設定ファイルによるカスタマイズ

主な機能

  • Worktree管理: Git worktreeのラッパーとして動作
  • シンボリックリンク: 設定ファイルの共有と環境間での一貫性維持
  • クロスプラットフォーム: Windows/macOS/Linuxに対応
  • フック機能: worktree作成・削除時のカスタムスクリプト実行
  • 柔軟な設定: TOML形式の設定ファイルによるカスタマイズ

インストール

Cargo (推奨)

# crates.ioから直接インストール
cargo install twin-cli

# または、最新の開発版をGitHubからインストール
cargo install --git https://github.com/yourusername/twin

ソースからビルド

# リポジトリをクローン
git clone https://github.com/yourusername/twin
cd twin

# ビルド＆インストール
cargo install --path .

バイナリダウンロード

Releasesページから、お使いのプラットフォーム用のバイナリをダウンロードできます。

使用方法

基本コマンド

Worktreeの作成（簡易版）

# 基本的な使用方法（ブランチ名のみ指定）
# デフォルトで ./worktrees/feature-new に作成される
twin add feature-new

# パスを明示的に指定
twin add feature-new ../custom-path

# 新しいブランチを作成
twin add feature-new -b feature-new

# 設定ファイルを指定（副作用を適用）
twin add feature-new --config .twin.toml

# Git worktree のみ実行（副作用をスキップ）
twin add feature-new --git-only

# その他の git worktree オプションもサポート
twin add feature-new --detach
twin add feature-new --lock

デフォルトでは、設定ファイルの worktree_base に指定されたディレクトリ（デフォルト: ./worktrees）に、ブランチ名と同じ名前のディレクトリが作成されます。

Worktreeの一覧表示（git worktree list のラッパー）

# デフォルト（テーブル形式）
twin list

# JSON形式で出力
twin list --format json

# シンプルな形式
twin list --format simple

Worktreeの削除（git worktree remove のラッパー）

# 通常の削除（ブランチ名またはパスを指定）
twin remove feature-new
twin remove ../feature-new

# 強制削除（エラーを無視）
twin remove feature-new --force

# Git worktree のみ実行（副作用をスキップ）
twin remove feature-new --git-only

設定管理

# デフォルト設定をTOML形式で出力
twin config default

# 現在の設定を表示
twin config --show

# 設定値をセット（未実装）
twin config --set key=value

# 設定値を取得（未実装）
twin config --get key

未実装機能

以下の機能は現在未実装です：

  • twin config --set/--get - 設定値の取得・設定
  • テンプレート処理

設定ファイル

Twin は .twin.toml という設定ファイルを使用して副作用を定義します。

設定ファイルの例

# .twin.toml - Twin設定ファイルの例

# Worktreeのベースディレクトリ（省略時: ./worktrees）
worktree_base = "./worktrees"

# ファイルマッピング設定
# Worktree作成時に自動的にシンボリックリンクやコピーを作成します
[[files]]
path = ".env.template"          # ソースファイルのパス
mapping_type = "copy"           # "symlink" または "copy"
description = "環境変数設定"     # 説明（省略可）
skip_if_exists = true           # 既存ファイルをスキップ（省略可）

[[files]]
path = ".claude/config.json"
mapping_type = "symlink"
description = "Claude設定ファイル"

# フック設定（worktree作成・削除時に実行するコマンド）
[hooks]
pre_create = [
  { command = "echo", args = ["Creating: {{branch}}"] }
]
post_create = [
  { command = "npm", args = ["install"], continue_on_error = true }
]
pre_remove = []
post_remove = []

設定項目の詳細

ファイルマッピング ([[files]])

フィールド 型 必須 説明
path string ✓ ファイルパス（メインリポジトリとworktreeで同じパス）
mapping_type string - "symlink" または "copy"（デフォルト: "symlink"）
skip_if_exists bool - 既存ファイルをスキップ（デフォルト: false）
description string - マッピングの説明

フックコマンド

フィールド 型 必須 説明
command string ✓ 実行するコマンド
args array - コマンド引数（{{branch}}、{{worktree_path}}などの変数を使用可）
continue_on_error bool - エラー時も続行（デフォルト: false）
timeout u64 - タイムアウト秒数（デフォルト: 60）

トラブルシューティング

Windows でシンボリックリンクが作成できない

問題: 「シンボリックリンクの作成に失敗しました」というエラーが表示される

解決方法:

  1. 開発者モードを有効にする（推奨）

    • 設定 → 更新とセキュリティ → 開発者向け
    • 「開発者モード」を有効にする

  2. 管理者権限で実行する

    • コマンドプロンプトを管理者として実行
    • または PowerShell を管理者として実行

  3. ファイルコピーモードを使用する

    • 設定ファイルで mapping_type = "copy" を指定

Worktreeが作成できない

問題: 「Worktreeの作成に失敗しました」というエラー

考えられる原因と解決方法:

  1. Gitリポジトリではない

    git init

  2. 同名のブランチが既に存在する

    # ブランチを確認
git branch -a
# 別の名前を指定
twin add ../agent-001 -b feature/another-name
# または強制的にブランチを再作成
twin add ../agent-001 -B feature/new-name

  3. Worktreeが既に存在する

    # Worktreeを確認
twin list
# または
git worktree list
# 既存のWorktreeを削除
twin remove ../agent-001
# または
git worktree remove ../agent-001

設定ファイルが読み込まれない

問題: カスタム設定が適用されない

確認事項:

  1. 設定ファイルの場所

    • プロジェクトルート: ./.twin.toml

  2. 設定ファイルの形式

    # デフォルト設定を確認
twin config default

  3. TOML構文エラー

    • 引用符の閉じ忘れ
    • 配列の記法ミス
    • インデントエラー

デバッグ情報の出力

環境変数を設定してデバッグ情報を表示：

# 詳細ログを表示
export RUST_LOG=debug
twin add ../agent-001 -b feature/test

# Gitのみ実行（副作用をスキップ）
twin add ../agent-001 --git-only

開発状況

実装済み機能

  • ✅ Git worktree コマンドのラッパー（add, list, remove）
  • ✅ シンボリックリンク作成・削除（Unix/Windows対応）
  • ✅ フック実行（pre/post create/remove）
  • ✅ 設定ファイル読み込み（.twin.toml）
  • ✅ 複数の出力形式（table, json, simple）
  • ✅ エラーハンドリング
  • ✅ --git-only オプション（副作用をスキップ）

未実装機能

  • ⏳ テンプレート処理
  • ⏳ 設定値の取得・設定（config --set/--get）

ライセンス

MIT License

コントリビューション

プルリクエストを歓迎します。大きな変更の場合は、まずissueを開いて変更内容について議論してください。

サポート

問題が発生した場合は、GitHubのissuesページで報告してください。