Merge conflicts cause confusion and aren't handled well

[billygriffin]

Please describe the problem you think should be solved

When people run into a merge conflict, it's often a confusing and overwhelming experience. GitHub Desktop provides a few ways to merge code from one branch into another (or when pulling from your upstream remote), but when a merge conflict occurs, there isn't a particularly elegant way of handling it, and the app just sort of leaves people on their own to resolve it, usually in the browser, with their editor, or on the command line + an in-terminal editor.

Example:

This recent issue clearly captures an example where this can fall down: #5264

Next steps

• Conduct interviews with non-GitHub people about their experiences with merge conflicts
• Synthesize the notes and identify particular problem areas
• Evaluate GitHub Desktop's existing handling of those problem areas
• Prototype one or more possible solutions and get them in front of users
• Build and release first iteration in Desktop
• Ensure we're properly capturing metrics to help measure success

We'll be using this issue to update the progress on each of these and we'll likely update it with additional references of others who have run into problems in this realm.

[billygriffin]

Via @niik in #2640 for solving the problem of differentiating between conflicted files and those without conflicts:

We talked about this and we think that a good first step is, as has been previously suggested, to sort them ahead of other changed files. Individually they'll still be sorted alphabetically but they'll be visually grouped together. We think that'll make a big difference.

[billygriffin]

#5694 and #5699 are related to this effort as well as the larger effort that is currently in design.

[ampinsk]

Designs

After some sketching, and a quick round of usability testing, we have a direction that we're going to move forward with building.

✨ Clickable prototype ✨

Encountering merge conflicts

This experience would begin by clicking the Merge into... button when comparing branches, or from the Merge options in the Branch menu.

If you run into conflicts, we will show you this modal, which lists the conflicted files, and sends you to your editor of choice. You can abort your merge at any time in the process.

If you abort while you have some resolved changes, we’ll show you a confirmation modal.

Resolving merge conflicts

Using Atom as an example, you would resolve conflicts in your editor or merge tool of choice:

When you come back to Desktop, these changes are reflected:

As you continue to resolve the conflicts, the modal continues to update. The number of merge conflicts per file will update as you resolve the conflicts in each file:

Committing your merge

Once all conflicts are resolved, you can commit the merge from the modal, and we’ll take you to the Changes view with your merge commit ready to be undone if needed.

Some questions we're still looking to investigate:

1. Are users comfortable not seeing a diff inside GHD?
2. What do users expect to happen and be able to accomplish when they go to the command line during the process?
3. Where should users be taken after they commit the merge from the modal?
4. How does this respond to terminal actions? For example, what if I merge in terminal and then go to GHD?
5. Do users stash files in the middle of a conflict and why?
6. How do users expect to handle binary files?

cc @billygriffin @donokuda @outofambit

[handletastic]

I don't have a great deal of time to answer here but I definitely want to answer this question.
1. Are users comfortable not seeing a diff inside GHD?
Yes, I, personally, am. However, I would much prefer to see a diff happening within GHD. Also would love to see the ability to change between two views (up-down in same file comparison and side by side comparison). I probably am just a bigger fan of side by side with coinciding lines.

[billygriffin]

Hi @hdsantos89, thanks for the feedback, that's great to hear. We're tracking side-by-side diffs here (#172), which I know is closed currently but is tracked as a future-proposal and will likely be reopened at some point soon.

We'll definitely keep an eye on whether the guided flow is universally valuable or whether folks want to just be able to see the conflicted diff in Desktop and resolve the conficts on their own.

[mcmz]

In my opinion users expect to see a simple side by side diff view. With some simple black arrows to merge the diff from ltr and rtl.

[billygriffin]

@mcmz Please keep discussion in this issue to merge conflicts. #172 is where we're tracking side-by-side diffs. Thank you!

[Tsarfolk]

I wanted to write that I don't like the changes, cause the default editor is Atom (...nasty tabs...) and I can't really change it... But then, I took a look at settings and found there Sublime 🙌

So, I'm ok with new feature. Can't say that wow it's a breakthrough, but it's good for sure
About editors, for person, who doesn't like sublime / webstorm or Atom (I found it as options of default editor which I can choose on my machine) it can be annoying. Since he or she really can't change the editor to the favourite one if it's not in the list
For example, Xcode is not supported as a default editor. But I can open *.swift file by clicking "Open with Default Program" and at the same time, I can't do it while merge conflicts in the new version

I personally use GHD only for merge conflicts and to watch current (some commit) diff
for checkout, pull, push, reset and etc CLI is more preferable for me

[billygriffin]

Thanks @Tsarfolk! There are a lot of editors available to work with Desktop (documentation here with available editors), and for the example you gave, XCode, we have an open issue if someone wants to configure it: #4825.

You're also able to always update your preferred editor in preferences.

Hope that's helpful! Our primary goal with the feature was to lower the level of intimidation of merge conflicts and make them more approachable for newer developers, while also not making them too burdensome for more experienced developers. We're discussing whether we can improve on the latter portion in #6213.

[everhardt]

When merging, I don't always only review conflicts: I sometimes want to review other changes as well.

Until now, I was able to glance through them by going through each file in the "changed files" list in GH. Wit this modal, I can't do that anymore. If it's a long list of files, I can't even see in GH which files are changed, as I can't scroll with the modal in place.

Therefore, I'd like to have a third button in the modal: "Resolve manually", where the modal closes and the changes are still in the staging area/ working directory.

[billygriffin]

Thanks @everhardt! That's really helpful feedback. We're looking at this in #6213. Your problem statement is slightly different from the person's from that issue but I think @ampinsk's initial thinking on it would also solve your problem in a similar manner that you proposed. We're still discussing this internally and trying to gather more data about how it's working for folks and how it's falling down, so I really appreciate you weighing in.

[jbrennan]

Seconding these things mentioned by @Tsarfolk and @everhardt as they line up with my experiences as well:

For example, Xcode is not supported as a default editor. But I can open *.swift file by clicking "Open with Default Program" and at the same time, I can't do it while merge conflicts in the new version

and

Until now, I was able to glance through them by going through each file in the "changed files" list in GH. Wit this modal, I can't do that anymore. If it's a long list of files, I can't even see in GH which files are changed, as I can't scroll with the modal in place.

Therefore, I'd like to have a third button in the modal: "Resolve manually", where the modal closes and the changes are still in the staging area/ working directory.

My workflow in GHD up until the new merge modal has been:

• merge in the branch in GHD
• if there are conflicts, open each conflicted file in Xcode via right click -> open with default program
• fix the merges in Xcode

Now, I don’t have that option. And since Xcode is not yet recognized as one of the valid GHD editors, I actually can’t perform a conflicted merge in GHD now.

Just wanted to give some +1s on this thread, thanks!

[billygriffin]

Thanks @jbrennan, especially for explaining your workflow! I think you should be able to do something very similar to your previous workflow when we ship the next iteration (that we're tracking in #6213), and also have available which conflicted files have all the conflicts resolved and which are still conflicted. Sorry for the inconvenience in the mean time. We're hoping this new path will be more useful for both people who prefer a bit more of a guided editor-centric workflow and people like you and the others who have offered feedback.

Quick question for you though, if XCode did show up as a supported editor in the guided flow, do you think you'd still prefer to resolve it in the old way, or would you like to use the guided flow?

[jbrennan]

I think you should be able to do something very similar to your previous workflow when we ship the next iteration (that we're tracking in #6213)

Excellent, looking forward to this!

if XCode did show up as a supported editor in the guided flow, do you think you'd still prefer to resolve it in the old way, or would you like to use the guided flow?

Hard to say for sure since I currently haven’t been able to use the flow, but probably yes. What I care about most during merge conflicts are seeing which files are conflicted + opening them in my editor to resolve them. Seems like supporting Xcode as an editor should handle that OK in the current workflow :)

[timor-raiman]

This is good news.
However, we are missing:

1. an option to accept one of the versions (--ours or --theirs) without merging through a merge tool
2. being able to configure a merge tool other than an editor (like winmerge)

For (1), right now, we drop to cli and do "git checkout --ours/theirs -- path/to/file; git add path/to/file" for each file we don't care to merge

[billygriffin]

Hi @timor-raiman, thanks for the feedback! We're considering some possibilities for a very lightweight version of (1) just in the guided flow. But generally our hypothesis has been (based on interviews and our observations) that there are so many different ways of visualizing and resolving the conflicts themselves and we think generally editors do a pretty reasonable job of this. Therefore instead of building yet another slightly different implementation of the same thing, we thought we'd start out by guiding users through the process to give them confidence when everything's resolved, but not actually going through the resolution itself. But we agree that there may be a bit more we can do without a full on conflict resolution tool in Desktop.

(2) is a good suggestion and is captured in #1765. Ignore that it's closed - we're working our way through the future proposal labeled issues and many of them will likely be reopened as we get our arms around all of them. Thanks again!

[thientm]

Thanks @Tsarfolk! There are a lot of editors available to work with Desktop (documentation here with available editors), and for the example you gave, XCode, we have an open issue if someone wants to configure it: #4825.

You're also able to always update your preferred editor in preferences.

Hope that's helpful! Our primary goal with the feature was to lower the level of intimidation of merge conflicts and make them more approachable for newer developers, while also not making them too burdensome for more experienced developers. We're discussing whether we can improve on the latter portion in #6213.

hope this have a option for KDiff3