Skip to content
  • catlan 
  • 5 min read

The Cure for Merge Madness

Following the addition of Git File History in Kaleidoscope 4.1, in this latest update we wanted to tackle merge conflicts by adding more context provided by Git.

Basics for resolving Git conflicts

We outlined the benefits of using a Visual Merge Tool in a previous blog post, but to better understand the concepts, here’s a bit of terminology. 

Git Terminology

  • heads/HEAD – a “head” (lowercase) refers to any one of the named heads (branch name or tag name) in the repository; “HEAD” (uppercase) refers exclusively to the currently active head.
  • LOCAL – the head for the file(s) from the current branch on the machine that you are using.
  • REMOTE – the head for files(s) from a remote location that you are trying to merge into your LOCAL branch.
  • BASE – the common ancestor(s) of LOCAL and REMOTE.
  • MERGED – the tag / HEAD object after the merge; this is saved as a new commit.

Got it? Yeah, we have never been fond of these names either. When trying to resolve a merge conflict, no one wants to first figure out what LOCAL and REMOTE are. The task of resolving a conflict is already complex enough.

To make things more fun, git mergetool, which is driving the merge process, creates files named <filename>_LOCAL_<pid>.<file extension>. There is one for LOCAL, REMOTE, BASE and BACKUP. So a file named HelloWorld.swift will become something like HelloWorld_LOCAL_52947.swift. And there are 3 more of those, while the merge is in progress.

New context in Kaleidoscope 4.2

In the past, Kaleidoscope tweaked those file names to show only LOCAL and REMOTE as A and B in the Path Bar. Now that Kaleidoscope can communicate with Git, we can do much more than that. Here’s what Kaleidoscope 4.2 now looks like:

A sample merge conflict using the Apple Swift repository on GitHub. Kaleidoscope 4.2 features a brand new header with helpful context information.

We know that there is a lot of data to take in at first glance, but the new top part of the window is helpful in getting the job done. We will explain each part below:

Window Title Bar

In the window title bar you’ll see a new element that gives you more detail about the task. You’ll see how many conflicts you still need to resolve in that file. Remember the keyboard shortcuts for the menu commands Previous Conflict (⌥⌘▲) and Next Conflict (⌥⌘▼) from the Navigate menu so you can quickly jump through all of them.

The Context Shelf

The window has a new area between the title bar and the Path Bar. We call it Context Shelf. It can be hidden, which may be useful once you have digested the information in it and need as much space as possible for the content. Just click the toolbar item or use the menu command in the View menu.

In the middle, depending on the conflict type (did you really expect Git to only have one?), you’ll see a description of what you are dealing with (a merge in this case) and which refs are involved. We will also try show you branch names when available.

Left and right, above A and B, you’ll see the last change on that branch that lead to the conflict shown below, in the same format you already know from the file history in Kaleidoscope 4.1. The top line shows the author and the short commit hash. Below that you’ll see the (possibly abbreviated) commit message and the date or time of the commit.

Clicking the area above A and B shows a popover with all the details, same as in the file history list. Here you will also see the avatar of the user (if available) and gain the ability to directly email the author by clicking on the author name. And you can read the full commit message and select and copy parts if needed.

The Path Bar

Finally, the Path Bar above the text views has been tweaked to outline exactly what content is shown where. It can be confusing to look at 3 files of very similar text, so it’s useful to get confirmation:

We hope this will make it easier and faster for you to solve merge conflicts and to continue to enhance your productivity. Let us know how it works for you, in particular if something is not working as you expected so we can improve that.