Key binding conventions - what keys should packages use?

In the official docs on keybinding conventions, [https://www.gnu.org/software/emacs/manual/html\_node/elisp/Key-Binding-Conventions.html](https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html) it says "Don’t define C-c *letter* as a key in Lisp programs", and while "C-x" isn't mentioned, my understanding is that anything beginning with "C-x" is reserved for Emacs itself. It also states "Sequences consisting of C-c followed by any other ASCII punctuation or symbol character are allocated for minor modes". However, many downloadable packages provide functions that are intended to be globally accessible, independently of major or minor modes. Many packages that I use, such as Magit, rg, projectile, suggest global keybindings to access their functionality (or even provide functions that will set "default" keybindings in the sacred "C-c *letter*" space!) These are all over the place - Magit uses "C-x", Tide uses "M-," and "M-.", and so on. The most common case seems to be, the package recommends binding some functions to key combinations in the "C-c *letter*" space, but doesn't actually perform the binding itself. I'm wondering if there have been any discussions of this topic in the emacs community, and if there is any consensus or tentative directions proposed. Thanks!

Personally I'm fine with packages binding nothing and leaving suggestions or personal preferences from the authors in their README The only exceptions that I can think of are: - `C-z` from Evil although I don't know whether it comes from Vim itself but conflicts with a suspend command. As I started discovering Evil bindings it has saved me quite a few times - `C-h` and similar in transient states when a new user might be lost using the feature and looking for contextual help eg. in the middle of minibuffer completion, transient popup

> Magit uses "C-x" it doesn't

> my understanding is that anything beginning with "C-x" is reserved for Emacs itself Your understanding is mistaken. > suggest global keybindings to access their functionality (or even provide functions that will set "default" keybindings in the sacred "C-c letter" space!) There's nothing wrong with that. As long as the functions aren't invoked without the user doing something, that's just another way of suggesting key bindings. What's important is that it be a user choice to make such bindings. > the package recommends binding some functions to key combinations in the "C-c letter" space, but doesn't actually perform the binding itself. Again, nothing wrong with suggesting or recommending key bindings that are among the bindings reserved for users. Users can bind or rebind any keys they like. The point of *reserving* some keys for users is to prevent/avoid having libraries *impose* those keys - as opposed to letting users choose them. Suggestion/recommendation is not imposition.

Like others, i like when there is nothing by default, but some examples in the github documentation. Or when a proposed keymap is there but not enabled by default and you choose the prefix keybinding to trigger the keymap.

It does magit-define-global-key-bindings is ‘t by default.

C-z is suspend in vim

Right, so that's even more surprising to me that Evil binds the Emacs state to that key

> Your understanding is mistaken. Can you enlighten me? As for the rest of your post... it doesn't really seem to be addressing my question.

1. Nothing anywhere suggests that prefix key `C-x` is reserved for Emacs itself. And in fact NO key bindings are reserved *from users* for Emacs itself. Users can bind any keys. But if you mean only reserved from 3rd-party code, then it's also true that nothing suggests such reservation. 2. As for the rest, I responded to / commented on specific bits of what you wrote. IOW, I addressed those specific parts of your question explicitly. If you don't think what I wrote helps you with your question, so be it. Hopefully feedback from someone else will help.

What does evil map C-z to? (I use vim, but I don't use evil)

I can’t imagine something like Org coming without keybindings, just suggestions. Defining everything in init.el would be a hell. Extremely inconvenient.

It does. `C-x g` is the obvious example.

A toggle for Emacs state

I think the manual explains it well. You shouldn’t provide a `C-c letter` (e.g. `C-c v`) in any packages. This is a convention. If you suggest the user to bind `C-c v` it’s okay. You are not binding it, and the user may just ignore you. The whole idea is to let the users know that they will keep that space for themselves, not being overridden by any package. If any package provides `C-c letter` however, you should report it as a bug or tell the maintainer. There’s no convention about `C-x` yet, so just try not to override common usages, maybe including Magit.

Users can bind any keys, packages too. Users are ASKED not to bind some keys and so are packages.

`C-x g is undefined`

``` These bindings may be added when `after-init-hook' is run. Each binding is added if and only if at that time no other key is bound to the same command and no other command is bound to the same key. ``` I see, we are both right and wrong at the same time :)

* No, users are ***not*** asked to not bind any keys. Users are advised against binding some keys -- *very few* -- keys such as `ESC` and `C-u`. Nothing prevents users from binding whatever keys they like, but Emacs tells them *why* they typically *won't want to* bind those few keys. * Package authors are asked/advised to respect the GNU Emacs key-binding conventions that are used in common. This includes not binding keys just by loading the package.

and there is the built-in winner-mode, which uses C-c left/right by default. so much about Emacs following its own recommendation :) but this is the world we live in... There is a lot of baggage accretes in software, which "lives" this long and values backwards compatibility over being consistent with the keybindings with the underlying OS. It's such a tension, which doesn't have an obvious or objectively best resolution.