Get help with your keystrokes
Emacs is called the self-documenting editor, because the Emacs help key
is available to give you documentation about every command and
keystroke—whenever you're entering an Emacs command, you can use the
help key to get assistance. The Emacs help key is defined as
C-h. All Emacs help facilities begin with this
This section describes the help commands you can use to get help with particular keystrokes.
Every keystroke you can type in Emacs is documented, and there are a few ways Emacs can tell you what a particular keystroke is for.
The first and quickest way is through the
describe-key-briefly function, which lets you input a
keystroke and then tells you, in the minibuffer, the name of the function that
keystroke executes. It's bound to
Start Emacs now, and try getting help with some keystrokes:
C-h c C-x C-c C-h c C-h l C-h c C-h c
You can also get more detailed information about a particular keystroke. The
C-h k, gives more information about a key or
keystroke, opening a new help buffer in a help window that describes its
use. Try running it with a letter key:
C-h k k
As you see from the new window that appears, the K key is bound to the
self-insert-command function, which inserts the given keyboard
character (in this case,
k) at point in the current
Try finding out what the
C-x k command does:
C-h k C-x k
The general help prefix,
C-h, takes on a special
meaning when you use it as a postfix
—when you type
C-h after some other control-character prefix, you
get a new buffer that lists all the available key bindings for that prefix.
For example, the
C-x keystroke is a frequently used
prefix in Emacs. You learned in the first tutorial in this series (see
Resources) that the
C-x C-c combination is the usual command to exit
Emacs: As the
save-buffers-kill-emacs function, it
writes all unsaved buffers to disk and then exits the program. You also learned
C-x C-f runs
find-file, which opens a file on the file system into
a new buffer of its own. But what else has a
Find out: Type
C-x C-h to get a list of
When you type this, a new *Help* buffer opens, giving a list of all possible
keystrokes that begin with the
In a previous tutorial in this series, you learned how to switch between
windows and how to resize them—type
o C-x 1 to move to the *Help* buffer window, and
then resize it to fill the Emacs frame, so your Emacs session looks like
Figure 1. Getting a list of all possible C-x keystroke combinations
When you're done perusing the *Help* buffer, type
to kill it.
The Emacs help key is more than just a prefix: You can use it even if you're in
the middle of typing a command. Whenever you'd like to know which commands are
possible for what you've already typed, type
When you do this, Emacs opens a new *Help* buffer. This buffer shows what commands begin with and what you've already typed.
Try getting a list of possible commands for the
a keystrokes. Type
C-x a C-h, and
notice the new *Help* buffer that appears:
Global Bindings Starting With C-x a: key binding --- ------- C-x a C-a add-mode-abbrev C-x a ' expand-abbrev C-x a + add-mode-abbrev C-x a - inverse-add-global-abbrev C-x a e expand-abbrev C-x a g add-global-abbrev C-x a i Prefix Command C-x a l add-mode-abbrev C-x a n expand-jump-to-next-slot C-x a p expand-jump-to-previous-slot C-x a i g inverse-add-global-abbrev C-x a i l inverse-add-mode-abbrev
The Emacs minibuffer offers command completion, which works like its equivalent in the Bash shell and many other UNIX shells.
When you're typing a function and you forget its entire name, you can use completion to get a hint. Press the Tab key whenever you're giving the name of a function, command, or file, and Emacs completes it to the most unique value possible.
For instance, remember from the last tutorial in this series that Emacs can
show you the latest phases of the moon. But if you try typing
M-x phases-of-the-moon right now, it doesn't work:
Emacs reports no match when you tell it to execute that function. Hmm.
You know that this function began with phases. What was the
To find out, try running it with completion:
M-x pha Tab
When you do this, Emacs completes the command for you. The correct function appears in the minibuffer:
Are any other functions available that begin with this name? Press Tab again to see, and look at what the minibuffer says:
M-x phases-of-moon [Sole completion]
If there were more options beginning with the text phases-of-moon, Emacs would have shown you them.
Press Enter to run the sole completion.
Now, try listing all the functions available: Type
. You can press Tab repeatedly
to scroll down in the list, and then type
destroy the completion-list buffer and cancel your command when you're done.
When more than one completion is possible and Emacs shows a *Completions* buffer in a new window that lists all the possibilities, you can scroll through the completions to select one in various ways:
Click a completion with
B2to select it.
Move to the *Completions* buffer (such as by typing
C-x o), and then press Enter to select the completion nearest to point.
Use the possibilities in the *Completions* buffer as a guide, and type out your selection in the minibuffer.
To demonstrate, try the following:
M-< C-Spacebar M->to select the comment code at the top of the *scratch* buffer as the region.
C-x mo Tabto pull up a *Completions* buffer that shows all functions beginning with the letters mo.
morse-regionto select that function, which converts the text in the region to Morse code.
C-x fi Tabto pull up a *Completions* buffer that shows all functions beginning with the letters fi.
C-x o C-x oto run the
other-windowfunction twice, moving the cursor first from the minibuffer to the *scratch* buffer and then to the *Completions* buffer.
C-nenough times that the cursor is on the
fill-regionfunction, and then press Enter to select that function.
Now your Emacs session should look like Figure 2.
Figure 2. Running a command on the region using completion
You can view and record a literal stream of all the keystrokes you type in Emacs, which is useful for debugging. There are a few ways to do that.
The last 100 keystrokes you made inside Emacs is called the lossage. To
view it, run the
view-lossage function. It's bound to
C-h l keystroke.
When you run this command, it opens a new *Help* buffer and displays the current keyboard lossage in that buffer.
Try it: Type
If you've been following along with the examples in this tutorial, your Emacs session should now look like Figure 3.
Figure 3. Viewing the lossage in Emacs
It's important to note that Emacs stores the actual characters you type, not
just the names of the commands you run. To see the difference, exit Emacs and
then start Emacs again, and view the lossage right away: Type
When you do this, you should see this lossage in the new *Help* window:
M-x v i e w - l o s s a g e <return>
Exit Emacs, start it again, and view the lossage by using completion a couple
of times to complete the command: Type
M-x view Tab l Tab
When you do this, you run the same command as before, but the lossage looks different:
M-x v i e w <tab> l <tab> <return>
If you want to view more than the last 100 keystrokes you've made, you can first open a dribble file; when you do so, Emacs dribbles a copy of everything you type, a single keystroke at a time, into that file until you exit.
To make a dribble file, run the
function. Try it now:
Make a new dribble file: Type
M-x open-dribble-file Enter mydribbles Enter.
Type some text in the *scratch* buffer:
Nothing is ever really lost
View the lossage: Type
M-x view-lossage Enter.
Exit Emacs: Type
After you've done this, look at the contents of your dribble file. It should contain every character you just typed, including the control characters you used to specify Emacs commands.
Table 1 lists the various Emacs commands you can use to get help on keystrokes, giving their function name (if applicable) and describing their purpose.
Table 1. Summary of Emacs keystroke-help commands
||This command performs command completion if given as part of a command, showing all possible input values for the given command.|
||This command describes all the possible commands and functions available for the given command prefix or keystroke.|
||This command reports in the minibuffer the name of function that keystroke is bound to.|
||This command opens a new help-buffer window that describes the function that keystroke is bound to.|
||This command opens a new buffer and displays the last 100 characters typed.|
||This command opens a specified file and dribbles a copy of all keyboard input to that file.|