tehbilly / karabiner-windows-mode

Karabiner-Elements complex ruleset to make using macOS friendlier by enabling common keyboard functionality used in Linux and Windows.

karabiner-windows-mode

Karabiner-Elements complex ruleset to make using macOS friendlier by enabling common keyboard functionality used in Linux and Windows. Now powered by Jsonnet, allowing the main files that need to be interacted with (*.jsonnet and *.libsonnet) to be much shorter and far more readable.

If you'd like to contribute to this project, please check the Contributing section.

Installation

Copy and paste the following URL into your browser window and Karabiner-Elements should ask to install the file:

karabiner://karabiner/assets/complex_modifications/import?url=https://raw.githubusercontent.com/tehbilly/karabiner-windows-mode/master/json/windows_shortcuts.json

List of Shortcuts

First, a note about how these shortcuts are named in Karabiner-Elements. They follow the convention

Key (Modifiers, if any) [Special notes, if any]

so they should be easy(ish) to understand. Contact me if you have improvement suggestions.

There are some applications, such as hypervisors, IDEs, remote desktops, and terminal emulators, that should receive raw inputs and handle them themselves. To that end, almost all shortcuts no longer apply to these applications. As such, the notes will no longer specify that the specific shortcut does not apply to the excepted applications as that is now the default state. Instead, they will note when a shortcut still applies.

Generally Excepted Applications:

• Hypervisors
  • Oracle VirtualBox VMs (not the VirtualBox manager application)
  • Parallels
  • VMware Fusion
• IDEs
  • GNU Emacs (GUI)
  • JetBrains (All)
  • Microsoft VSCode
  • Sublime Text
• Remote Desktops
  • Chrome Remote Desktop (app version, not in-browser version)
  • Citrix XenAppViewer
  • Microsoft Remote Desktop Connection
• Terminal Emulators
  • Alacritty
  • Hyper
  • iTerm2
  • Kitty
  • Terminal
  • WezTerm

Credits

• @TechnicallyDifficult for coming up with the initial json file
• @alvaro1728 for creating the current json file and for asking the question that got this whole thing started
• @tezeko for Karabiner-Elements
• @lsissoko for Ctrl+R and Ctrl+W additions
• @aperlstein for adding Ctrl+Enter, Ctrl+Shift+Enter, Ctrl+Space, and for adding Citrix XenAppViewer to list of exceptions
• @Ivanca for adding IDEs to list of exceptions
• @from-nibly for adding VMware Fusion to list of exceptions
• @andormarkus for adding JetBrains PyCharm to list of exceptions
• @amateescu for adding JetBrains PhpStorm to list of exceptions
• @vidurb for adding GNU Emacs to list of exceptions, and the Cmd+ shortcuts
• @jkluch for adding Microsoft RDC to list of exceptions
• @csmager for adding Parallels and JetBrains Rider to list of exceptions
• @kingamajick for adding WezTerm and Chrome Remote Desktop (enabling support for file_paths to identify applications) to the list of exceptions
• @raxigan for simplifying JetBrains IDE listing and adding the Win [Spotlight] shortcut

Links

• Karabiner-Elements (Homepage) (GitHub)

Contributing

Pull requests (PRs) and issues are welcome! But first, some notes:

• Make sure to note your changes in the relevant places in the readme
• Remember to give yourself credit in Credits section
• Don't change any *.json files! They are automatically rendered and your changes will be overridden.

Again, please refrain from making changes directly to any *.json files (all JSON files will be rendered automatically as necessary on a push to the master branch) and instead make your additions in the *.jsonnet and *.libsonnet files and submit a PR. A comment will automatically be added to the PR showing any JSON changes that will result.

Adding Exceptions

When adding exceptions, you will need the applications "bundle identifier". To get this, you can use the following AppleScript (SuperUser thread):

osascript -e 'id of app "<application>"'

In the above example, <application> is the name of the application, such as Finder or Microsoft Excel.

Once you have the bundle identifier, which will be, for example, com.microsoft.VSCode for Microsoft VSCode, you will need to add it to the bundle.libsonnet file in the appropriate section. Since VSCode is an IDE, we would add it to the ides: [ ... ], section. Make sure to add ^ at the beginning, and $ at the end of the identifier, and to add \\ before any periods. (Look in the file and follow the pattern.)

Testing

For testing, get Jsonnet (I use the C++ version personally, but a Go version is also available), render the json file locally (jsonnet -- ./jsonnet/windows_shortcuts.jsonnet >./json/windows_shortcuts.json) and test it in Karabiner Elements to ensure your changes work how you think they should work.

Once your testing is done, you can simply run make to ensure your changes are syntactically valid jsonnet and that they are formatted. If you don't get any errors, then you should be ready to commit your changes and submit a PR.