chrisgrieser / finder-vim-mode

Feature-rich mouseless control of macOS Finder, inspired by vim/ranger.

Vim Mode for Finder

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

Usage Examples

• rl: Duplicate selected file and open the copy.
• axw: 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 q and navigated via hjkl. Use esc or press q again 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

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"
   
   defaults write com.apple.finder FXPreferredViewStyle -string "Nlsv" # set default view to "List"
   defaults write com.apple.finder CreateDesktop false # disable desktop icons & make desktop unfocussable
   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 the 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.

Note

I do not use Raycast, but Raycast can be supported with either the Spotlight addon or by enabling some sort of compatibility mode. For proper Raycast support, please open an issue.

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.
• In some edge cases, not using of English as System UI language can create an issue. (You can fix this by changing to English: System Settings → General → Language & Region → Preferred Languages)

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 ~6000 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 ~1000 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

finder-vim-mode's Issues

[Bug]: Spotlight Search does not work when focused on Finder

Bug Description

Spotlight Search does not work if called from a Finder window. Instead finder-vim-mode actions are performed in the background Finder window.

Relevant Screenshot

No response

To Reproduce

1. Open Finder
2. Open Spotlight Search
3. Try typing something, it will perform vim actions on the background window instead of typing in the search window

Keyboard Layout

U.S.

System UI language

English (US)

Checklist

• I updated to the latest version of this plugin.
• I updated to the latest version of Karabiner Elements.
• I have read about the limitations of Karabiner plugins in the Caveats section of the README.

Feature Request: Visual Mode

Feature Requested

Thanks for this awesome vim mode! I'm getting used to hjkl and love it, but I keep wanting to select 3-4 files within a folder to cut/copy/paste/open them together. I used v for this at first but realized that instead shows preview information for the current file. Is there already a way to select a subset of the files after navigating to some with e.g. jk?

Relevant Screenshot

No response

Checklist

• The feature would be useful to more users than just me.
• I have read about the limitations of Karabiner plugins in the Caveats section of the README.

Multi-Select does not work on folders

So with the multi-select, there is quite an annoying limitation, which took me a while to figure out. Weirdly enough, Finder can select a file, multiple files, or a folder, but not multiple folders… m(

var wd = "/Users/chrisgrieser/Library/Mobile Documents/com~apple~CloudDocs/File Hub/"

var folder = Path(wd + "untitled folder")
var folder = Path(wd + "untitled folder copy")
var file = Path(wd + "untitled")
var file2 = Path(wd + "untitled 2")

var finder = Application("Finder")

// works
finder.select(folder); 
finder.select(file);
finder.select([file]); 
finder.select([file, file2]);

// does not work
finder.select([folder]);
finder.select([folder, folder2]);

The docs on the JXA Path object are pretty sparse. If anyone knows how to fix this, any tips are welcome

Select files is not good (weird) [Bug]:

Bug Description

When I installed the keybindings to karabiner, my expectations were low because I didn't think the application would work properly in such an application like finder tbh 🫣, but after trying it for like 10 minutes, I said wow and that was the aha moment. It's really amazing, well designed and well applied. Thank you for that. However I think there's two things might improve the experience.

1. the keybindings image is in bad quality and hard to see, so if possible to upload higher quality image. (I can design one if you can provide me with the high quality plain one and then add it to the repo)

2. Selecting files are through shift+space or shift+arrow and this is not bad but a little bit weird because usually when selecting multiple files we do it with command and mouse click then select multiple files that not in order (if you know what I mean). I'd be grateful if possible feature can be added to the keybindings.

Thank you again for this amazing and well thought add-on.

Relevant Screenshot

No response

To Reproduce

If we have 4 files and we want to select files 1 and 4.
steps:

1. select file number 1.
2. not selecting the next 2 files (2+3).
3. select the 4th file.

Keyboard Layout

British - QWERTY

Checklist

• I updated to the latest version.
• I have read about the limitations of Karabiner plugins in the caveats section of the README.

edited: the steps to reproduce/ just a typo.