config.md: advertise diffedit3 as an alternative to meld-3 diff e…

…ditor

This is instead of #3292, which would make
`diffedit3` built into `jj`. I still have some hope of eventually making
`diffedit3` into the default diff editor that is available without any
configuration, which probably requires building it into `jj`, but this may not
happen, and it wouldn't hurt to test `diffedit3` first. Some examples of
concerns (see also the discussion in that PR):

- It is only a guess on my part that this would make a good default. The editor
might not be polished enough, and most users are not used to 3-pane diff
editing. I think most users would like it if they tried it, but this might be
plain wrong.

- There are concerns about adding a heavyweight dependency on `jj`. While I
tried to make it as lightweight as possible, it still unavoidably includes a web
server.

- There may be ways to bundle `diffedit3` with `jj` without combining them in a
single binary.

cli/src/config/merge_tools.toml

@@ -12,6 +12,26 @@ program="meld"
 # If using this as a template, note that `$output` is repeated twice below
 edit-args = ["$left", "$output", "$right", "-o", "$output"]
 
+[merge-tools.diffedit3]
+program="diffedit3"
+# 17376 is a verified random number, as in https://xkcd.com/221/ :). I am trying
+# to avoid 8000 or 8080 in case those, more commonly used, port numbers are used
+# for something else.
+#
+# We use a random port as a fallback if all 5 of the preferred port numbers are
+# busy.
+edit-args = ["$left", "$right", "$output", "--port", "17376-17380", "--port", "0"]
+
+[merge-tools.diffedit3-ssh]
+program="diffedit3"
+# 17376 is a verified random number, as in https://xkcd.com/221/ :). I am trying
+# to avoid 8000 or 8080 in case those, more commonly used, port numbers are used
+# for something else.
+#
+# We do NOT use a random port as a fallback since we recommend that the user
+# configure SSH to forward these 5 ports
+edit-args = ["$left", "$right", "$output", "--port", "17376-17380", "--no-browser"]
+
 [merge-tools.vimdiff]
 program = "vim"
 # `-d` enables diff mode. `-f` makes vim run in foreground even if it starts a GUI.

docs/config.md

@@ -481,17 +481,74 @@ merge-tools.kdiff3.edit-args = [
 
 ### Experimental 3-pane diff editing
 
-The special `"meld-3"` diff editor sets up Meld to show 3 panes: the sides of
-the diff on the left and right, and an editing pane in the middle. This allow
-you to see both sides of the original diff while editing. If you use
-`ui.diff-editor = "meld-3"`, note that you can still get the 2-pane Meld view
-using `jj diff --tool meld`.
-
-To configure other diff editors, you can include `$output` together with `$left`
-and `$right` in `merge-tools.TOOL.edit-args`. `jj` will replace `$output` with
-the directory where the diff editor will be expected to put the result of the
-user's edits. Initially, the contents of `$output` will be the same as the
-contents of `$right`.
+We offer two special "3-pane" diff editor configs:
+
+- `meld-3`, which requires installing [Meld](https://meldmerge.org/), and
+- `diffedit3`, which requires installing [`diffedit3`](https://github.com/ilyagr/diffedit3/releases).
+
+`Meld` is a graphical application that is recommended, but can be difficult to
+install in some situations. `diffedit3` is designed to be easy to install and to
+be usable in environments where Meld is difficult to use (e.g. over SSH via port
+forwarding). `diffedit3` starts a local server that can be accessed via a web
+browser, similarly to [Jupyter](https://jupyter.org/).
+
+There is also the `diffedit3-ssh` which is similar to `diffedit3` but does not
+try to open the web browser pointing to the local server (the URL
+printed to the terminal) automatically. `diffedit3-ssh` also always uses ports in between
+17376-17380 and fails if they are all busy. This can be useful when working
+over SSH. Open the fold below for more details of how to set that up.
+
+<details>
+<summary> Tips for using `diffedit3-ssh` over SSH </summary>
+
+To use `diffedit3` over SSH, you need to set up port forwarding. One way to do
+this is to start SSH as follows (copy-paste the relevant lines):
+
+```shell
+ssh -L 17376:localhost:17376 \
+    -L 17377:localhost:17377 \
+    -L 17378:localhost:17378 \
+    -L 17379:localhost:17379 \
+    -L 17380:localhost:17380 \
+    myhost.example.com
+```
+
+`diffedit3-ssh` is set up to use these 5 ports by default. Usually, only the
+first of them will be used. The rest are used if another program happens to use
+one of them, or if you run multiple instances of `diffedit3` at the same time.
+
+Another way is to add a snippet to `~/.ssh/config`:
+
+```
+Host myhost
+    User     myself
+    Hostname myhost.example.com
+    LocalForward 17376 localhost:17376
+    LocalForward 17377 localhost:17377
+    LocalForward 17378 localhost:17378
+    LocalForward 17379 localhost:17379
+    LocalForward 17380 localhost:17380
+```
+
+With that configuration, you should be able to simply `ssh myhost`.
+
+</details>
+
+
+Setting either `ui.diff-editor = "meld-3"` or `ui.diff-editor = "diffedit3"`
+will result in the diff editor showing 3 panes: the diff on the left and right,
+and an editing pane in the middle. This allow you to see both sides of the
+original diff while editing.
+
+If you use `ui.diff-editor = "meld-3"`, note that you can still get the 2-pane
+Meld view using `jj diff --tool meld`. `diffedit3` has a button you can use to
+switch to a 2-pane view.
+
+To configure other diff editors in this way, you can include `$output` together
+with `$left` and `$right` in `merge-tools.TOOL.edit-args`. `jj` will replace
+`$output` with the directory where the diff editor will be expected to put the
+result of the user's edits. Initially, the contents of `$output` will be the
+same as the contents of `$right`.
 
 ### `JJ-INSTRUCTIONS`