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..289ab47078 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 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. + + + +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`