ComfyUI WorkflowをGitで管理する｜JSON差分・モデル・Node Versionの扱い

ComfyUIのworkflowをGitで管理するなら、リポジトリに入れるのはworkflow JSON・設定・依存の台帳までで、model本体と生成物は外に置きます。workflow JSONにはmodelファイルもcustom nodeも含まれないため、「何があれば再現できるか」を台帳として一緒にcommitすることが管理の中心になります。

情報確認日：2026年8月22日（日本時間）

結論：小さいテキストはGit、大きいバイナリは台帳だけ

Gitで管理するものは何か

公式ドキュメントは、workflowをJSONとして保存・共有できる一方で、「workflowにはmodelファイル・入力素材・custom node packageは含まれない」と明記しています。つまりJSONだけをcommitしても、他のPCで同じ結果は出ません。管理対象は「JSON＋再現に必要な情報」のセットです。

線引きの基準は「テキストで、差分に意味があり、数MB以内」です。modelは数GBのバイナリで差分に意味がなく、生成画像は同じworkflowから再生成できます。どちらもGitの履歴を重くするだけで、管理の価値がありません。

# .gitignore
models/
output/
input/*
!input/.gitkeep
*.safetensors
*.ckpt
*.png
*.mp4

Workflow JSONをどう置くか

フォルダと命名の規約を先に決めると、後から探す時間が減ります。この記事では「用途／名前／版」の順で整理します。

comfy-workflows/
├── README.md
├── workflows/
│   ├── portrait/
│   │   ├── portrait-sdxl.json            # GUI 形式（UI で開く用）
│   │   ├── portrait-sdxl.api.json        # API 形式（スクリプト実行用）
│   │   └── README.md                     # 目的・必要 model・既知の制約
│   └── product-photo/
├── models.csv                            # model 台帳
├── custom-nodes.lock.json                # custom node manifest
├── extra_model_paths.yaml.example
└── releases/
    └── v1.2.0/
        ├── samples/                      # sample 画像の保存先（Git 管理外でもよい）
        └── benchmark.csv

• ファイル名は小文字・ハイフン区切りにし、日本語と空白を避ける（スクリプトから扱いやすい）
• GUI形式とAPI形式を両方置く場合は.api.jsonのように拡張子で区別する
• 版はファイル名ではなくGitのtagで表す。portrait-v2-final.jsonのような名前を増やさない
• workflowごとのREADMEに「何を作るworkflowか」「必要なmodel」「想定解像度」「既知の制約」を書く

ファイル名に版を入れない理由は、同じworkflowの履歴をGitが持っているからです。名前で版を表すと、どれが最新かをGitの外で管理することになります。

Model本体はなぜ入れないのか

modelをGitに入れない代わりに、「どこから・どのファイルを・どのlicenseで・どこに置いたか」を台帳にします。hashを残すのは、同名で中身の違うファイルを見分けるためです。

# models.csv
kind,filename,source_url,sha256,license,commercial_use,place_under,checked_at,note
checkpoint,example-base.safetensors,https://example.com/model-page,<sha256>,<license name>,yes/no,models/checkpoints,2026-09-20,
lora,example-style.safetensors,https://example.com/lora-page,<sha256>,<license name>,yes/no,models/loras,2026-09-20,trigger word: ...
vae,example-vae.safetensors,https://example.com/vae-page,<sha256>,<license name>,yes/no,models/vae,2026-09-20,

# hash の取り方（Linux / macOS）
shasum -a 256 models/checkpoints/example-base.safetensors

台帳があれば、別のPCで「どのファイルをどこに置けば動くか」が分かります。公式ドキュメントが案内するComfyUI/models/配下の配置（checkpoints・loras・vaeなど）をplace_under列に書いておくと、配置の迷いも消えます。

Custom Nodeとversionをどう残すか

custom nodeはそれぞれ独立したGitリポジトリで、更新で挙動が変わります。workflowが動いた時点のnode一覧とversionを、manifestとしてcommitします。

{
  "comfyui": {
    "commit": "<git rev-parse HEAD の値>",
    "python": "3.12.x",
    "torch": "X.Y.Z+cu130"
  },
  "custom_nodes": [
    {
      "name": "example-node-pack",
      "repo": "https://github.com/example/example-node-pack",
      "version": "1.4.2",
      "commit": "<commit hash>",
      "requirements": ["somelib>=2.0"]
    }
  ],
  "recorded_at": "2026-09-20"
}

versionはcustom nodeのpyproject.tomlにある値、commitはそのフォルダでgit rev-parse HEADを実行した値です。両方残すのは、Registry経由で入れた場合とgit cloneで入れた場合で、手元にある情報が違うからです。

このmanifestから環境を復元する作業そのものは、Snapshot機能を扱う別記事に任せます。この記事の役割は「復元に必要な情報を、workflowと同じcommitに残す」ことです。nodeを自分で開発している場合は、そのnodeのversionとtagの付け方をカスタムノードのCI/CDに合わせておくと、manifestのversionがそのまま使えます。

JSON差分をどう読みやすくするか

ComfyUIが保存するJSONは、UIでnodeを少し動かしただけでも座標が変わり、差分に「意味のない行」が混ざります。commit前に同じ規則で整形すると、少なくともキーの順序や空白による差分は消えます。座標の差分まで消すかどうかは、次の検証で決めます。

# commit 前に、キーをソートして 2 スペースで整形する
jq --indent 2 -S . workflows/portrait/portrait-sdxl.json > tmp.json && mv tmp.json workflows/portrait/portrait-sdxl.json

整形を自動化するなら、Gitのpre-commit hookやタスクランナーに同じコマンドを入れ、手で実行するかどうかで結果が変わらないようにします。

workflowを1か所変えてgit diffで変更nodeを特定する

整形の効果と差分の読み方は、実際に1か所だけ変えて確かめます。手順は次のとおりです。

1. 整形済みのJSONをcommitしておく
2. UIで開き、KSamplerのstepsなど値を1つだけ変えて上書き保存する（nodeは動かさない）
3. 同じ整形コマンドを通し、git diffを見る
4. 次に、nodeを少し移動しただけで保存し、同じくgit diffを見る

--- a/workflows/portrait/portrait-sdxl.json
+++ b/workflows/portrait/portrait-sdxl.json
@@
       "type": "KSampler",
       "widgets_values": [
         12345,
         "fixed",
-        25,
+        30,
         7,
         "euler",

2の差分がこのように値の行だけなら、整形は効いています。差分の中で変わった行の近くに"type"があれば、どのnodeの値かが分かります。保存したJSONを開き、nodeごとの値がどのキーに入っているかは自分の環境のファイルで確認してください（形式はComfyUIの更新で変わることがあります）。

「nodeを移動のみ」で座標の差分が多く残り、それが邪魔なら、座標キーを落とした比較用コピーを別に作る方法もあります。ただし元のJSONから座標を消すとUIでの配置が失われるため、commitするファイルからは消さないでください。

生成物と検証条件をどう紐づけるか

workflowの「この版は正しく動いた」という事実は、JSONだけでは残りません。tagを打つたびに、sample画像・seed・検証CSVをその版に紐づけます。

出力PNGにはworkflowとpromptが埋め込まれる仕様なので、sample画像そのものが「その版の証跡」にもなります。ただし画像編集ソフトで開いて保存し直すとmetadataが失われることがあるため、sampleは加工せずに保存します。

git add workflows models.csv custom-nodes.lock.json
git commit -m "portrait-sdxl: steps 25→30、sample と benchmark を更新"
git tag v1.2.0
git push origin main --tags

API形式のJSONをcommitしておけば、comfy run --workflowのようにCLIから同じworkflowを実行でき、検証の自動化にもつながります。CLIの使い方はComfy CLIの使い方を参照してください。

よくある質問

まとめ

ComfyUI workflowのGit管理は、JSON・設定・台帳というテキストだけをリポジトリに入れ、model本体と生成物は外に置く線引きから始まります。modelはURL・hash・licenseの台帳に、custom nodeはname・version・commitのmanifestに置き換えます。

commit前の整形で差分を意味のある行に絞り、1か所変えてgit diffで変更nodeを特定できるかを確かめてください。tagごとにsample・seed・検証CSVを紐づければ、「この版は動いた」という事実まで含めて履歴になります。