Vim Mode for Finder

Feature-rich control of macOS Finder without the mouse, inspired by vim and ranger.

Usage Examples

• wl: Duplicate selected file and open the copy.
• axq: Select all files, move them to the other window, close current window.
• .f.d.: Show hidden files, select first hidden file, delete it, hide dotfiles again.
• AM: Select files (but not folders), create a new directory, move selected files into that directory, and start renaming the directory (enters insert mode).
• azmhp: Select all files and folders, zip them, (wait for zipping to finish), and move the archive one directory up

Table of Contents

• Usage
• Installation
• Updates
• Caveats
• Build
• Credits
• About the developer

Usage

• Only works in Finder's List View.
• :help Press ? in Finder to display the cheatsheet above. Generally, everything in brackets only applies to the uppercase version of the key.
• Move: m marks the current selection as "to be moved." The next paste-operation p moves the files. A move can be aborted via esc.
• Cross-move: If you have exactly two Finder windows open, x moves the selection to the other window, and X copies the selection to the other window.
• Context-menu: Can be opened with c and navigated via hjkl. Press esc, q, or c to close the context-menu.
• Find mode is triggered via f, works similar to f in vim, expecting another character afterward. For example, fh jumps to the next file that starts with the letter h.
• Toggle -bkp suffix: Add suffix -bkp to the file. If it already has such a suffix, remove it. Useful for debugging as well.
• Tab goes to the next file in alphabetical order, even when the view is not sorted alphabetically. (This is actually a built-in feature of Finder, but worth mentioning since barely anyone knows about it.)
• Copy/Paste file content: Y copies the content of the selected file, while P pastes text from the clipboard into the selected file (appending).
• Copy path components:
  • Ctrl+p: Absolute path
  • Ctrl+n: File name
  • Ctrl+t (if in git repo): Path relative to the repo root
• Open in GitHub: If the file is in a git repo, Ctrl+g opens the file at GitHub and also copies the URL to the clipboard.

Note

Pressing return in a prompt window, for example when replacing a file, mistakenly puts you in Insert Mode. Unfortunately, Karabiner is not able to detect whether the front window is a regular Finder window or a prompt. The workaround is to either press esc to go back to Normal Mode, or to use tab and then space to select the correct action in the prompt window.

Installation

This plugin requires you to have English as your System UI language. (You can set the language via: System Settings → General → Language & Region → Preferred Languages)

1. Run this in your terminal:

   brew install karabiner-elements # Install Karabiner (if not already installed)
   
   worktree="https://raw.githubusercontent.com/chrisgrieser/finder-vim-mode/main"
   open "karabiner://karabiner/assets/complex_modifications/import?url=$worktree/finder-vim.json"
   curl -sL "$worktree/extras/cheatsheet.png" --create-dirs --output "$HOME/.config/karabiner/assets/finder-vim-mode/cheatsheet.png"
   curl -sL "$worktree/extras/notificator" --create-dirs --output "$HOME/.config/karabiner/assets/finder-vim-mode/notificator"
   
   # set default view to "List"
   defaults write com.apple.finder FXPreferredViewStyle -string "Nlsv"
   # optional: disable desktop icons & make desktop unfocussable
   defaults write com.apple.finder CreateDesktop false
   # restart Finder for changes to take effect
   killall Finder

2. Activate the plugin: Import → Enable

3. Karabiner users: If you already use Karabiner and have another modification affecting the Capslock key, the other modification must come below the Finder Vim Mode in the list of modifications. (Karabiner prioritizes modifications further on top of the list.)

4. Alfred users: In the Appearance Options, you need to set the Focusing behavior to Compatibility Mode for Karabiner to detect Alfred being active.

5. Spotlight users: You need to install the Spotlight addon. The addon has to be above the Finder Vim Mode in Karabiner's list of modifications.

   # install Spotlight addon
   open "karabiner://karabiner/assets/complex_modifications/import?url=https://raw.githubusercontent.com/chrisgrieser/finder-vim-mode/main/addons/finder-vim-spotlight-addon.json"

6. The first time you receive a notification, you are asked whether notifications should be allowed or not.

Updates

Unfortunately, Karabiner has no mechanism for auto-updating plugins. Therefore, you have to install updates manually by re-running the code above. You can check for the last commit date to see whether there has been an update:

Caveats

Since Karabiner plugins are only hotkey re-mappings without proper scripting mechanisms, this plugin has some limitations:

• Only List view is supported.
• If you use the mouse to click buttons, you can end up in the wrong mode. In that case, you can press esc to get back to Normal Mode. (Or, you know, just do not use the mouse. You're a vim user, after all.)
• File selection dialogues from other apps (for example to upload a file in the browser) are not supported.
• Unfortunately, it is not possible to have a vimrc or to let the user configure the keybindings themselves in any way, at least not with a Karabiner plugin. If you want to rebind keys, you have to change the respective key manually in the JSON file.
• If you have set custom keybindings for Finder, they can potentially interfere. It is therefore recommended to unset them.
• The plugin has been tested with the U.S. and German keyboard layout. It should mostly also work for other layouts.

Build

Karabiner plugins are essentially hotkey configurations in form of a JSON file. Since the amount of configurations for this plugin is rather large, the resulting JSON file ~8000 lines. To make that manageable, this plugin is written in YAML, where features such as anchors and aliases reduce the lines of code to only ~1300 lines.

If you want to fork this plugin, it is recommended to work with the YAML file and "compile" it to the JSON required by Karabiner. You can do so with yq:

# `explode()` required to resolve the anchors and aliases
yq --output-format=json 'explode(.)' finder-vim.yaml > finder-vim.json

Credits

• The cheatsheet has been created with http://www.keyboard-layout-editor.com/.
• The notification script is a modified version of the Notificator by Vítor Galvão.

About the developer

In my day job, I am a sociologist studying the social mechanisms underlying the digital economy. For my PhD project, I investigate the governance of the app economy and how software ecosystems manage the tension between innovation and compatibility. If you are interested in this subject, feel free to get in touch.

• Academic Website
• ResearchGate
• Mastodon
• LinkedIn