(TO BE SQUASHED) ssh forwarding, etc, diffedit3 0.4

cli/src/config/merge_tools.toml

@@ -14,17 +14,23 @@ 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.
-edit-args = ["$left", "$right", "$output", "--port-range", "17376", "17380"]
+# 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-nobrowser]
+[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.
-edit-args = ["$left", "$right", "$output", "--port-range", "17376", "17380", "--no-browser"]
+# 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"

docs/config.md

@@ -490,12 +490,48 @@ 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-nobrowser` which is just like `diffedit3` but does
-not try to open the web browser for you pointing to the local server (the URL
-printed to the terminal) automatically. This can be useful when working over
-SSH.
+There is also the `diffedit3-ssh` which is similar to `diffedit3` but does not
+try to open the web browser for you pointing to the local server (the URL
+printed to the terminal) automatically and 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>
 
-<!-- TODO(ilyagr): Explain what port it runs on, give example SSG commands -->
 
 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,