Skip to content

Commit

Permalink
config.md: advertise diffedit3 as an alternative to meld-3 diff e…
Browse files Browse the repository at this point in the history
…ditor

This is instead of martinvonz#3292, which would make
`diffedit3` built into `jj`. I am still hoping to eventually make that a reality
and to make `diffedit3` a default diff editor that would be installed everywhere
`jj` is, but this may not happen, and it wouldn't help 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.
  • Loading branch information
ilyagr committed Apr 12, 2024
1 parent 65a525c commit aa5b51c
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 11 deletions.
14 changes: 14 additions & 0 deletions cli/src/config/merge_tools.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
41 changes: 30 additions & 11 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- 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`

Expand Down

0 comments on commit aa5b51c

Please sign in to comment.