We received feedback about keyboard shortcuts no longer working in the text merge since the recent Kaleidoscope 5.2 release. While it’s true that we changed some shortcuts, all functionality remains intact, and we believe more consistent and usable than before.
In this post, we’ll provide background on navigation and merge actions, explain the rationale behind the changes, and offer tips on how to revert to the old behavior if you still prefer that after reading. Let’s dive in!
Navigation: Primary vs Secondary Actions
Text Comparison
In a regular comparison, there is one primary navigation action: jump to the next or previous change. In Kaleidoscope, a change can be an insert, a deletion or a modification of content. In a comparison, you typically browse changes, and you may occasionally copy stuff from one side to the other. In a text comparison, there’s always one change that is currently selected. Commands from the Merge menu act on that selection.
These are all the ways to navigate text in Kaleidoscope:
- Use the toolbar buttons in the bottom right of the window.
- Select Navigate > Next Change or Navigate > Previous Change from the menu
- Use the keyboard shortcuts associated with those commands: ⌘▼ and ⌘▲. These are the most common shortcuts in Kaleidoscope.
- Scroll through your text, either by dragging the scrollbar handle or by some gesture on your mouse or trackpad.. You notice that changes get highlighted as you scroll.
- Use the Swipe between pages gesture on your trackpad.
Text Merge
While behaving rather similarly, a merge is a different task. You often end up in a merge due to a conflict in your Git Working Copy. You are rarely there out of cheer fun, rather something went unexpectedly wrong. Your task is to find these conflicts and resolve them as quickly as possible, while not destroying anyones work along the way.
So the very same actions that jump to the next/previous change in a comparison now jump to the next/previous conflict in a merge. See the list above for all the options.
Kaleidoscope always had the concept of secondary navigation actions: jumping to next/previous change instead of jumping to next/previous conflict. But these were somewhat inconsistent in their implementation.
In a merge, there’s now a consistent set of secondary alternatives for all the above, and the all work by just holding down the option (⌥) key while performing that action. For example, to navigate to the Next Change, you need to press ⌥⌘▼, which is different from ⌘▼ in earlier versions. ⌘▼ is now assigned to Next Conflict, which is the main action.
Choose A and Choose B
Once you have navigated to a specific conflict and decided how to resolve it, you often do that by copying text from one side to the other.
In the menu, there are Merge > Choose A and Merge > Choose B commands for that. Those used to have the same keyboard shortcuts as Merge > Copy A to B and Merge > Copy B to A in a Text Comparison, simply ⌘► and ⌘◀. While those were really easy to remember and use, there is a major problem with them: they are also used as text editing shortcuts in all of macOS.
Not everyone needs to edit text while resolving a merge conflict, but if you edit text, hitting the familiar ⌘◀ to jump to the beginning of the line would just overwrite your edit made with the content from B, as this was the shortcut for Merge > Choose B and took precedence. This was pretty frustrating, and bad practice for an app trying to be a good citizen on the platform.
So, while slightly harder to use and memorize, you now need to hold down the control (⌃) key in addition to the above for Merge > Choose A and Merge > Choose B. So it’s now ⌃⌘► and ⌃⌘◀. These don’t conflict with any default shortcuts on macOS.
Due to the cursor keys being quite overloaded by default (there’s also ⌃◀ and ⌃► to move between Spaces, and many others without the command (⌘) key for text editing, the keyboard shortcuts for the new Base to A Comparison and Base to B Comparison look a bit overwhelming with ⌃⇧⌘◀ and ⌃⇧⌘►, but they are actually not that hard to get used to. Read more about the new Base to A/B Comparisons in our previous post.
Reverting to old Shortcuts
If you decide you want to revert to some of the old shortcuts, System Settings on macOS comes to your rescue.
Start System Settings, then locate Keyboard in the left column and click Keyboard Shortcuts… In the overlay that opens, locate App Shortcuts in that sidebar. Now you find a plus (+) button at the end of a list. Click it.
Select Kaleidoscope from the list of All Applications and then enter the Menu title you want to override, along with your preferred Keyboard shortcut.
Here are all the candidates discussed above, with their old shortcuts. Mix and match to suit your needs.
| Menu title | Previous Keyboard shortcut | New in Kaleidoscope 5.2 |
|---|---|---|
| Previous Conflict | ⌥⌘▲ | ⌘▲ |
| Previous Change | ⌘▲ | ⌥⌘▲ |
| Next Conflict | ⌥⌘▼ | ⌘▼ |
| Next Change | ⌘▼ | ⌥⌘▼ |
| Choose A | ⌘► | ⌃⌘► |
| Choose B | ⌘◀ | ⌃⌘◀ |
Note that the new shortcuts for Previous Change and Next Change as of Kaleidoscope 5.2 are only changed when merging, for a Comparison they remain as they always used to be.
Conclusion
We understand that adapting to new keyboard shortcuts can be challenging, especially when you’ve developed muscle memory around the old ones. However, we believe that these changes in Kaleidoscope 5.2 will ultimately enhance your merge experience.
We encourage you to give the new shortcuts a try. If you find that you still prefer the old shortcuts, use System Settings to revert them to your liking. We’d love to hear your thoughts! Have you had a chance to try the new shortcuts? What do you think about the changes?
Happy merging!
