From 6bfd9e3c3ceae5b716a95acfcfdc76e76704e330 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sat, 6 Apr 2024 15:47:44 -0700 Subject: [PATCH] config.md: advertise `diffedit3` as an alternative to `meld-3` diff editor This is instead of https://github.com/martinvonz/jj/pull/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 | 14 +++++++++++ docs/config.md | 41 ++++++++++++++++++++++++--------- 2 files changed, 44 insertions(+), 11 deletions(-) diff --git a/cli/src/config/merge_tools.toml b/cli/src/config/merge_tools.toml index af0bbc8d1d..920577cd7a 100644 --- a/cli/src/config/merge_tools.toml +++ b/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. diff --git a/docs/config.md b/docs/config.md index 7b9597b499..e4b485cfc2 100644 --- a/docs/config.md +++ b/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 +useable 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. + + + +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`