{"id":16406748,"url":"https://github.com/ambrevar/evil-special-modes","last_synced_at":"2025-09-03T16:32:05.714Z","repository":{"id":86812895,"uuid":"106851648","full_name":"Ambrevar/evil-special-modes","owner":"Ambrevar","description":"[DISCONTINUED] See https://github.com/jojojames/evil-collection instead","archived":false,"fork":false,"pushed_at":"2017-11-07T08:04:28.000Z","size":69,"stargazers_count":34,"open_issues_count":0,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-16T23:52:39.736Z","etag":null,"topics":["emacs","evil","vim"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ambrevar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2017-10-13T17:03:37.000Z","updated_at":"2020-07-30T15:56:11.000Z","dependencies_parsed_at":"2023-07-12T10:15:16.991Z","dependency_job_id":null,"html_url":"https://github.com/Ambrevar/evil-special-modes","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ambrevar%2Fevil-special-modes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ambrevar%2Fevil-special-modes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ambrevar%2Fevil-special-modes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ambrevar%2Fevil-special-modes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ambrevar","download_url":"https://codeload.github.com/Ambrevar/evil-special-modes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231874118,"owners_count":18439217,"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":["emacs","evil","vim"],"created_at":"2024-10-11T06:10:45.793Z","updated_at":"2024-12-30T18:58:31.849Z","avatar_url":"https://github.com/Ambrevar.png","language":"Emacs Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evil Special Modes\n\nThis is a collection of [Evil](https://github.com/emacs-evil/evil) bindings for\n_the rest of Emacs_ that Evil does not cover by default, such as `help-mode`,\n`M-x calendar`, Eshell and more.\n\n**Warning:** This repo isn't receiving updates anymore, please refer to:\nhttps://github.com/jojojames/evil-collection.\n\n\n\n## Goals\n\n1. Reduce context switching: As soon as \"moving around\" gets hardwired\nto `\u003chjkl\u003e`, it becomes frustratingly inefficient not to have it everywhere.\n\n2. Community work: setting up bindings is tremendous work and joining force can\nonly save hours for all of Evil users out there.  While not everyone may agree\non the chosen bindings, it helps to have something to start with rather than\nnothing at all.  In the end, users are free to override a subset of the proposed\nbindings to best fit their needs.\n\n3. Consistency: Having all bindings defined in one place allows for enforcing\nconsistency across special modes and coordinating the community work to define a\nreference implementation.\n\n\n\n## Installation\n\n- Clone or download this repository.\n\n- Modify your `load-path`:\n\n\t(add-to-list 'load-path (expand-file-name \"/path/to/evil-special-modes/\" user-emacs-directory))\n\n- Register the bindings, either all at once:\n\n\t(when (require 'evil-special-modes nil t)\n\t  (evil-special-modes-init))\n\nor mode-by-mode, for instance:\n\n\t(with-eval-after-load 'calendar (require 'evil-calendar) (evil-calendar-set-keys))\n\nThe list of supported modes is simply the list of files.\n\nIf you want to enable Evil in the minibuffer, you'll have to turn it on\nexplicitly.  This is so because many users find it confusing.\n\n\t(require 'evil-minibuffer)\n\t(evil-minibuffer-init)\n\n\n\n## Guidelines\n\nThe following rules serve as guiding principles to define the set of standard\nEvil bindings for various modes.  Since special modes are by definition\nstructurally incomparable, those rules cannot be expected to be applied\nuniversally.\n\nThe rules are more-or-less sorted by priority.\n\n0. Don't bind anything to `:` nor `\u003cescape\u003e`.\n\n1. Keep the movement keys when possible and sensible.\n\n\t- `h`, `j`, `k`, `l`\n\t- `w`, `W`, `b`, `B`, `e`, `E`, `ge`, `gE`\n\t- `f`, `F`, `t`, `T`, `;`, `,`\n\t- `gg`, `G`\n\t- `|`\n\t- `(`, `)`\n\t- `{`, `}`\n\t- `%`\n\t- `+`, `-`, `0`, `^`, `$`\n\t- `C-i`, `C-o`\n\n2. Keep the yanking and register keys when possible and sensible.\n\n\t- `y`, `Y`\n\t- `\"`\n\n3. Keep the search keys when possible and sensible.\n\n\t- `/`, `?`\n\t- `#`, `*`\n\n4. Keep the mark keys when possible and sensible.\n\n\t- `m`\n\t- `'`, `\\``\n\n5. Keep the windowing keys when possible and sensible.\n\n\t- `H`, `L`, `M`\n\t- `C-e`, `C-y`\n\t- `C-f`, `C-b`\n\t- `C-d`, `C-u`\n\t- `C-w`-prefixed bindings.\n\t- Some `z`-prefixed bindings (see below).\n\n6. The following keys are free when insert-mode does not make sense in the\ncurrent mode:\n\n\t- `a`, `A`, `i`, `I`\n\t- `c`, `C`, `r`, `R`, `s`, `S`\n\t- `d`, `D`, `x`, `X`\n\t- `o`, `O`\n\t- `p`, `P`\n\t- `=`, `\u003c`, `\u003e`\n\t- `J`\n\t- `~`\n\n\tAny of those keys can be set to be a prefix key.\n\n7. Prefix keys: `g` and `z` are the ubiquitous prefix keys.\n\n\t- `g` generally stands for \"go\" and is best used for movements.\n\t- `z` is used for scrolling, folding, spell-checking and more.\n\n8. Macro and action keys\n\n\t- `@`, `q`\n\t- `.`\n\n\n\n## Rationale (Work in progress)\n\nMany special modes share the same set of similar actions.  Those actions should\nshare the same bindings across all modes whenever feasible.\n\n### Motion (`[`, `]`, `{`, `}`, `(`, `)`, `C-j`, `C-k`)\n\n- `[` and `]`: Use `[[` and `]]` for navigation between sections.\n\n\tIf the mode makes no difference between the end of a section and the beginning\nof the next, use `[` and `]`.\n\n- `C-j`, `C-k`: If there is granularity, i.e. subsections, use `C-j` and `C-k`\nto browse them.  This reflects [evil-magit][] and [evil-mu4e][] default\nbindings.\n\n- `{`, `}`: If there is no paragraph structure, `{` and `}` can be used for sub-sectioning.\n\n- `(`, `)`: If there is no sentence structure, `(` and `)` can be used for sub-sectioning.\n\n- `HJKL`: `hjkl` can be used for atomic movements, but `HJKL` can usually not be used\nbecause `H`, `K` and `L` are all universal (`J` is `evil-join` and usually\ndoes not make sense in special modes).\n\n- `C-h` should not be remapped: Since we have `C-j` and `C-k` for vertical motion, it would\nmake sense to use `C-h` and `C-l` for horizontal motion.  There are some\nshortcomings though:\n\n\t- In Vim, `C-h` works as backspace, but Evil does not follow that behaviour.\n\n\t- In Emacs, it is a prefix key for all help-related commands, and so is `\u003cf1\u003e`.\n\n\t- Most importantly, `C-h` is too widespread and ubiquitous to be replaced.\n      So we don't.\n\n- As a consequence of the former point, `C-l` is available.\n\n- `M-\u003chjkl\u003e`: Those keys are usually free in Evil but still bound to their Emacs\ndefault (e.g. `M-l` is `downcase-word`).  Besides, if `C-j`/`C-k` are\nalready used, having `M-j` and `M-k` might add up to the confusion.\n\n### Quitting (`q`, `ZQ`, `ZZ`)\n\nIn Vim, `q` is for recording macros.  In most Emacs special modes, it stands for\nquitting while macros are recorded/played with `\u003cf3\u003e` and `\u003cf4\u003e`.\nVim quits with `ZZ` or `ZQ`.\n\nA good rule of thumb would be:\n\n- Always bind `ZZ` and `ZQ` to the quitting function(s), `evil-quit` if nothing\n  else makes sense.\n\n- Bind `q` to `evil-quit` if macros don't make sense in current mode.\n\n- If macros don't make sense in current mode, then `@` is available.\n\n### Refreshing / Reverting (`gr`)\n\n`gr` is used for reverting in [evil-magit][], [evil-mu4e][], and some Spacemacs\nconfigurations (org-agenda and neotree among others).\n\n`C-l` is traditionally used to refresh the terminal screen.\n\n### Marking\n\nEmacs inconsistently uses \"u\" and \"U\" to unmark.  Since in Vim those keys are\nusually bound to \"undo\", they are probably best left to commands that undo\nactions in the buffer and not undo marks.\n\n`m` defaults to `evil-set-marker` which might not be very useful in special\nmodes.  This is somewhat debatable though.\n\nSuggested mark bindings:\n\n- `m`: Mark or toggle mark, depending on what the mode offers.\n\n- `~`: Toggle all mark.  This mirrors the \"invert-char\" Vim command bound to `~`\nby default.\n\n- `M`: Remove all marks.\n\n- `%`: Mark regexp.\n\n- `x`: Execute action on marks.  This mirrors Dired's binding of `x`.\n\nWhile `m` won't be available for setting marks (in the Vim sense), `'`can still be\nused as it can jump to other buffers.\n\nOptionally:\n\n- `*`: Mark all, because `*` is traditionally a wild card.\n\n- `#`: Remove mark.  This is useful when we want to unmark a region having both\nmarked and unmarked entries.  But `M` could also be made to remove all marks on\nregion, making this binding useless.\n\n### Filtering / Narrowing / Searching.\n\n`s` and `S` seem to be used in some places like [mu4e][].\n\n- `s`: [s]elect/[s]earch/filter candidates according to a pattern.\n\n- `S`: Remove filter and select all.\n\n- `=` is also free and its significance is obvious.\n\n- `|` is not free but the pipe symbolic is very tantalizing.\n\n### Sorting\n\n- `o`: Change the sort [o]rder.\n- `O`: Sort in reverse order.\n\npackage-menu uses `S`.\n\nproced and Dired use `s`.\n\nprofiler uses `A` and `D`.\n\nmu4e uses `O`.\n\n[ranger](http://www.nongnu.org/ranger/) uses `o`.\n\n### Jumping / Interactive \"goto\" (`gd` and `.`)\n\n- `gd`: [g]o to [d]efinition.\n\n- `.`: go to current entity (day for calendar, playing track for [EMMS][]).\nBind only if more relevant than `evil-repeat`.\n\nmu4e has `j` in Emacs, `J` in Evil.\n\n### Browse URL (`gx`)\n\n`gx`: go to URL.  This is a default Vim binding.\n\n### Help (`?`)\n\nIf searching makes sense, keep `?` for backward search.\nIf not, it can be used to display help.\n\n### History browsing (`C-n`, `C-p`)\n\n`C-n` and `C-p` are standard bindings to browse the history elements.\n\n### Bookmarking\n\n?\n\n\n\n## Modes left behind\n\nSome modes might still remain unsupported by this package.  Should you be\nmissing your `\u003chjkl\u003e`, feel free to file an issue or even a pull request.\n\n\n\n## Third-party packages\n\nTo keep the goals of this package within reach, we restrict the changes to\nvanilla Emacs modes.\n\nThird-party packages are provided by several parties:\n\n- [evil-ediff][]\n- [evil-magit][]\n- [evil-mu4e][]\n- Org-mode: https://github.com/GuiltyDolphin/org-evil or https://github.com/Somelauw/evil-org-mode\n\nShould you know any suitable package not mentioned in this list, let us know and\nfile an issue.\n\nOther references:\n\n- [Spacemacs](http://spacemacs.org)\n- [Doom Emacs](https://github.com/hlissner/doom-emacs/blob/master/modules/private/hlissner/%2Bbindings.el)\n\n[EMMS]: https://www.gnu.org/software/emms/\n[evil-ediff]: https://github.com/emacs-evil/evil-ediff\n[evil-magit]: https://github.com/emacs-evil/evil-magit\n[evil-mu4e]: https://github.com/JorisE/evil-mu4e\n[mu4e]: https://www.djcbsoftware.nl/code/mu/mu4e.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambrevar%2Fevil-special-modes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fambrevar%2Fevil-special-modes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambrevar%2Fevil-special-modes/lists"}