Newbie: explicit 3-way diff?

[akavel]

Hi!
For context, I'm a newbie to jj, and didn't yet use it much in practice; that said, I do have some working knowledge of git (but not deep internals, and not all its commands/flags/incantations either).
I'd like to ask: in jj, given some 3 branches A, B, C, I would like to build a "three-way diff", for a user to be able to fully resolve/accept each difference/chunk by hand, for example with the kdiff3 GUI tool (or a builtin one in jj if present). The thing is,

• I want to make sure the user sees every difference, not just the conflicting ones - also the "non-conflicting" ones - and must manually approve/reject/choose resolution to every change;
• this 3-way diff tool should always get called, unless those 3 commits compared are exactly identical.

I'm fine to call this tool on separate workspaces if that's the only way; that said, in such case I'd still be grateful for help how to do this and how to then build a final "merge commit" if the user accepted, that would include the specific final resolutions they selected for each "discrepancy area".

I'd be also super grateful if you could help me understand how I could do it via jujutsu's Rust API as well - if all goes well, I'd actually like to try and use this conflict resolution "embedded" in a utility app I'm trying to write in Rust.

TIA!

[martinvonz]

I think you're looking for the documentation here: https://martinvonz.github.io/jj/latest/config/#3-way-merge-tools-for-conflict-resolution. Check that out first. Perhaps your own merge tool can work with that file-based API.

[arxanas]

If writing your own merge tool, scm-diff-editor could be a good place to start, as it accepts the files that jj provides, then does its own three-way merge; follow where base is used here:

https://github.com/arxanas/scm-record/blob/8c2d4f36f933ed02acd0a147289925b224deb948/scm-diff-editor/src/lib.rs#L56-L65

If suitable, you could also contribute directly to scm-record/scm-diff-editor.

[ilyagr]

It's not immediately clear to me what you need help with.

@martinvonz will correct me if I'm wrong, but AFAIK jj resolve should pass the exact original files to kdiff3, with one exception: if two files are identical in the base of the conflict and one of the sides, that conflict is auto-resolved. Ideally, jj would have a way to customize this, but it's a tricky question of how the UI for this would work and would require some changes to how jj handles conflicts.

---

Another issue you may be having is that we configured kdiff3 to auto-resolve conflicts by default with its --auto option. You can undo this by configuring:

[merge-tools.kdiff3]
merge-args = ["$base", "$left", "$right", "-o", "$output"]

or you can create an extra merge tool kdiff3-noauto following the docs Martin linked. See also kdiff3 --help for more options. By contrast, the default config is:

$ jj config list --include-defaults merge-tools.kdiff3
merge-tools.kdiff3.merge-args = ["$base", "$left", "$right", "-o", "$output", "--auto"]
merge-tools.kdiff3.edit-args = ["--merge", "--cs", "CreateBakFiles=0", "--cs", "SkipDirStatus=1", "$left", "$right", "$output"]

---

There's also the issue that jj resolve currently works one file at a time. You can still run it in a loop or combine it with jj resolve --list. Or, you could implement the ability for it to work on entire dirs. The main reason this is not implemented is that few merge tools can handle it, but kdiff3 is one of the tools that can (though I find the interface it uses for it un-intuitive).

BTW, the paid Beyond Compare has similar abilities to kdiff3 and might have an easier to use interface for merging three dirs, though YMMV. They do have a generous free trial (30 days, with only days that you actively use the program counted).

---

Finally, if all else doesn't work (e.g. if the the auto-resolution of whole-file conflicts makes jj resolve a non-starter), you can do it manually with workspaces, as you suggested.

If there is no relationship between A, B, and C and you want to edit one (or more) of those three commits, you can manually create three workspaces with jj workspace add dir_A -r A; jj workspace add dir_B -r B; jj workspace add dir_C -r C and then run
either meld or https://github.com/ilyagr/diffedit3 on these three dirs (meld will allow you edit all three sides, diffedit3 will only let you edit one of the sides). I don't think particular configuration is doable with kdiff3¹, but I'm not sure this is what you wanted either.

My best guess is that you wanted to treat B as the base of the merge and then output the merge to a fourth commit. Then, you should do jj new some_parents; jj workspace add dir_output in addition to the above. Then, do kdiff3 dir_B dir_A dir_C -o dir_output. This is again the interface I mentioned as unintuitive above.

Footnotes

1. IIRC, kdiff3 dir_B dir_A dir_C results in a read-only interface. Your best bet with kdiff3 and 3 dirs would be to try kdiff3 dir_B dir_A dir_C --merge, I found it quite confusing and am not immediately sure what it does or what it's good for, but perhaps it will be helpful to you. The four-dir version I explain at the end is probably more sensible. ↩

[arxanas]

@akavel Is this the same use-case/scenario as setting the difftool/mergetool in .gitattributes?

[akavel]

Also, at this point I'm not sure you are using any of jj's features. You can use git worktree just as well as jj workspace. Of course, jj can be useful for other things your to might do.

Part of my reason for interest here was/is to maybe embed jj in my tool (which is also written in Rust) as a library. As I wrote in the initial question above:

I'd be also super grateful if you could help me understand how I could do it via jujutsu's Rust API as well - if all goes well, I'd actually like to try and use this conflict resolution "embedded" in a utility app I'm trying to write in Rust.

[akavel]

@akavel Is this the same use-case/scenario as setting the difftool/mergetool in .gitattributes?

@arxanas I'm afraid I don't understand what you mean by that. I don't know much about .gitattributes.

[ilyagr]

I haven't tried to use the jj API myself, but we provide some examples in the examples directory. There are people on discord who have done it. It'd be probably be simplest to see how jj cli's code for similar functionality works.

Launching merge tools is currently part of the cli rather than the library, but it sounds like you won't actually use it.

If there's functionality in the cli you actually need, you'd have to first send a PR to move it into the library so you can use it via API. Or you could use the CLI, probably as an external process.

[arxanas]

@akavel gitattributes/custom difftools like this https://git-scm.com/docs/gitattributes#_defining_an_external_diff_driver