/!\ This page is primarily intended for Mercurial's developers.

Merge Tools Plan

A plan to resolve usability concerns around configured merge tools.

1. Problem Statement

Most Linux distributions come with vim installed as part of the base system, and our packaging advice recommends including our merge tools configuration, which means that most users will trip over vimdiff even if they don't want it. Learning how to force-disable a merge tool is an extra unfriendly step many users are confronted with, and this is more common in large enterprise type installations than for hobby users, which can lead to more hatred of Mercurial.

2. Proposed Solution

Quotes from this message and some followups:

""" The idea would be to have a default merge tool that display available choice and prompt the user to configure one he is comfortable with. This issue is coming up frequently enough that we should probably make it happen. I wonder what other people think. """

""" It might be a problem for other people though, so if it ceases being the default, maybe have Mercurial ask something like the following (starting with any tools defined in the [merge-tools] section of config files) if there are merge conflicts that it cannot resolve:

There are merge conflicts in file ./some/path/to/filename.ext, but no default merge tool has been defined in ui.merge Use [v]imdiff, [k]diff3, internal:[l]ocal, internal:[o]ther, [f]ail? (v) """

Quotes from more followups:

=== We should behave properly if the merge in non-interactive.===

I'm not sure what we currently do in that case but I'm assuming we use internal:merge and move forward. We should keep (get to) that behavior in the future.

2.1. Prompt display

The list of Mercurial tool will be long and complicate. I think it is still worthwhile to inflict it to the user (better than vimdiff). I think we should have a multiple line prompt (exceptional situation!)

There are merge conflicts in file ./some/path/to/filename.ext, but no default merge tool has been defined in ui.merge, please pick one:

?) get more help and details f) fail the merge and go back to the command line 0) merge (leave merge marker in your repository) 1) merge3 (same, also display content from the base) 0) kdiff3 1) meld 2) vimdiff o) See other unavailable merge tool

(content of forms provided as exemple not a serious proposal)

The see other unavailable merge tool could point out at other popular merge tool with pointer about how to install them.

2.2. Transition for current user

> Some users might intentional not have configured a [ui]merge=$TOOL intentionally and expect the current behavior of using the "best" tool that's installed

The choices should probably be order used the current priority that way people who expect the default to be the best would have the "best" as default prompt choice.

2.2.1. Helping people to pick

Picking a a merge tool will be complicated and stressful for most user, we should probably:

- Have a description of each configurer merge tool in the config (that user can access from the prompt)

- Easy way to see what other option exist for there system and how to gain access to it if not already available.

2.2.2. saving the config change

We should probably make it possible to save the result of that merge in user config. Adding the config at the end of the user/repo HGRC seems the way to go.

Having a post-merge prompt asking:

Do you want to use this merge tool in the future - no, ask me again next time, - yes for all merge in this repository, - yes for all my merge,

3. Concerns

This is a pretty major behavior change. Some users might intentional not have configured a [ui]merge=$TOOL intentionally and expect the current behavior of using the "best" tool that's installed (eg FileMerge.app on OS X, kdiff3 on linux, etc).

We already have a way to forcibly disable undesirable merge tools for users. That's a start, but it's not sufficient because we're still getting roughly monthly reports on mercurial@ of users landing in vimdiff and not knowing how to get anything useful instead.


CategoryDeveloper and CategoryNewFeatures

MergeToolsPlan (last edited 2015-12-03 05:00:50 by Pierre-YvesDavid)