ファイルとブランチの操作

CodeDAG の実行結果とプロジェクトの設定は、どちらも通常の Git ブランチとファイルとして、手元のコンピューターに残ります。ほとんどのことは cdg コマンドで済みますが、いくつかは Git を直接使うか、ファイルシステム上で自分で処理する必要があります。結果の確認、メインブランチへのマージ、ブランチのクリーンアップの手順全体は、仕上げ、マージ、クリーンアップを参照してください。

スナップショットから一部の変更を取り出す

分離ブランチモードでは、キャンセル、見送り、やり直しになったタスクと、キャンセルまたは見送りになったワークフロー全体の結果は、デフォルト（--code snapshot）でスナップショットブランチに保存されます。このブランチは、自分で削除するまでリポジトリに残り続けます。タスクのスナップショットには、タスク自身の変更だけでなく、開始時点のコードと、マージされた上流の結果も含まれています。そのため、取り出す前にまずタスクブランチと比較して、どれがこのタスクによる変更かを見分けてから、必要な部分を Git で取り出します。スナップショットブランチがある理由は、結果に納得できないときの備えを参照してください。

スナップショットに保存される内容

スナップショットブランチには 2 種類あります。1 つのタスクの結果を保存するものと、ワークフロー全体の結果を保存するものです。

ブランチ名に入るタイトルは小文字に変換され、スペースなどブランチ名に使えない文字は - に置き換えられます。日時はこのコンピューターのローカル時刻で、秒まで含みます。たとえば、ワークフロー add-helpers のタスク 2（タイトルは Add mul helper）が 2026-09-30 11:39:55 にやり直しを求められた場合、スナップショットブランチは cdg/add-helpers/snapshots/t2-add-mul-helper-20260930-113955 になります。

ブランチ名の <ワークフロー名> は、ワークフローファイルの .codedag/dags/ からの相対パスから決まります。たとえば、サブディレクトリにある team-a/build.yaml は team-a_build になります。ルールはファイルの置き場所と形式を参照してください。はっきりしないときは、cdg dag status の出力にある Integration Branch で確認してください。

次の場合は、取り出せるスナップショットがありません。

• 保存する変更がない場合： スナップショットブランチは作られません。
• レビューで --code discard を指定した場合： 変更はそのまま破棄され、あとから取り出すことはできません。
• タスクレベルの cancel または defer で --code commit を指定した場合： 変更はタスクブランチにコミットされ、スナップショットブランチは別に作られません。
• 共有ワークスペースモードの場合： スナップショットはなく、キャンセルされたタスクが書いたファイルはワークスペースに残ります。共有ワークスペースモードでは、レビューはどう変わりますかを参照してください。

レビューアクションごとに --code に指定できる値とデフォルト値は、タスクレベルのオプションの表を参照してください。

スナップショットブランチを見つける

スナップショットブランチの名前はどれも cdg/<ワークフロー名>/snapshots/ で始まるので、git branch --list で一覧表示できます。比較には対応するタスクブランチも必要で、その名前は cdg/<ワークフロー名>/t<タスク ID>- で始まります。

# リポジトリにある、すべてのワークフローのスナップショットブランチを一覧表示する
git branch --list 'cdg/*/snapshots/*'

# ワークフロー add-helpers のタスク 2 のタスクブランチを見つける
git branch --list 'cdg/add-helpers/t2-*'

1 つのタスクにスナップショットブランチが複数あることもあります。たとえば、一度やり直したあとでキャンセルされた場合です。名前の末尾の日時で区別してください。再実行したことのあるワークフローでは、ブランチ名のワークフロー名に日時のサフィックスが付きます。たとえば cdg/add-helpers-20260930-105924/snapshots/... で、これも 1 つ目のコマンドで一覧表示されます。タスクが branchName でブランチ名を指定している場合、タスクブランチはその名前になりますが、スナップショットブランチはこの場合も cdg/<ワークフロー名>/snapshots/ で始まります。

worktree のレプリカはプライマリリポジトリと同じブランチを共有するため、プライマリリポジトリからすべてのスナップショットブランチが見えます。clone のレプリカは、それぞれ独自のブランチを持ちます。ある clone で実行されたタスクのタスクブランチとスナップショットブランチは、どちらもその clone にしかありません。その clone の中でそのまま比較して取り出すことも、先に 2 本のブランチをプライマリリポジトリにフェッチすることもできます。

git fetch ../my-app-clone-1 <スナップショットブランチ>:<スナップショットブランチ> <タスクブランチ>:<タスクブランチ>

タスクがどの clone で実行されたかわからないときは、各 clone でスナップショットブランチを一覧表示してみてください。ワークフローのスナップショットは、統合ブランチがあるワークスペースに作られます。通常はプライマリリポジトリです。

タスク自身の変更だけを見る

タスクブランチとスナップショットブランチをドット 3 つの記法で比較すると、このタスク自身の変更だけが得られます。

# タスクが変更したファイル
git diff --stat cdg/add-helpers/t2-add-mul-helper...cdg/add-helpers/snapshots/t2-add-mul-helper-20260930-113955

# スナップショットにある、このタスクのコミット
git log --oneline cdg/add-helpers/t2-add-mul-helper..cdg/add-helpers/snapshots/t2-add-mul-helper-20260930-113955

ドット 3 つの git diff は、2 本のブランチが分かれた地点を起点にします。タスクがキャンセルまたは見送りになったあと、タスクブランチはクリーンベースラインで止まっています。やり直しを求められた場合も、新しいセッションはクリーンベースラインから始まります。そのため、2 本のブランチは必ずクリーンベースラインで分かれ、比較結果にはタスク自身の変更だけが含まれます。スナップショットを直接 main と比較すると、上流のタスクの変更も含まれてしまいます。

ワークフローのスナップショットも、比較対象を統合ブランチに変えて、同じ方法で比較します。ワークフローがキャンセルまたは見送りになったあと、統合ブランチは今回のワークフローのベースに戻っているため、比較結果は今回の実行によるすべての変更になります。

git diff --stat cdg/add-helpers/integration...cdg/add-helpers/snapshots/dag-review-20260930-114306

必要な部分を取り出す

取り出す前に、まずこのワークフローのレビューが終了していることを確認し、それから変更を入れたいブランチ（main や新しいブランチなど）に切り替えます。ワークフローがまだキューにある間は、プライマリリポジトリもレプリカも、そのワークフローに使われる可能性があります。そこに未コミットの変更を残すと、そのあとで開始されるタスクや、統合ブランチへのマージのステップが、ワークスペースがクリーンでないために on-hold で止まります。ワークスペースに未コミットの変更があるを参照してください。

# ファイル全体を取り出す：現在のファイルをスナップショットのバージョンで置き換える
git checkout <スナップショットブランチ> -- src/mul.js

# あるファイルに対するタスクの変更だけを取り出し、現在のファイルに適用する
git diff --binary <タスクブランチ>...<スナップショットブランチ> -- README.md | git apply --3way

# タスク自身の変更をすべて取り出す
git diff --binary <タスクブランチ>...<スナップショットブランチ> | git apply --3way

1 つ目の方法で得られるのは、スナップショットにあるそのファイルの内容全体です。上流のタスクも同じファイルを変更していた場合は、その変更も一緒に入ってきます。あとの 2 つの方法は、ファイルにあるほかの内容を残したまま、タスク自身の変更だけを適用します。コンフリクトが起きた場合は、--3way がファイルにコンフリクトマーカーを残すので、自分で解決します。コンフリクトがなければ、取り出した変更はすべてステージ済みになっているので、確認してから自分でコミットします。コマンドの --binary は、画像やフォントのようなバイナリファイルの変更もパッチに含めるためのものです。これがないと、タスクがバイナリファイルを変更していた場合に git apply が失敗します。元のコミットごと取り出したい場合は、git cherry-pick を使って、前の節の git log で表示されたコミットを選んで取り込むこともできます。

ワークフローのスナップショットに保存されているのは、結果一式です。すべてを取り出したい場合は、統合ブランチをマージするときと同じようにマージします。たとえば git merge cdg/add-helpers/snapshots/dag-review-20260930-114306 を実行します。一部だけが必要な場合は、上の方法でファイルごとに取り出します。

指定したタスクブランチ名を使う

あるタスクの結果を決まった名前のブランチに残したい場合は、そのタスクに branchName を書きます。たとえば、あとでそのブランチだけをプッシュしてプルリクエストを作成したい場合です。CodeDAG はこの名前をそのまま使い、cdg/ プレフィックスは付けません。branchName を使えるのは分離ブランチモードだけです。名前が満たすべき条件と、使えない名前は、branchName を参照してください。

tasks:
  - id: 1
    title: 検索APIを実装
    branchName: feature/search-api
    prompt: docs/plans/search.md に沿って検索 API を実装し、対応するユニットテストを追加してください。

名前を固定する代わりに、既存のブランチと同じ名前は使えなくなります。自動で名前が付くブランチは、前回のブランチが残っていると名前に日時が付き、重複を避けます。一方、branchName で指定した名前は変わりません。同じ名前のブランチがすでにある場合、検証で branch-name-conflict の警告が出ます。対処せずに投入すると、ワークフローの実行がこのタスクまで進んだところで、タスクは on-hold で止まります。警告には、その名前を何が占有しているかと、それに応じた対処方法が書かれています。占有が解消されれば、名前を変えずに、元の名前をそのまま使い続けられます。

占有には 2 種類あります。1 つは、ワークスペースにある同じ名前のローカルブランチで、自分で削除するか名前を変更します。

# 前回の結果を残しておきたい場合：名前を変更する
git branch -m feature/search-api feature/search-api-prev

# もう必要ない場合：削除する
git branch -D feature/search-api

ブランチがいずれかのワークスペースでチェックアウトされている間は、Git でそのブランチを削除できません。先に、そのワークスペースを別のブランチに切り替えてください。clone をレプリカにしている場合は、各 clone にある同じ名前のブランチを、それぞれ処理する必要があります。

もう 1 つは、clone をレプリカにしている場合にだけ起こります。CodeDAG は、このコンピューター上の同期リポジトリを介して、ワークスペースの間でブランチを受け渡します。プライマリリポジトリと各 clone にある codedag-mirror という名前のリモートは、この同期リポジトリを指しています。前回このタスクをキャンセルまたは見送りにしたときに --code commit を使っていると、この名前が同期リポジトリに残ります。これは cdg branch release で解放します。codedag-mirror リモートを自分で操作する必要はありません。

cdg branch release feature/search-api

キューにあるワークフローがまだ使っているブランチと、スナップショットブランチは解放できません。条件の全体は、cdg branch release を参照してください。

タスクがすでに同じ名前のブランチのために on-hold で止まっている場合は、占有が解消されてから cdg task recover で復旧します。調査の手順はブランチの問題を参照してください。古いブランチを処理しても branch-name-conflict が表示される場合は、ワークフローファイルで新しい branchName に変えるか、branchName を削除して、CodeDAG に自動で名前を付けさせます。

ワークフローと共有設定を別に保存する

ワークフローファイルとプロジェクト設定は、どちらもプライマリリポジトリのルートにある .codedag/ に置かれています。このディレクトリはプロジェクトのサイドカーリポジトリで、プロジェクトリポジトリとは独立した Git リポジトリです。そのため、これらのファイルは .codedag の中で別にコミットする必要があり、プロジェクトリポジトリのコミットには含まれません。

コミットには、通常の git コマンドを使います。cdg init が生成する .codedag/.gitignore は、あらかじめ local/ を除外しています。ローカル設定 settings.local.jsonc とログは、どちらもこのディレクトリにあります。そのため、git add -A で追加されるのは、dags/ にあるワークフローファイルや共有設定 settings.jsonc のような、共有できるファイルだけです。

cd .codedag
git add -A
git commit -m "Add search-api workflow"

CodeDAG がこのリポジトリの中でコミット、プッシュ、プルをすることはありません。いつ保存するかは自分で決めます。リモートにプッシュしてチームと同期する方法は、.codedag をリモートにプッシュするを参照してください。

ログファイルの場所

ワークフローファイル 1 つにつきログファイルが 1 つあり、プライマリリポジトリの .codedag/local/logs/ に置かれます。ログのパスは、ワークフローファイルの .codedag/dags/ からの相対的な位置に合わせて決まり、拡張子が .log に変わります。.codedag/dags/add-helpers.yaml のログは .codedag/local/logs/add-helpers.log です。サブディレクトリにある .codedag/dags/team-a/build.yaml のログは、同じ名前のサブディレクトリに書かれ、.codedag/local/logs/team-a/build.log になります。ディレクトリ名とファイル名は、どちらも元の大文字・小文字と表記のままです。タスクがレプリカで実行された場合も、ログはプライマリリポジトリのこのディレクトリに書かれます。

同じワークフローのログは、何回目の実行のものでも、すべて同じファイルに追記されます。cdg dag logs と cdg task logs が読み取るのは、このファイルです。ログの各行は、[Task 2] [2026-09-30 11:38:20] のように、タスク ID と時刻で始まります。ファイルを直接開くときは、grep や less のようなツールを使って、タスクや時刻で検索できます。

ログは local/ にあるため、.codedag のバージョン管理の対象にはならず、このコンピューターにだけ残ります。ログを見るためのコマンドとオプションは、cdg dag logs と cdg task logs を参照してください。古いログが不要になったら、ファイルをそのまま削除してかまいません。

ブランチをクリーンアップする、またはワークスペースを取り除く

ワークフローのレビューが終了し、必要な結果もマージし終えたら、ワークフローが残した cdg/<ワークフロー名>/ のブランチ、ログファイル、使わなくなったレプリカは、どれもクリーンアップできます。手順はブランチとワークスペースをクリーンアップするを参照してください。スナップショットブランチもこれらのブランチに含まれ、削除すると、その中の変更はもう取り出せません。削除する前に、スナップショットから一部の変更を取り出すに沿って、残しておきたい内容がないことを確認してください。