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

…ditor

This is instead of martinvonz#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,20 @@ 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.
+edit-args = ["$left", "$right", "$output", "--port-range", "17376", "17380"]
+
+[merge-tools.diffedit3-nobrowser]
+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"]
+
 [merge-tools.vimdiff]
 program = "vim"
 # `-d` enables diff mode. `-f` makes vim run in foreground even if it starts a GUI.

docs/config.md

@@ -472,17 +472,36 @@ 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 applicatication 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-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.
+
+<!-- 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,
+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`