Corgi key binding policy

[plexus]

I posted this on the Corgi channel on the lambda island discord, reposting it here for reference and visibility. At some point this will have to make it into the docs.

Corgi has the opportunity of a fresh start, we have so far been relatively conservative in adding bindings. Our set of key bindings will grow, but we want it to grow in a reasoned way. What follows are guidelines to help decide if a certain key binding should be included with stock Corgi.

• we start from vanilla vim as a baseline, we try hard not to redefine a vanilla vim binding (we generally get these from evil, so we don't typically define these ourselves)
• two exceptions to that:
  • it's a trade-off that is really worth it for clojure devs, e.g. having </>/L/H as single-character commands (barf/slurp/previous sexp/next sexp) provides two orders of magnitude more value to a clojure dev than shift text left/right and top of buffer/bottom of buffer
  • in a certain mode there's something that is conceptually closer to the intent of the vim command, e.g. in dired-mode i switches to wdired-mode. You can still think of it as "insert"
• keys that are not bound in vanilla vim are fair game, but very few (if any) single-character keys are still available
• SPC and , are two leader keys where we put most of our bindings, with SPC being general bindings that work more or less the same anywhere, and , being more mode-specific/language specific behavior
• Within these bindings we care about
  • Good consistent categories: SPC f is all about files, SPC j is all about jumping
  • Good mnemonics: SPC f f = find file, SPC j c is Jump to last Change, etc
  • Not nesting too deep, we have a big space with just leader+two characters, we should rarely have to go three characters deep. (we already have some exceptions, like SPC f e i, and these might move to SPC e i (Emacs Init file)
  • Consistency across modes, if , x y does something in a clojure file, it should not do something wildly different in a JS file
  • discoverability is a big goal here, you can press SPC or , and wait for which-key, and explore and learn Corgi's bindings that way
• vim has some other "leader" keys, e.g. g is a prefix for an amalgamation of things, it's not using the whole space so there's some room in there to add our own
• according to some docs I find [ and ] were to navigate to previous next curly. Maybe that was in original vi, it seems in modern vim they are also prefix keys witth quite a lot of bindings under them. I'm not sure to what extent evil copies these, but currently by loading evil-collection we also get evil-collection-unimpaired which (re-?)binds a bunch of these. There's an open issue for this, we may drop evil-unimpaired and take ownership of that space ourselves.
• Any bindings that are not vanilla vim, and not explicitly defined by corgi-keys, are working by accident, they are not part of Corgi's interface and are fair game to rebind in future versions. This includes all of Emacs' default bindings and any bindings introduced by packages
• If there are Spacemacs (or Doom or whatever) bindings that people particularly pine for then they are free game to be added, but they have to adhere to this policy. In particular spacemacs bindings are often too deeply nested, and inconsistent across mode, and often lack good mnemonics, so for each binding someone will have to make a case why we should add it
• In summary, we cater for vim users first, Spacemacs users second, "legacy" emacs users third, while trying to learn from the mistakes of Spacemacs, so that we can end up with a set of bindings that are consistent and intuitive and "good" (for some value of good) in their own right

[otfrom]

Thx for this. Looking at these design principles has helped me find keybindings for the user-keys as well.