An alternative M-x interface for Emacs.
Emacs Lisp Makefile
Pull request Compare This branch is 105 commits ahead of nonsequitur:master.
Latest commit ba09f5e Aug 30, 2017 @DarwinAwardWinner Update buttercup

README.mkdn

Amx, an alternative interface for M-x in Emacs

Build Status MELPA

Amx is an alternative interface for M-x in Emacs. It provides several enhancements over the ordinary execute-extended-command, such as prioritizing your most-used commands in the completion list and showing keyboard shortcuts, and it supports several completion systems for selecting commands, such as ido and ivy.

Installation

Amx is not yet available in MELPA or another package repository for easy installation, but it should be soon. Until then, you will need to install it manually.

Download amx.el from this repository and put it somewhere in your emacs load-path. Then run M-x load-library amx to load it, or put (require 'amx) in your .emacs file.

If you want to use the ido or ivy backends, you'll need to install the linked packages as well. If you already have these installed and enabled, Amx should use them automatically.

Since Amx is a fork of Smex, it retains compatibility with the format of smex-save-file. If you are migrating from smex to Amx, Amx will automatically load your smex saved history the first time it is used, so all your frequently-used commands will still be sorted at the top.

Usage

To replace regular M-x with Amx, use M-x amx-mode. This will remap execute-extended-command (the command normally run by M-x) to amx. You can verify that Amx is active by checking for keyboard shortcuts in the completion buffer. If you need to turn it off, use M-x amx-mode again. Customize this variable to permananely enable the mode.

Completion backends

Amx currently supports 3 different completion backends: standard Emacs completion, Ido completion, and ivy completion. By default, Amx automatically detecs when ido-mode or ivy-mode are enabled, and uses the appropriate backend. So you should generally get the same kind of completion that you're already used to. However, you can also force Amx to use a specific completion system by customizing the variable amx-backend.

Showing keyboard shortcuts for commands

When completing command names, Amx shows the keyboard shortcut for all commands currently bound to a key, so you can find out when there's an easier way to run the command you're looking for. Alternatively, if you know the keyboard shortcut but don't remember the name of the command it's bound to, you can complete based on the keyboard shortcut (this works best with ido or ivy backends). If you don't like this, you can disable it by customizing amx-show-key-bindings.

Getting help for commands

C-h f, while Amx is active, runs describe-function on the currently selected command.

M-. jumps to the definition of the selected command.

C-h w shows the key bindings for the selected command. (Via where-is.)

Show only major mode commands

amx-major-mode-commands runs Amx, limited to commands that are relevant to the active major mode. Note that this command is not bound to any key by default, so if you use it a lot, you should add your own key binding for it.

Show unbound commands

amx-show-unbound-commands shows frequently used commands that have no key bindings.

Persistence between sessions

Amx keeps a file to save its state betweens Emacs sessions. The default path is ~/.emacs.d/amx-items; you can change it by customizing the variable amx-save-file. Unlike Smex, it should be safe to change the save file after loading Amx.

If amx-save-file does not exist but smex-save-file is defined and does exist, Amx will load its state from that file instead. This facilitates migrating from Smex to Amx while retaining all of your saved command history.

Ignoring commands

Certain commands are not very useful to run via M-x. These include commands that only have an effect when bound to certain keys (e.g. self-insert-command), commands that are marked obsolete, and commands meant for mouse interaction. Amx will not present these commands in the list of completions, but just in case, it will still let you enter them if you know their name. You can tell Amx to ignore additional commands by customizing amx-ignored-command-matchers.

Speeding up Amx

There are two features that can cause a noticeable delay (around 1/4 of a second) when running amx: command ignoring and showing key bindings. Generally this delay is not a problem, since you can start typing imediately and Amx will catch up after the short delay. However, if it bothers you, these delays can be greatly reduced by setting one or both of amx-ignored-command-matchers and amx-show-key-bindings to nil.

Running the tests

Amx comes with a test suite. If you want to run it yourself, first install the cask dependency manager. Then, from the package directory, run cask install to install all the development dependencies, in particular buttercup. Finally, to run the tests, execute cask exec buttercup -L .. Please run this test suite before submitting any pull requests, and note in the pull request whether any of the tests fail.

Relationship to Smex

Amx is a fork of Smex, which appears to no longer be under active development. However, Amx has diverged significantly from Smex and should be considered a separate package. New features include multiple completion backends, showing/completing on key bindings, and hiding irrelevant commands.

Since the last tagged release of Smex was version 3.0, the first release version of Amx will be 4.0.