{"id":13478836,"url":"https://github.com/chrisgrieser/finder-vim-mode","last_synced_at":"2025-04-07T13:08:28.114Z","repository":{"id":64604605,"uuid":"576342717","full_name":"chrisgrieser/finder-vim-mode","owner":"chrisgrieser","description":"Feature-rich mouseless control of macOS Finder, inspired by vim/ranger.","archived":false,"fork":false,"pushed_at":"2025-03-05T17:12:40.000Z","size":10719,"stargazers_count":92,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T12:04:59.715Z","etag":null,"topics":["complex-modification","finder-extension","karabiner-elements","macos-finder","macos-finder-extension","vim-emulation","vim-emulator","vim-mode"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrisgrieser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://www.paypal.me/ChrisGrieser","ko_fi":"pseudometa"}},"created_at":"2022-12-09T15:53:03.000Z","updated_at":"2025-03-30T12:16:43.000Z","dependencies_parsed_at":"2023-01-31T05:16:19.948Z","dependency_job_id":"522ccfa0-1a90-4083-8d90-e444e4d83aa0","html_url":"https://github.com/chrisgrieser/finder-vim-mode","commit_stats":{"total_commits":192,"total_committers":2,"mean_commits":96.0,"dds":0.00520833333333337,"last_synced_commit":"e6b555192ff14381e789265507a3d3e2135113d1"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgrieser%2Ffinder-vim-mode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgrieser%2Ffinder-vim-mode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgrieser%2Ffinder-vim-mode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgrieser%2Ffinder-vim-mode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrisgrieser","download_url":"https://codeload.github.com/chrisgrieser/finder-vim-mode/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247657281,"owners_count":20974345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["complex-modification","finder-extension","karabiner-elements","macos-finder","macos-finder-extension","vim-emulation","vim-emulator","vim-mode"],"created_at":"2024-07-31T16:02:04.219Z","updated_at":"2025-04-07T13:08:28.104Z","avatar_url":"https://github.com/chrisgrieser.png","language":"Shell","funding_links":["https://www.paypal.me/ChrisGrieser","https://ko-fi.com/pseudometa","https://ko-fi.com/Y8Y86SQ91'"],"categories":["File Management","Shell"],"sub_categories":[],"readme":"# Vim Mode for Finder\nFeature-rich control of macOS Finder without the mouse, inspired by vim and\nranger.\n\n![Last commit shield](https://img.shields.io/github/last-commit/chrisgrieser/finder-vim-mode?style=plastic)\n\n![Finder vim cheatsheet](./extras/cheatsheet.png)\n\n## Usage examples\n- `wl`: Duplicate selected file and open the copy.\n- `axq`: Select all files, move them to the other window, close current window.\n- `.f.d.`: Show hidden files, select first hidden file, delete it, hide dotfiles\n  again.\n- `AM`: Select files (but not folders), create a new directory, move selected\n  files into that directory, and start renaming the directory (enters insert\n  mode).\n- `azmhp`: Select all files and folders, zip them (and wait for zipping to\n  finish), and move the archive one directory up\n\n## Table of contents\n\n\u003c!-- toc --\u003e\n\n- [Usage](#usage)\n- [Installation](#installation)\n- [Updates](#updates)\n- [Caveats](#caveats)\n- [Build](#build)\n- [Credits](#credits)\n- [About the developer](#about-the-developer)\n\n\u003c!-- tocstop --\u003e\n\n## Usage\n- Only works in Finder's `List View`.\n- __`:help`__ Press `?` in Finder to display the cheatsheet above. Generally,\n  everything in brackets only applies to the uppercase version of the key.\n- __Move__: `m` marks the current selection as \"to be moved.\" The next\n  paste-operation `p` moves the files. A move can be aborted via `esc`.\n- __Cross-move__: If you have *exactly* two Finder windows open, `x` moves the\n  selection to the other window, and `X` copies the selection to the other\n  window.\n- __Context-menu__: Can be opened with `c` and navigated via `hjkl`. Press\n  `esc`, `q`, or `c` to close the context-menu.\n- __Find mode__ is triggered via `f`, works similar to `f` in vim, expecting\n  another character afterward. For example, `fh` jumps to the next file that\n  starts with the letter `h`.\n- __Toggle `-bkp` suffix__: Add suffix `-bkp` to the file. If it already has\n  such a suffix, remove it. Useful for debugging as well.\n- __`Tab`__ goes to the next file in alphabetical order, *even when the view is\n  not sorted alphabetically.* (This is actually a built-in feature of Finder,\n  but worth mentioning since barely anyone knows about it.)\n- __Copy/Paste file content:__ `Y` copies the content of the selected file, while\n  `P` pastes text from the clipboard into the selected file (appending).\n\n\u003e [!NOTE]\n\u003e __Pressing `return` in a prompt window__, for example when replacing a file,\n\u003e mistakenly puts you in Insert Mode. Unfortunately, Karabiner is not able to\n\u003e detect whether the front window is a regular Finder window or a prompt. The\n\u003e workaround is to either press `esc` to go back to Normal Mode, or to use `tab`\n\u003e and then `space` to select the correct action in the prompt window.\n\n## Installation\nThis plugin requires you to have __English as your System UI language__. (You\ncan set the language via: `System Settings → General → Language \u0026 Region →\nPreferred Languages`)\n\n1. Run this in your terminal:\n\n    ```bash\n    brew install karabiner-elements # Install Karabiner (if not already installed)\n\n    worktree=\"https://raw.githubusercontent.com/chrisgrieser/finder-vim-mode/main\"\n    open \"karabiner://karabiner/assets/complex_modifications/import?url=$worktree/finder-vim.json\"\n    curl -sL \"$worktree/extras/cheatsheet.png\" --create-dirs --output \"$HOME/.config/karabiner/assets/finder-vim-mode/cheatsheet.png\"\n    curl -sL \"$worktree/extras/notificator\" --create-dirs --output \"$HOME/.config/karabiner/assets/finder-vim-mode/notificator\"\n\n    # set default view to \"List\"\n    defaults write com.apple.finder FXPreferredViewStyle -string \"Nlsv\"\n    # optional: disable desktop icons \u0026 make desktop unfocussable\n    defaults write com.apple.finder CreateDesktop false\n    # restart Finder for changes to take effect\n    killall Finder\n    ```\n\n2. Activate the plugin: `Import` → `Enable`\n3. *Karabiner users:* If you already use Karabiner and have another modification\n   affecting the `Capslock` key, the other modification must come __below__ the\n   *Finder Vim Mode* in the list of modifications. (Karabiner prioritizes\n   modifications further on top of the list.)\n   \u003c!-- LTeX: enabled=false --\u003e\n4. *Alfred users:* In [the Appearance\n   Options](https://www.alfredapp.com/help/appearance/#options), you need to set\n   the `Focusing` behavior to `Compatibility Mode` for Karabiner to detect\n   Alfred being active.\n   \u003c!-- LTeX: enabled=true --\u003e\n5. *Spotlight users:* You need to install the Spotlight add-on. The add-on has to\n   be __above__ the Finder Vim Mode in Karabiner's list of modifications.\n\n    ```bash\n    # install Spotlight addon\n    open \"karabiner://karabiner/assets/complex_modifications/import?url=https://raw.githubusercontent.com/chrisgrieser/finder-vim-mode/main/addons/finder-vim-spotlight-addon.json\"\n    ```\n\n6. The first time you receive a notification, you are asked whether\n   notifications should be allowed or not.\n\n## Updates\nUnfortunately, Karabiner has no mechanism for auto-updating plugins. Therefore,\nyou have to install updates manually by re-running the code above. You can check\nfor the last commit date to see whether there has been an update:\n\n![Last commit shield](https://img.shields.io/github/last-commit/chrisgrieser/finder-vim-mode?style=plastic)\n\n## Caveats\nSince Karabiner plugins are only hotkey re-mappings without proper scripting\nmechanisms, this plugin has some limitations:\n- Only __List view__ is supported.\n- If you __use the mouse to click buttons__, you can end up in the wrong mode.\n  In that case, you can press `esc` to get back to Normal Mode.\n- File selection dialogues from other apps (for example to upload a file in the\n  browser) are not supported.\n- Unfortunately, it is __not possible to have a `vimrc` or to let the user\n  configure the keybindings__ themselves in any way, at least not with a\n  Karabiner plugin. If you want to rebind keys, you have to change the\n  respective key manually in the JSON file.\n- If you have set __custom keybindings for Finder__, they can potentially\n  interfere. It is therefore recommended to unset them.\n- The plugin has been tested with the __US and German keyboard layout__. It\n  should mostly also work for other layouts.\n\n## Build\nKarabiner plugins are essentially hotkey configurations in form of a JSON file.\nSince the amount of configurations for this plugin is rather large, the\nresulting JSON file ~8000 lines. To make that manageable, this plugin is written\nin YAML, where features such as [anchors and\naliases](https://www.linode.com/docs/guides/yaml-anchors-aliases-overrides-extensions/)\nreduce the lines of code to only ~1300 lines.\n\nIf you want to fork this plugin, it is recommended to work with the YAML file\nand \"compile\" it to the [JSON required by\nKarabiner](https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/).\nYou can do so with [yq](https://github.com/mikefarah/yq):\n\n```bash\n# `explode()` required to resolve the anchors and aliases\nyq --output-format=json 'explode(.)' finder-vim.yaml \u003e finder-vim.json\n```\n\n## Credits\n- The cheatsheet has been created with \u003chttp://www.keyboard-layout-editor.com/\u003e.\n- The notification script is a modified version of the [Notificator by Vítor\n  Galvão](https://github.com/vitorgalvao/notificator).\n\n\u003c!-- vale Google.FirstPerson = NO --\u003e\n## About the developer\nIn my day job, I am a sociologist studying the social mechanisms underlying the\ndigital economy. For my PhD project, I investigate the governance of the app\neconomy and how software ecosystems manage the tension between innovation and\ncompatibility. If you are interested in this subject, feel free to get in touch.\n\n- [Academic website](https://chris-grieser.de/)\n- [ResearchGate](https://www.researchgate.net/profile/Christopher-Grieser)\n- [Mastodon](https://pkm.social/@pseudometa)\n- [LinkedIn](https://www.linkedin.com/in/christopher-grieser-ba693b17a/)\n\n\u003ca href='https://ko-fi.com/Y8Y86SQ91' target='_blank'\u003e \u003cimg height='36'\nstyle='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3'\nborder='0' alt='Buy Me a Coffee at ko-fi.com' /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisgrieser%2Ffinder-vim-mode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrisgrieser%2Ffinder-vim-mode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisgrieser%2Ffinder-vim-mode/lists"}