Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

worktree.baseRef 設定（fresh | head）を追加：--worktree、EnterWorktree、エージェント分離ワークツリーをリモートの origin/<デフォルトブランチ> からブランチするか、ローカルの HEAD からブランチするかを選択できます。注意： デフォルトの fresh は EnterWorktree の基準を origin/<デフォルトブランチ> に戻します（2.1.128 以降はローカル HEAD でした）。未プッシュのコミットを新しいワークツリーに含めたい場合は worktree.baseRef: "head" を設定してください

原文（英語） ​

Added worktree.baseRef setting (fresh | head) to choose whether --worktree, EnterWorktree, and agent-isolation worktrees branch from origin/<default> or local HEAD. Note: the default fresh changes EnterWorktree's base back to origin/<default> (it has been local HEAD since 2.1.128) — set worktree.baseRef: "head" to keep unpushed commits in new worktrees

概要 ​

worktree.baseRef は、Claude Codeのワークツリー機能において、新しいワークツリーをリモートの最新状態（fresh）から作成するか、現在のローカルHEAD（head）から作成するかを設定するオプションです。fresh はリモートと同期したクリーンな状態から作業を始めたい場合に、head は現在の作業途中コミットを含めて継続したい場合に使用します。この設定は --worktree CLIフラグ、EnterWorktree ツール、エージェント分離ワークツリーすべてに適用されます。

基本的な使い方 ​

settings.json に worktree.baseRef を追加します。

json
{
  "worktree": {
    "baseRef": "head"
  }
}

デフォルト値は "fresh" です（設定なしの場合も fresh が使われます）。

実践例 ​

fresh モード（デフォルト）：常にリモートの最新から分岐 ​

json
{
  "worktree": {
    "baseRef": "fresh"
  }
}

fresh を使う場面：

  • リモートの main または master と同期した状態でタスクを始めたい
  • ローカルの作業状態に依存しないクリーンな環境が必要
  • CI/CDパイプラインやコードレビューでの利用
bash
# リモートの最新状態から新しいワークツリーを作成
claude --worktree
# → origin/main から新しいブランチが作成される

head モード：ローカルHEADから分岐（未プッシュコミットを保持） ​

json
{
  "worktree": {
    "baseRef": "head"
  }
}

head を使う場面：

  • フィーチャーブランチで作業中に、その変更をベースとして別の作業を並行したい
  • まだプッシュしていないコミットを新しいワークツリーにも含めたい
  • 現在の作業内容を引き継いでエージェントに作業させたい
bash
# ローカルのHEAD（未プッシュのコミットを含む）から分岐
claude --worktree
# → 現在の HEAD から新しいブランチが作成される

EnterWorktree ツールでの使用 ​

エージェントがサブタスクを並行実行する際にも worktree.baseRef が適用されます。

json
{
  "worktree": {
    "baseRef": "head"
  }
}
# Claude Code プロンプト
> 現在のフィーチャーブランチをベースに、テストの追加とドキュメント更新を並行して行ってください

エージェントは head モードの場合、現在のコミットを引き継いだワークツリーで作業を開始します。

プロジェクト設定での固定 ​

チーム全体で同じ挙動を使いたい場合は、プロジェクトの .claude/settings.json に設定します。

json
{
  "worktree": {
    "baseRef": "fresh"
  }
}

注意点 ​

  • 破壊的変更への注意：2.1.128から2.1.132の間は EnterWorktree のデフォルト基準がローカル HEAD でしたが、2.1.133以降は fresh（origin/<default>）に戻りました。この変更により既存のワークフローに影響が出る場合は、明示的に "head" を設定してください
  • fresh モードではリモートとの同期が必要なため、ネットワーク接続が必要になる場合があります
  • head モードで未プッシュのコミットが多い場合、新しいワークツリーとリモートの差分が大きくなります
  • エージェント分離ワークツリー（--dangerously-skip-permissions 等）にも同じ設定が適用されます

関連情報 ​