docs: Recommend to use '* merge=mergiraf' #384

By the way, maybe it would be possible to incorporate the line-based-fallback logic into Git itself? So we would return a special exit code if we know we can't handle the given language, and Git would in turn run git merge-file internally, which might be faster than us shelling out. I think this functionality would be helpful even outside Mergiraf (in fact I believe the issue would've already been implemented if custom merge drivers were more prevalent).

In fact, doesn't the error code thing basically exist already? Quoting "Defining a custom merge driver":

When the driver crashes (e.g. killed by SEGV), it is expected to exit with non-zero status that are higher than 128, and in such a case, the merge results in a failure (which is different from producing a conflict).

So Git could perform the fallback on exit code >128

That sounds like a good idea! But at the moment (git v2.47.2), it seems that git simply aborts the entire operation if mergiraf returns code 129. If Git was to change this in a later version, then we'd need to know the Git version to know if we can allow ourselves to fail, or if we should handle the fallback on our side. So that would probably mean running git --version to find out?But at that rate we might as well run git merge-file directly, perhaps…

One question I have is whether we should rather use our own line-based merging (which doesn't require starting a new process) or git's own (which might better respect git's configuration, and is likely more optimized than the diffy implementation).

I've been trying this out on various codebases and didn't notice anything particular, beyond the warning that I disabled above, so this seems good to go as far as I am concerned.

One question I have is whether we should rather use our own line-based merging (which doesn't require starting a new process) or git's own (which might better respect git's configuration, and is likely more optimized than the diffy implementation).

I wanted to suggest gix as another option (gix-merge in particular), but it operates on a whole repo, so using it would be more complicated than just passing 3 strings. Digging into the source code a bit though, it seems to boil down to the same imara-diff-based merge we use: https://docs.rs/gix-merge/0.5.1/src/gix_merge/blob/builtin_driver/text/function.rs.html#28. So I guess that's another point for the first option.

Actually, I wonder whether we could just hook into these internals, and get rid of diffy-imara completely

Ah nice! Last time I looked I hadn't been able to find this sort of functionality there, I don't know if it's because it wasn't there yet or I didn't look closely enough.

Switching sounds good to me in principle, but looking at the dependencies of gix-merge, it seems that it's far from self-contained. It looks like diffy-imara remains more lightweight and quite fitting for us, no?

seems that it's far from self-contained

I guess the dependencies are there because of all the Git-related logic, but we kind of want that if we want to respect Git config and such, no?

Otherwise we could maybe persuade them to extract the pure string merging algorithm into a separate crate we could then take a dependency on. But this would be pretty much what we have already with diffy-imara, yeah (aside from the latter being much worse maintained by yours truly 😅)

I guess the dependencies are there because of all the Git-related logic, but we kind of want that if we want to respect Git config and such, no?

Perhaps… I am not sure to what extent their implementation really does!