外部マージツール

マージに競合がある場合、Diversion は競合している各ファイルに対して、選択したマージツールを実行できます。ツールがファイルの 2 つのバージョンをマージし、Diversion がその結果をマージに保存します。特別なマージツールが必要なファイルに使用してください。例:

Unity のシーンとプレハブは、UnityYAMLMerge (Unity Smart Merge) で
JSON、YAML、ソースコードは、mergiraf のような構文を理解するツールで
手動でマージしたい任意のファイルは、KDiff3 や Meld のようなビジュアルツールで

クイックスタート

マージツールを追加します。コンピューターごとに 1 回だけ必要です。この例は JSON ファイルをマージします:
dv merge-tool add --name mergiraf --pattern '\.json$' --cmd 'mergiraf merge $ANCESTOR $CURRENT $INCOMING -o $RESULT'

自分のツールでマージします:

dv merge <branch> --conflict_resolution merge-tool

Diversion はまずサーバー上でマージできるものをマージします。残った競合ごとに、ファイルにマッチするツールを実行します。最後まで解決されなかった競合は、Diversion アプリで解決してください。

Unity やその他のツールについては、例を参照してください。

仕組み

merge-tool の競合解決を指定して、マージ、更新、またはリバートを開始します。
Diversion はまずサーバー上でマージできるものをマージします。テキストファイルの異なる部分を両側が変更した場合、Diversion が自動的にマージするため、ツールは実行されません。
残った競合ごとに、Diversion はファイルパスにパターンがマッチする最初のツールを見つけます。ファイルの各バージョンを一時ファイルにダウンロードし、ツールを実行します。
ツールがすべての競合を解決すると、Diversion はマージを完了してコミットを作成します。
一部の競合が解決されなかった場合、マージは開いたままになります。残りは Diversion アプリで解決します。ツールが解決した競合は、解決済みのまま保持されます。

マージツールはあなたのコンピューター上で実行されます。ツールの設定はリポジトリではなく、このコンピューターのあなたのユーザーに保存されるため、チームメンバーはそれぞれ自分のツールをセットアップします。

マージツールをセットアップする

ツールをインストールする

マージツールをインストールし、そのプログラムへのフルパスを確認します。プログラムが PATH 上にある場合は、プログラム名だけで十分です。

ツールを Diversion に追加する

どのファイルをそのツールで処理し、どう実行するかを Diversion に指定します:

dv merge-tool add --name <name> --pattern '<regex>' --cmd '<command>'

すぐに使えるコマンドは例を参照してください。

セットアップを確認する

Diversion がマッチングする順序で、ツールを一覧表示します:

dv merge-tool

コマンドプレースホルダー

--cmd では、ファイルパスとして以下のプレースホルダーを使用します。Diversion はツールを実行する前に、これらを一時ファイルに置き換えます。

プレースホルダー	置き換えられる内容
`$ANCESTOR`	共通の祖先: どちらの側も変更する前のファイル
`$CURRENT`	自分の側: マージ先のブランチ、または `update` と `revert` の場合はワークスペース
`$INCOMING`	受け入れる側: マージするブランチまたはコミット、`update` の場合はブランチの最新バージョン、`revert` の場合はリバートされた内容
`$RESULT`	出力ファイル。ツールはマージ結果をここに書き込む必要があります。最初は空です。

コマンドのルール:

--cmd には $RESULT を含める必要があります。
コマンドはシェルを介さず直接実行されます。パイプ (|)、リダイレクト (>)、環境変数は機能しません。必要な場合は、手順をスクリプトにまとめ、そのスクリプトをコマンドに設定してください。
スペースを含むプログラムパスは二重引用符で囲んでください。
Mac と Linux では、--cmd の値全体を単一引用符で囲んでください。そうしないと、Diversion に届く前にシェルが $ANCESTOR などのプレースホルダーを置き換えてしまいます。

一時ファイルは元のファイル拡張子を保持します (例: local.prefab)。これは、UnityYAMLMerge や mergiraf のように、拡張子からマージ方法を決めるツールで重要です。

ファイルパターン

--pattern は正規表現です。Diversion はリポジトリ内のファイルパスに対してマッチングします。

パターン	マッチするもの
`\.prefab$`	`.prefab` で終わるファイル
`\.(unity\|prefab)$`	`.unity` または `.prefab` で終わるファイル
`Characters/.*\.prefab$`	任意の `Characters` フォルダー内の `.prefab` ファイル
`.*`	すべてのファイル

複数のツールがファイルにマッチする場合、リストの最初のツールが優先されます。dv merge-tool add は新しいツールをリストの末尾に追加します。順序は dv merge-tool で確認してください。どのツールにもマッチしないファイルは、Diversion アプリで解決するために残されます。

終了コードとビジュアルツール

デフォルトでは、git mergetool と同じように、ツールの終了コードが結果を決めます:

終了コード	結果
`0`	解決済み。Diversion は `$RESULT` の内容を保存します。
`1` から `127`	ツールが競合を未解決のまま残しました。Diversion アプリで解決します。
`128` 以上	ツールが失敗しました。

一部のビジュアルツールは、保存せずに閉じても 0 で終了します。そのようなツールには --no-trust-exit-code を追加してください。Diversion は終了コードを無視して $RESULT を確認します:

ツールが $RESULT に書き込み、ファイルに競合マーカー (<<<<<<<) がなければ、競合は解決済みです。
そうでない場合、Diversion は Was the merge successful? [y/n] と確認します。
CI ジョブなど、確認するターミナルがない場合、競合は未解決のままになります。

例

Unity Smart Merge (UnityYAMLMerge)

UnityYAMLMerge は Unity Editor に付属しています。Unity のシーン、プレハブ、その他の YAML アセットをマージします。テキストとして保存されたアセットでのみ機能するため、先に Asset Serialization Mode を Force Text に設定してください (Unity ベストプラクティスを参照)。 6000.0.23f1 はお使いの Unity バージョンに変更してください:

dv merge-tool add --name unity-yaml \
  --pattern '\.(unity|prefab|asset|mat|anim|controller)$' \
  --cmd '"/Applications/Unity/Hub/Editor/6000.0.23f1/Unity.app/Contents/Tools/UnityYAMLMerge" merge -p $ANCESTOR $INCOMING $CURRENT $RESULT'

dv merge-tool add --name unity-yaml --pattern "\.(unity|prefab|asset|mat|anim|controller)$" --cmd "\"C:\Program Files\Unity\Hub\Editor\6000.0.23f1\Editor\Data\Tools\UnityYAMLMerge.exe\" merge -p $ANCESTOR $INCOMING $CURRENT $RESULT"

UnityYAMLMerge はファイルを base、remote、local、merged の順序で受け取ります。これは他の多くのツールとは異なります。

Windows では、この例を Command Prompt で実行してください。PowerShell はバージョンによって引数内の引用符の扱いが異なるため、引用符で囲んだプログラムパスが壊れることがあります。

mergiraf (JSON、YAML、コード)

mergiraf は多くのファイルタイプの構文を理解します。1 つの JSON オブジェクトに追加された 2 つの新しいキーのように、同じ行に対する 2 つの変更をマージできます。

dv merge-tool add --name mergiraf \
  --pattern '\.(json|ya?ml|toml)$' \
  --cmd 'mergiraf merge $ANCESTOR $CURRENT $INCOMING -o $RESULT'

KDiff3

KDiff3 は、マージできるものは自動でマージします。あなたの対応が必要な競合が残ったときにだけウィンドウを開きます。

dv merge-tool add --name kdiff3 \
  --pattern '\.(ini|cfg)$' \
  --cmd 'kdiff3 $ANCESTOR $CURRENT $INCOMING -o $RESULT --auto'

Meld

Meld は保存せずに閉じても 0 で終了するため、--no-trust-exit-code を追加します:

dv merge-tool add --name meld \
  --pattern '\.txt$' \
  --cmd 'meld $CURRENT $ANCESTOR $INCOMING -o $RESULT' \
  --no-trust-exit-code

マージツールで競合を解決する

CLI から

dv merge、dv update、または dv revert に --conflict_resolution merge-tool を追加します:

dv merge feature/new-level --conflict_resolution merge-tool
dv update --conflict_resolution merge-tool
dv revert <commit_id> --conflict_resolution merge-tool

ツールが 1 つもセットアップされていない場合、コマンドはマージを開始する前に停止します。ツールは競合を 1 つずつ処理します。その後、CLI はファイルごとの結果を出力します:

merge encountered conflicts, resolving with external merge tools
Resolved 1 conflict(s) with external tools:
  - Assets/Prefabs/Player.prefab (unity-yaml)
Skipped 1 conflict(s), left for manual resolution:
  - Assets/Textures/Hero.psd: no merge tool is configured for this file
Not all conflicts were resolved. Please resolve the rest manually:
https://app.diversion.dev/repo/<repo_id>/merges/<merge_id>

結果	意味	対応
Resolved	ツールがファイルをマージし、Diversion が結果をマージに保存しました。	不要です。
Skipped	ファイルにマッチするツールがない、ツールが競合を未解決のまま残した、または `n` と回答した場合です。	出力されたリンクを開き、Diversion アプリでファイルを解決します。
Failed	ツールが起動しなかった、終了コード `128` 以上で終了した、またはファイルのダウンロードやアップロードが失敗した場合です。	`dv merge-tool` でツールを確認してから、Diversion アプリでファイルを解決します。

Diversion は、すべての競合が解決されたときにのみマージを完了します。いずれかの競合が Skipped または Failed になった場合、マージは開いたままになり、コマンドはゼロ以外の終了コードで終了するため、スクリプトから検知できます。

マージツールを管理する

dv merge-tool            # ツールをマッチング順に一覧表示
dv merge-tool add ...    # ツールを追加、または同名のツールを更新
dv merge-tool -d <name>  # ツールを削除

すでに存在する名前でツールを追加すると、Diversion はそのツールを置き換え、リスト内の位置を保持します。 Diversion はツールを ~/.diversion/merge_tools.json (Windows では %USERPROFILE%\.diversion\merge_tools.json) に保存します。ファイルを直接編集する代わりに、dv merge-tool で変更してください。すべてのオプションは dv merge-tool を参照してください。

トラブルシューティング

メッセージ	原因と対処
`no merge tools configured`	ツールがありません。`dv merge-tool add` で追加してください。
`no merge tool is configured for this file`	ファイルパスにマッチするパターンがありません。`dv merge-tool` でパターンを確認してください。
`the tool exited with code N and left the conflict unresolved`	ツールが自力でファイルをマージできませんでした。Diversion アプリで解決してください。
`the tool wrote an empty file while a side still had content`	ツールが結果を `$RESULT` に書き込みませんでした。たとえば `-o $RESULT` のように、コマンドが `$RESULT` に書き込むことを確認してください。
`the two sides differ only in metadata`	ファイルの内容は同じですが、ファイル名など他の何かが変更されています。マージツールでは対応できません。Diversion アプリで解決してください。
`failed to run merge tool`	Diversion がプログラムを起動できませんでした。プログラムへのフルパスを使用し、スペースが含まれる場合は二重引用符で囲んでください。
ビジュアルツールで、保存せずに閉じてもファイルが解決済みになる	`--no-trust-exit-code` を付けてツールを追加し直してください。

はじめに

AI

コラボレーション

Unreal Engine で使う

Unity で使う

連携

リファレンス

CLI リファレンス

変更履歴

クイックスタート

仕組み

マージツールをセットアップする

コマンドプレースホルダー

ファイルパターン

終了コードとビジュアルツール

例

Unity Smart Merge (UnityYAMLMerge)

mergiraf (JSON、YAML、コード)

KDiff3

Meld

マージツールで競合を解決する

CLI から

マージツールを管理する

トラブルシューティング

関連

​クイックスタート

​仕組み

​マージツールをセットアップする

​コマンドプレースホルダー

​ファイルパターン

​終了コードとビジュアルツール

​例

​Unity Smart Merge (UnityYAMLMerge)

​mergiraf (JSON、YAML、コード)

​KDiff3

​Meld

​マージツールで競合を解決する

​CLI から

​マージツールを管理する

​トラブルシューティング

​関連

クイックスタート

仕組み

マージツールをセットアップする

コマンドプレースホルダー

ファイルパターン

終了コードとビジュアルツール

例

Unity Smart Merge (UnityYAMLMerge)

mergiraf (JSON、YAML、コード)

KDiff3

Meld

マージツールで競合を解決する

CLI から

マージツールを管理する

トラブルシューティング

関連