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]])

フックコマンド

トラブルシューティング

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ページで報告してください。