From 0562de387511d5941617dba2cb478bd84803ed01 Mon Sep 17 00:00:00 2001
From: Simon Cropp <simon.cropp@gmail.com>
Date: Fri, 21 Aug 2026 20:24:18 +1000
Subject: [PATCH] Fix P4Merge text argument order

p4merge takes its two files positionally as `left right`, so the file
named first is the one shown on the left. The text branches had them the
wrong way round: Left emitted `"{temp}" "{target}"` and Right emitted
`"{target}" "{temp}"`, the inverse of the binary branches directly below
them and of every other tool definition.

So a default launch, which uses Right, opened with the target on the
left, and setting DiffEngine_TargetOnLeft flipped it the wrong way. The
generated docs recorded the same inversion.

Introduced by ff21ccc2, which truncated the old four argument merge form
`base left right merged` to its first two arguments, leaving what had
been the base sitting in the left slot.
---
 docs/diff-tool.md                         | 12 ++++++------
 src/DiffEngine.Tests/diffTools.include.md | 12 ++++++------
 src/DiffEngine/Implementation/P4Merge.cs  |  7 +++++--
 3 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/docs/diff-tool.md b/docs/diff-tool.md
index 22d35f53..e251516f 100644
--- a/docs/diff-tool.md
+++ b/docs/diff-tool.md
@@ -716,11 +716,11 @@ DiffTools.UseOrder(DiffTool.P4Merge);
 
   * Example target on left arguments for text:
    ```
-   -C utf8-bom "tempFile.txt" "targetFile.txt"
+   -C utf8-bom "targetFile.txt" "tempFile.txt"
    ```
   * Example target on right arguments for text:
    ```
-   -C utf8-bom "targetFile.txt" "tempFile.txt"
+   -C utf8-bom "tempFile.txt" "targetFile.txt"
    ```
   * Example target on left arguments for binary:
    ```
@@ -740,11 +740,11 @@ DiffTools.UseOrder(DiffTool.P4Merge);
 
   * Example target on left arguments for text:
    ```
-   -C utf8-bom "tempFile.txt" "targetFile.txt"
+   -C utf8-bom "targetFile.txt" "tempFile.txt"
    ```
   * Example target on right arguments for text:
    ```
-   -C utf8-bom "targetFile.txt" "tempFile.txt"
+   -C utf8-bom "tempFile.txt" "targetFile.txt"
    ```
   * Example target on left arguments for binary:
    ```
@@ -762,11 +762,11 @@ DiffTools.UseOrder(DiffTool.P4Merge);
 
   * Example target on left arguments for text:
    ```
-   -C utf8-bom "tempFile.txt" "targetFile.txt"
+   -C utf8-bom "targetFile.txt" "tempFile.txt"
    ```
   * Example target on right arguments for text:
    ```
-   -C utf8-bom "targetFile.txt" "tempFile.txt"
+   -C utf8-bom "tempFile.txt" "targetFile.txt"
    ```
   * Example target on left arguments for binary:
    ```
diff --git a/src/DiffEngine.Tests/diffTools.include.md b/src/DiffEngine.Tests/diffTools.include.md
index 3f27245f..f6243f7b 100644
--- a/src/DiffEngine.Tests/diffTools.include.md
+++ b/src/DiffEngine.Tests/diffTools.include.md
@@ -581,11 +581,11 @@ DiffTools.UseOrder(DiffTool.P4Merge);
 
   * Example target on left arguments for text:
    ```
-   -C utf8-bom "tempFile.txt" "targetFile.txt"
+   -C utf8-bom "targetFile.txt" "tempFile.txt"
    ```
   * Example target on right arguments for text:
    ```
-   -C utf8-bom "targetFile.txt" "tempFile.txt"
+   -C utf8-bom "tempFile.txt" "targetFile.txt"
    ```
   * Example target on left arguments for binary:
    ```
@@ -605,11 +605,11 @@ DiffTools.UseOrder(DiffTool.P4Merge);
 
   * Example target on left arguments for text:
    ```
-   -C utf8-bom "tempFile.txt" "targetFile.txt"
+   -C utf8-bom "targetFile.txt" "tempFile.txt"
    ```
   * Example target on right arguments for text:
    ```
-   -C utf8-bom "targetFile.txt" "tempFile.txt"
+   -C utf8-bom "tempFile.txt" "targetFile.txt"
    ```
   * Example target on left arguments for binary:
    ```
@@ -627,11 +627,11 @@ DiffTools.UseOrder(DiffTool.P4Merge);
 
   * Example target on left arguments for text:
    ```
-   -C utf8-bom "tempFile.txt" "targetFile.txt"
+   -C utf8-bom "targetFile.txt" "tempFile.txt"
    ```
   * Example target on right arguments for text:
    ```
-   -C utf8-bom "targetFile.txt" "tempFile.txt"
+   -C utf8-bom "tempFile.txt" "targetFile.txt"
    ```
   * Example target on left arguments for binary:
    ```
diff --git a/src/DiffEngine/Implementation/P4Merge.cs b/src/DiffEngine/Implementation/P4Merge.cs
index 1a1770d5..cb562a04 100644
--- a/src/DiffEngine/Implementation/P4Merge.cs
+++ b/src/DiffEngine/Implementation/P4Merge.cs
@@ -3,11 +3,14 @@ static partial class Implementation
     public static Definition P4Merge()
     {
         var launchArguments = new LaunchArguments(
+            // p4merge takes the two files positionally as `left right`, so the target leads for
+            // target-on-left and the temp file leads for target-on-right. Same order for text and
+            // binary; only the encoding switch differs.
             Left: (temp, target) =>
             {
                 if (FileExtensions.IsTextFile(temp))
                 {
-                    return $"-C utf8-bom \"{temp}\" \"{target}\"";
+                    return $"-C utf8-bom \"{target}\" \"{temp}\"";
                 }
 
                 return $"\"{target}\" \"{temp}\"";
@@ -16,7 +19,7 @@ public static Definition P4Merge()
             {
                 if (FileExtensions.IsTextFile(temp))
                 {
-                    return $"-C utf8-bom \"{target}\" \"{temp}\"";
+                    return $"-C utf8-bom \"{temp}\" \"{target}\"";
                 }
 
                 return $"\"{temp}\" \"{target}\"";