The Emacs Editor

Emacs is the extensible, customizable, self-documenting real-time display editor. This manual describes how to edit with Emacs and some of the ways to customize it; it corresponds to GNU Emacs version 26.3.

The homepage for GNU Emacs is at https://www.gnu.org/software/emacs/.

To view this manual in other formats, click here.

You can also purchase a printed copy from the FSF store.

For information on extending Emacs, see Emacs Lisp.

This is the GNU Emacs Manual , updated for Emacs version 26.3.

Copyright © 1985–1987, 1993–2019 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being “The GNU Manifesto,” “Distribution” and “GNU GENERAL PUBLIC LICENSE,” with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.” (a) The FSF's Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

Detailed Node Listing

Here are some other nodes which are really subnodes of the ones already listed, mentioned here so you can get to them in one step:

Distribution

GNU Emacs is free software ; this means that everyone is free to use it and free to redistribute it under certain conditions. GNU Emacs is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GNU Emacs that they might get from you. The precise conditions are found in the GNU General Public License that comes with Emacs and also appears in this manual1. See Copying.

One way to get a copy of GNU Emacs is from someone else who has it. You need not ask for our permission to do so, or tell anyone else; just copy it. If you have access to the Internet, you can get the latest distribution version of GNU Emacs by anonymous FTP; see https://www.gnu.org/software/emacs on our website for more information.

You may also receive GNU Emacs when you buy a computer. Computer manufacturers are free to distribute copies on the same terms that apply to everyone else. These terms require them to give you the full sources, including whatever changes they may have made, and to permit you to redistribute the GNU Emacs received from them under the usual terms of the General Public License. In other words, the program must be free for you when you get it, not just free for the manufacturer.

If you find GNU Emacs useful, please send a donation to the Free Software Foundation to support our work. Donations to the Free Software Foundation are tax-deductible in the US. If you use GNU Emacs at your workplace, please suggest that the company make a donation. To donate, see https://my.fsf.org/donate/. For other ways in which you can help, see https://www.gnu.org/help/help.html.

We also sell hardcopy versions of this manual and An Introduction to Programming in Emacs Lisp , by Robert J. Chassell. You can visit our online store at https://shop.fsf.org/. The income from sales goes to support the foundation's purpose: the development of new free software, and improvements to our existing programs including GNU Emacs.

If you need to contact the Free Software Foundation, see https://www.fsf.org/about/contact/, or write to

Free Software Foundation 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA

Introduction

You are reading about GNU Emacs, the GNU incarnation of the advanced, self-documenting, customizable, extensible editor Emacs. (The ‘ G ’ in GNU (GNU's Not Unix) is not silent.)

We call Emacs advanced because it can do much more than simple insertion and deletion of text. It can control subprocesses, indent programs automatically, show multiple files at once, and more. Emacs editing commands operate in terms of characters, words, lines, sentences, paragraphs, and pages, as well as expressions and comments in various programming languages.

Self-documenting means that at any time you can use special commands, known as help commands , to find out what your options are, or to find out what any command does, or to find all the commands that pertain to a given topic. See Help.

Customizable means that you can easily alter the behavior of Emacs commands in simple ways. For instance, if you use a programming language in which comments start with ‘ <** ’ and end with ‘ **> ’, you can tell the Emacs comment manipulation commands to use those strings (see Comments). To take another example, you can rebind the basic cursor motion commands (up, down, left and right) to any keys on the keyboard that you find comfortable. See Customization.

Extensible means that you can go beyond simple customization and create entirely new commands. New commands are simply programs written in the Lisp language, which are run by Emacs's own Lisp interpreter. Existing commands can even be redefined in the middle of an editing session, without having to restart Emacs. Most of the editing commands in Emacs are written in Lisp; the few exceptions could have been written in Lisp but use C instead for efficiency. Writing an extension is programming, but non-programmers can use it afterwards. See Emacs Lisp Intro, if you want to learn Emacs Lisp programming.

1 The Organization of the Screen

On a graphical display, such as on GNU/Linux using the X Window System, Emacs occupies a graphical window. On a text terminal, Emacs occupies the entire terminal screen. We will use the term frame to mean a graphical window or terminal screen occupied by Emacs. Emacs behaves very similarly on both kinds of frames. It normally starts out with just one frame, but you can create additional frames if you wish (see Frames).

Each frame consists of several distinct regions. At the top of the frame is a menu bar , which allows you to access commands via a series of menus. On a graphical display, directly below the menu bar is a tool bar , a row of icons that perform editing commands when you click on them. At the very bottom of the frame is an echo area , where informative messages are displayed and where you enter information when Emacs asks for it.

The main area of the frame, below the tool bar (if one exists) and above the echo area, is called the window . Henceforth in this manual, we will use the word “window” in this sense. Graphical display systems commonly use the word “window” with a different meaning; but, as stated above, we refer to those graphical windows as “frames”.

An Emacs window is where the buffer —the text or other graphics you are editing or viewing—is displayed. On a graphical display, the window possesses a scroll bar on one side, which can be used to scroll through the buffer. The last line of the window is a mode line . This displays various information about what is going on in the buffer, such as whether there are unsaved changes, the editing modes that are in use, the current line number, and so forth.

When you start Emacs, there is normally only one window in the frame. However, you can subdivide this window horizontally or vertically to create multiple windows, each of which can independently display a buffer (see Windows).

At any time, one window is the selected window . On a graphical display, the selected window shows a more prominent cursor (usually solid and blinking); other windows show a less prominent cursor (usually a hollow box). On a text terminal, there is only one cursor, which is shown in the selected window. The buffer displayed in the selected window is called the current buffer , and it is where editing happens. Most Emacs commands implicitly apply to the current buffer; the text displayed in unselected windows is mostly visible for reference. If you use multiple frames on a graphical display, selecting a particular frame selects a window in that frame.

Point: The place in the text where editing commands operate.

Echo Area: Short messages appear at the bottom of the screen.

Mode Line: Interpreting the mode line.

Menu Bar: How to use the menu bar.

1.1 Point

The cursor in the selected window shows the location where most editing commands take effect, which is called point 2. Many Emacs commands move point to different places in the buffer; for example, you can place point by clicking mouse button 1 (normally the left button) at the desired location.

By default, the cursor in the selected window is drawn as a solid block and appears to be on a character, but you should think of point as between two characters; it is situated before the character under the cursor. For example, if your text looks like ‘ frob ’ with the cursor over the ‘ b ’, then point is between the ‘ o ’ and the ‘ b ’. If you insert the character ‘ ! ’ at that position, the result is ‘ fro!b ’, with point between the ‘ ! ’ and the ‘ b ’. Thus, the cursor remains over the ‘ b ’, as before.

If you are editing several files in Emacs, each in its own buffer, each buffer has its own value of point. A buffer that is not currently displayed remembers its value of point if you later display it again. Furthermore, if a buffer is displayed in multiple windows, each of those windows has its own value of point.

See Cursor Display, for options that control how Emacs displays the cursor.

1.2 The Echo Area

The line at the very bottom of the frame is the echo area . It is used to display small amounts of text for various purposes.

The echo area is so-named because one of the things it is used for is echoing , which means displaying the characters of a multi-character command as you type. Single-character commands are not echoed. Multi-character commands (see Keys) are echoed if you pause for more than a second in the middle of a command. Emacs then echoes all the characters of the command so far, to prompt you for the rest. Once echoing has started, the rest of the command echoes immediately as you type it. This behavior is designed to give confident users fast response, while giving hesitant users maximum feedback.

The echo area is also used to display an error message when a command cannot do its job. Error messages may be accompanied by beeping or by flashing the screen.

Some commands display informative messages in the echo area to tell you what the command has done, or to provide you with some specific information. These informative messages, unlike error messages, are not accompanied with a beep or flash. For example, C-x = (hold down <Ctrl> and type x , then let go of <Ctrl> and type = ) displays a message describing the character at point, its position in the buffer, and its current column in the window. Commands that take a long time often display messages ending in ‘ ... ’ while they are working (sometimes also indicating how much progress has been made, as a percentage), and add ‘ done ’ when they are finished.

Informative echo area messages are saved in a special buffer named *Messages* . (We have not explained buffers yet; see Buffers, for more information about them.) If you miss a message that appeared briefly on the screen, you can switch to the *Messages* buffer to see it again. The *Messages* buffer is limited to a certain number of lines, specified by the variable message-log-max . (We have not explained variables either; see Variables, for more information about them.) Beyond this limit, one line is deleted from the beginning whenever a new message line is added at the end.

See Display Custom, for options that control how Emacs uses the echo area.

The echo area is also used to display the minibuffer , a special window where you can input arguments to commands, such as the name of a file to be edited. When the minibuffer is in use, the text displayed in the echo area begins with a prompt string , and the active cursor appears within the minibuffer, which is temporarily considered the selected window. You can always get out of the minibuffer by typing C-g . See Minibuffer.

1.3 The Mode Line

At the bottom of each window is a mode line , which describes what is going on in the current buffer. When there is only one window, the mode line appears right above the echo area; it is the next-to-last line in the frame. On a graphical display, the mode line is drawn with a 3D box appearance. Emacs also usually draws the mode line of the selected window with a different color than that of unselected windows, in order to make it stand out.

The text displayed in the mode line has the following format:

cs : ch - fr buf pos line ( major minor )

On a text terminal, this text is followed by a series of dashes extending to the right edge of the window. These dashes are omitted on a graphical display.

The cs string and the colon character after it describe the character set and newline convention used for the current buffer. Normally, Emacs automatically handles these settings for you, but it is sometimes useful to have this information.

cs describes the character set of the text in the buffer (see Coding Systems). If it is a dash (‘ - ’), that indicates no special character set handling (with the possible exception of end-of-line conventions, described in the next paragraph). ‘ = ’ means no conversion whatsoever, and is usually used for files containing non-textual data. Other characters represent various coding systems —for example, ‘ 1 ’ represents ISO Latin-1.

On a text terminal, cs is preceded by two additional characters that describe the coding systems for keyboard input and terminal output. Furthermore, if you are using an input method, cs is preceded by a string that identifies the input method (see Input Methods).

The character after cs is usually a colon. If a different string is displayed, that indicates a nontrivial end-of-line convention for encoding a file. Usually, lines of text are separated by newline characters in a file, but two other conventions are sometimes used. The MS-DOS convention uses a carriage return character followed by a linefeed character; when editing such files, the colon changes to either a backslash (‘ \ ’) or ‘ (DOS) ’, depending on the operating system. Another convention, employed by older Macintosh systems, uses a carriage return character instead of a newline; when editing such files, the colon changes to either a forward slash (‘ / ’) or ‘ (Mac) ’. On some systems, Emacs displays ‘ (Unix) ’ instead of the colon for files that use newline as the line separator.

On frames created for emacsclient (see Invoking emacsclient), the next character is ‘ @ ’. This indication is typical for frames of an Emacs process running as a daemon (see Emacs Server).

The next element on the mode line is the string indicated by ch . This shows two dashes (‘ -- ’) if the buffer displayed in the window has the same contents as the corresponding file on the disk; i.e., if the buffer is unmodified. If the buffer is modified, it shows two stars (‘ ** ’). For a read-only buffer, it shows ‘ %* ’ if the buffer is modified, and ‘ %% ’ otherwise.

The character after ch is normally a dash (‘ - ’). However, if default-directory (see File Names) for the current buffer is on a remote machine, ‘ @ ’ is displayed instead.

fr gives the selected frame name (see Frames). It appears only on text terminals. The initial frame's name is ‘ F1 ’.

buf is the name of the buffer displayed in the window. Usually, this is the same as the name of a file you are editing. See Buffers.

pos tells you whether there is additional text above the top of the window, or below the bottom. If your buffer is small and all of it is visible in the window, pos is ‘ All ’. Otherwise, it is ‘ Top ’ if you are looking at the beginning of the buffer, ‘ Bot ’ if you are looking at the end of the buffer, or ‘ nn % ’, where nn is the percentage of the buffer above the top of the window. With Size Indication mode, you can display the size of the buffer as well. See Optional Mode Line.

line is the character ‘ L ’ followed by the line number at point. (You can display the current column number too, by turning on Column Number mode. See Optional Mode Line.)

major is the name of the major mode used in the buffer. A major mode is a principal editing mode for the buffer, such as Text mode, Lisp mode, C mode, and so forth. See Major Modes. Some major modes display additional information after the major mode name. For example, Compilation buffers and Shell buffers display the status of the subprocess.

minor is a list of some of the enabled minor modes , which are optional editing modes that provide additional features on top of the major mode. See Minor Modes.

Some features are listed together with the minor modes whenever they are turned on, even though they are not really minor modes. ‘ Narrow ’ means that the buffer being displayed has editing restricted to only a portion of its text (see Narrowing). ‘ Def ’ means that a keyboard macro is currently being defined (see Keyboard Macros).

In addition, if Emacs is inside a recursive editing level, square brackets (‘ [...] ’) appear around the parentheses that surround the modes. If Emacs is in one recursive editing level within another, double square brackets appear, and so on. Since recursive editing levels affect Emacs globally, such square brackets appear in the mode line of every window. See Recursive Edit.

You can change the appearance of the mode line as well as the format of its contents. See Optional Mode Line. In addition, the mode line is mouse-sensitive; clicking on different parts of the mode line performs various commands. See Mode Line Mouse. Also, hovering the mouse pointer above mouse-sensitive portions of the mode line shows tooltips (see Tooltips) with information about commands you can invoke by clicking on the mode line.

1.4 The Menu Bar

Each Emacs frame normally has a menu bar at the top which you can use to perform common operations. There's no need to list them here, as you can more easily see them yourself.

On a display that supports a mouse, you can use the mouse to choose a command from the menu bar. An arrow on the right edge of a menu item means it leads to a subsidiary menu, or submenu . A ‘ ... ’ at the end of a menu item means that the command will prompt you for further input before it actually does anything.

Some of the commands in the menu bar have ordinary key bindings as well; if so, a key binding is shown after the item itself. To view the full command name and documentation for a menu item, type C-h k , and then select the menu bar with the mouse in the usual way (see Key Help).

Instead of using the mouse, you can also invoke the first menu bar item by pressing <F10> (to run the command menu-bar-open ). You can then navigate the menus with the arrow keys or with C-b , C-f (left/right), C-p , and C-n (up/down). To activate a selected menu item, press <RET>; to cancel menu navigation, press C-g or <ESC> <ESC> <ESC> . (However, note that when Emacs was built with a GUI toolkit, the menus are drawn and controlled by the toolkit, and the key sequences to cancel menu navigation might be different from the above description.)

On a text terminal, you can optionally access the menu-bar menus in the echo area. To this end, customize the variable tty-menu-open-use-tmm to a non- nil value. Then typing <F10> will run the command tmm-menubar instead of dropping down the menu. (You can also type M-` , which always invokes tmm-menubar .) tmm-menubar lets you select a menu item with the keyboard. A provisional choice appears in the echo area. You can use the up and down arrow keys to move through the menu to different items, and then you can type <RET> to select the item. Each menu item is also designated by a letter or digit (usually the initial of some word in the item's name). This letter or digit is separated from the item name by ‘ ==> ’. You can type the item's letter or digit to select the item.

2 Kinds of User Input

GNU Emacs is primarily designed for use with the keyboard. While it is possible to use the mouse to issue editing commands through the menu bar and tool bar, that is not as efficient as using the keyboard. Therefore, this manual mainly documents how to edit with the keyboard.

Keyboard input into Emacs is based on a heavily-extended version of ASCII . Simple characters, like ‘ a ’, ‘ B ’, ‘ 3 ’, ‘ = ’, and the space character (denoted as <SPC>), are entered by typing the corresponding key. Control characters , such as <RET>, <TAB>, <DEL>, <ESC>, <F1>, <Home>, and <LEFT>, are also entered this way, as are certain characters found on non-English keyboards (see International).

Emacs also recognizes control characters that are entered using modifier keys . Two commonly-used modifier keys are <Control> (usually labeled <Ctrl>), and <Meta> (usually labeled <Alt>)3. For example, Control-a is entered by holding down the <Ctrl> key while pressing a ; we will refer to this as C-a for short. Similarly, <Meta>-a , or M-a for short, is entered by holding down the <Alt> key and pressing a . Modifier keys can also be applied to non-alphanumerical characters, e.g., C-<F1> or M-<LEFT> .

You can also type Meta characters using two-character sequences starting with <ESC>. Thus, you can enter M-a by typing <ESC> a . You can enter C-M-a (holding down both <Ctrl> and <Alt>, then pressing a ) by typing <ESC> C-a . Unlike <Meta>, <ESC> is entered as a separate character. You don't hold down <ESC> while typing the next character; instead, press <ESC> and release it, then enter the next character. This feature is useful on certain text terminals where the <Meta> key does not function reliably.

On graphical displays, the window manager might block some keyboard inputs, including M-<TAB> , M-<SPC> , C-M-d and C-M-l . If you have this problem, you can either customize your window manager to not block those keys, or rebind the affected Emacs commands (see Customization).

Simple characters and control characters, as well as certain non-keyboard inputs such as mouse clicks, are collectively referred to as input events . For details about how Emacs internally handles input events, see Input Events.

3 Keys

Some Emacs commands are invoked by just one input event; for example, C-f moves forward one character in the buffer. Other commands take two or more input events to invoke, such as C-x C-f and C-x 4 C-f .

A key sequence , or key for short, is a sequence of one or more input events that is meaningful as a unit. If a key sequence invokes a command, we call it a complete key ; for example, C-f , C-x C-f and C-x 4 C-f are all complete keys. If a key sequence isn't long enough to invoke a command, we call it a prefix key ; from the preceding example, we see that C-x and C-x 4 are prefix keys. Every key sequence is either a complete key or a prefix key.

A prefix key combines with the following input event to make a longer key sequence. For example, C-x is a prefix key, so typing C-x alone does not invoke a command; instead, Emacs waits for further input (if you pause for longer than a second, it echoes the C-x key to prompt for that input; see Echo Area). C-x combines with the next input event to make a two-event key sequence, which could itself be a prefix key (such as C-x 4 ), or a complete key (such as C-x C-f ). There is no limit to the length of key sequences, but in practice they are seldom longer than three or four input events.

You can't add input events onto a complete key. For example, because C-f is a complete key, the two-event sequence C-f C-k is two key sequences, not one.

By default, the prefix keys in Emacs are C-c , C-h , C-x , C-x <RET> , C-x @ , C-x a , C-x n , C-x r , C-x v , C-x 4 , C-x 5 , C-x 6 , <ESC>, M-g , and M-o . (<F1> and <F2> are aliases for C-h and C-x 6 .) This list is not cast in stone; if you customize Emacs, you can make new prefix keys. You could even eliminate some of the standard ones, though this is not recommended for most users; for example, if you remove the prefix definition of C-x 4 , then C-x 4 C-f becomes an invalid key sequence. See Key Bindings.

Typing the help character ( C-h or <F1>) after a prefix key displays a list of the commands starting with that prefix. The sole exception to this rule is <ESC>: <ESC> C-h is equivalent to C-M-h , which does something else entirely. You can, however, use <F1> to display a list of commands starting with <ESC>.

4 Keys and Commands

This manual is full of passages that tell you what particular keys do. But Emacs does not assign meanings to keys directly. Instead, Emacs assigns meanings to named commands , and then gives keys their meanings by binding them to commands.

Every command has a name chosen by a programmer. The name is usually made of a few English words separated by dashes; for example, next-line or forward-word . Internally, each command is a special type of Lisp function , and the actions associated with the command are performed by running the function. See What Is a Function.

The bindings between keys and commands are recorded in tables called keymaps . See Keymaps.

When we say that “ C-n moves down vertically one line” we are glossing over a subtle distinction that is irrelevant in ordinary use, but vital for Emacs customization. The command next-line does a vertical move downward. C-n has this effect because it is bound to next-line . If you rebind C-n to the command forward-word , C-n will move forward one word instead.

In this manual, we will often speak of keys like C-n as commands, even though strictly speaking the key is bound to a command. Usually, we state the name of the command which really does the work in parentheses after mentioning the key that runs it. For example, we will say that “The command C-n ( next-line ) moves point vertically down”, meaning that the command next-line moves vertically down, and the key C-n is normally bound to it.

Since we are discussing customization, we should tell you about variables . Often the description of a command will say, “To change this, set the variable mumble-foo .” A variable is a name used to store a value. Most of the variables documented in this manual are meant for customization: some command or other part of Emacs examines the variable and behaves differently according to the value that you set. You can ignore the information about variables until you are interested in customizing them. Then read the basic information on variables (see Variables) and the information about specific variables will make sense.

5 Entering Emacs

The usual way to invoke Emacs is with the shell command emacs . From a terminal window running a Unix shell on a GUI terminal, you can run Emacs in the background with emacs & ; this way, Emacs won't tie up the terminal window, so you can use it to run other shell commands. (For comparable methods of starting Emacs on MS-Windows, see Windows Startup.)

When Emacs starts up, the initial frame displays a special buffer named ‘ *GNU Emacs* ’. This startup screen contains information about Emacs and links to common tasks that are useful for beginning users. For instance, activating the ‘ Emacs Tutorial ’ link opens the Emacs tutorial; this does the same thing as the command C-h t ( help-with-tutorial ). To activate a link, either move point onto it and type <RET> , or click on it with mouse-1 (the left mouse button).

Using a command line argument, you can tell Emacs to visit one or more files as soon as it starts up. For example, emacs foo.txt starts Emacs with a buffer displaying the contents of the file ‘ foo.txt ’. This feature exists mainly for compatibility with other editors, which are designed to be launched from the shell for short editing sessions. If you call Emacs this way, the initial frame is split into two windows—one showing the specified file, and the other showing the startup screen. See Windows.

Generally, it is unnecessary and wasteful to start Emacs afresh each time you want to edit a file. The recommended way to use Emacs is to start it just once, just after you log in, and do all your editing in the same Emacs session. See Files, for information on visiting more than one file. If you use Emacs this way, the Emacs session accumulates valuable context, such as the kill ring, registers, undo history, and mark ring data, which together make editing more convenient. These features are described later in the manual.

To edit a file from another program while Emacs is running, you can use the emacsclient helper program to open a file in the existing Emacs session. See Emacs Server.

Emacs accepts other command line arguments that tell it to load certain Lisp files, where to put the initial frame, and so forth. See Emacs Invocation.

If the variable inhibit-startup-screen is non- nil , Emacs does not display the startup screen. In that case, if one or more files were specified on the command line, Emacs simply displays those files; otherwise, it displays a buffer named *scratch* , which can be used to evaluate Emacs Lisp expressions interactively. See Lisp Interaction. You can set the variable inhibit-startup-screen using the Customize facility (see Easy Customization), or by editing your initialization file (see Init File).4

You can also force Emacs to display a file or directory at startup by setting the variable initial-buffer-choice to a string naming that file or directory. The value of initial-buffer-choice may also be a function (of no arguments) that should return a buffer which is then displayed. If initial-buffer-choice is non- nil , then if you specify any files on the command line, Emacs still visits them, but does not display them initially.

6 Exiting Emacs

C-x C-c Kill Emacs ( save-buffers-kill-terminal ).

C-z On a text terminal, suspend Emacs; on a graphical display, iconify (or “minimize”) the selected frame ( suspend-frame ).

Killing Emacs means terminating the Emacs program. To do this, type C-x C-c ( save-buffers-kill-terminal ). A two-character key sequence is used to make it harder to type by accident. If there are any modified file-visiting buffers when you type C-x C-c , Emacs first offers to save these buffers. If you do not save them all, it asks for confirmation again, since the unsaved changes will be lost. Emacs also asks for confirmation if any subprocesses are still running, since killing Emacs will also kill the subprocesses (see Shell).

C-x C-c behaves specially if you are using Emacs as a server. If you type it from a client frame, it closes the client connection. See Emacs Server.

Emacs can, optionally, record certain session information when you kill it, such as the files you were visiting at the time. This information is then available the next time you start Emacs. See Saving Emacs Sessions.

If the value of the variable confirm-kill-emacs is non- nil , C-x C-c assumes that its value is a predicate function, and calls that function. If the result of the function call is non- nil , the session is killed, otherwise Emacs continues to run. One convenient function to use as the value of confirm-kill-emacs is the function yes-or-no-p . The default value of confirm-kill-emacs is nil .

If the value of the variable confirm-kill-processes is nil , C-x C-c does not ask for confirmation before killing subprocesses started by Emacs. The value is t by default.

To further customize what happens when Emacs is exiting, see Killing Emacs.

To kill Emacs without being prompted about saving, type M-x kill-emacs .

C-z runs the command suspend-frame . On a graphical display, this command minimizes (or iconifies ) the selected Emacs frame, hiding it in a way that lets you bring it back later (exactly how this hiding occurs depends on the window system). On a text terminal, the C-z command suspends Emacs, stopping the program temporarily and returning control to the parent process (usually a shell); in most shells, you can resume Emacs after suspending it with the shell command %emacs .

Text terminals usually listen for certain special characters whose meaning is to kill or suspend the program you are running. This terminal feature is turned off while you are in Emacs. The meanings of C-z and C-x C-c as keys in Emacs were inspired by the use of C-z and C-c on several operating systems as the characters for stopping or killing a program, but that is their only relationship with the operating system. You can customize these keys to run any commands of your choice (see Keymaps).

7 Basic Editing Commands

Here we explain the basics of how to enter text, make corrections, and save the text in a file. If this material is new to you, we suggest you first run the Emacs learn-by-doing tutorial, by typing C-h t ( help-with-tutorial ).

7.1 Inserting Text

You can insert an ordinary graphic character (e.g., ‘ a ’, ‘ B ’, ‘ 3 ’, and ‘ = ’) by typing the associated key. This adds the character to the buffer at point. Insertion moves point forward, so that point remains just after the inserted text. See Point.

To end a line and start a new one, type <RET> ( newline ). (The <RET> key may be labeled <Return>, or <Enter>, or with a funny-looking left-pointing arrow on your keyboard, but we refer to it as <RET> in this manual.) This command inserts a newline character into the buffer, then indents (see Indentation) according to the major mode. If point is at the end of the line, the effect is to create a new blank line after it and indent the new line; if point is in the middle of a line, the line is split at that position. To turn off the auto-indentation, you can either disable Electric Indent mode (see Indent Convenience) or type C-j , which inserts just a newline, without any auto-indentation.

As we explain later in this manual, you can change the way Emacs handles text insertion by turning on minor modes . For instance, the minor mode called Auto Fill mode splits lines automatically when they get too long (see Filling). The minor mode called Overwrite mode causes inserted characters to replace (overwrite) existing text, instead of shoving it to the right. See Minor Modes.

Only graphic characters can be inserted by typing the associated key; other keys act as editing commands and do not insert themselves. For instance, <DEL> runs the command delete-backward-char by default (some modes bind it to a different command); it does not insert a literal ‘ DEL ’ character ( ASCII character code 127).

To insert a non-graphic character, or a character that your keyboard does not support, first quote it by typing C-q ( quoted-insert ). There are two ways to use C-q :

C-q followed by any non-graphic character (even C-g ) inserts that character. For instance, C-q <DEL> inserts a literal ‘ DEL ’ character.

followed by any non-graphic character (even ) inserts that character. For instance, inserts a literal ‘ ’ character. C-q followed by a sequence of octal digits inserts the character with the specified octal character code. You can use any number of octal digits; any non-digit terminates the sequence. If the terminating character is <RET>, that <RET> serves only to terminate the sequence. Any other non-digit terminates the sequence and then acts as normal input—thus, C-q 1 0 1 B inserts ‘ AB ’. The use of octal sequences is disabled in ordinary non-binary Overwrite mode, to give you a convenient way to insert a digit instead of overwriting with it.

To use decimal or hexadecimal instead of octal, set the variable read-quoted-char-radix to 10 or 16. If the radix is 16, the letters a to f serve as part of a character code, just like digits. Case is ignored.

A few common Unicode characters can be inserted via a command starting with C-x 8 . For example, C-x 8 [ inserts ‘ which is Unicode code-point U+2018 left single quotation mark, sometimes called a left single “curved quote” or “curly quote”. Similarly, C-x 8 ] , C-x 8 { and C-x 8 } insert the curved quotes ’ , “ and ” , respectively. Also, a working Alt key acts like C-x 8 ; e.g., A-[ acts like C-x 8 [ and inserts ‘ . To see which characters have C-x 8 shorthands, type C-x 8 C-h .

Alternatively, you can use the command C-x 8 <RET> ( insert-char ). This prompts for the Unicode name or code-point of a character, using the minibuffer. If you enter a name, the command provides completion (see Completion). If you enter a code-point, it should be as a hexadecimal number (the convention for Unicode), or a number with a specified radix, e.g., #o23072 (octal); See Integer Basics. The command then inserts the corresponding character into the buffer.

For example, the following all insert the same character:

C-x 8 <RET> left single quotation mark <RET> C-x 8 <RET> left sin <TAB> <RET> C-x 8 <RET> 2018 <RET> C-x 8 [ A-[ (if the Alt key works) ` (in Electric Quote mode)

A numeric argument to C-q or C-x 8 ... specifies how many copies of the character to insert (see Arguments).

In addition, in some contexts, if you type a quotation using grave accent and apostrophe `like this' , it is converted to a form ‘like this’ using single quotation marks, even without C-x 8 commands. Similarly, typing a quotation ``like this'' using double grave accent and apostrophe converts it to a form “like this” using double quotation marks. See Quotation Marks.

7.2 Changing the Location of Point

To do more than insert characters, you have to know how to move point (see Point). The keyboard commands C-f , C-b , C-n , and C-p move point to the right, left, down, and up, respectively. You can also move point using the arrow keys present on most keyboards: <RIGHT>, <LEFT>, <DOWN>, and <UP>; however, many Emacs users find that it is slower to use the arrow keys than the control keys, because you need to move your hand to the area of the keyboard where those keys are located.

You can also click the left mouse button to move point to the position clicked. Emacs also provides a variety of additional keyboard commands that move point in more sophisticated ways.

C-f Move forward one character ( forward-char ).

<RIGHT> This command ( right-char ) behaves like C-f , except when point is in a right-to-left paragraph (see Bidirectional Editing).

C-b Move backward one character ( backward-char ).

<LEFT> This command ( left-char ) behaves like C-b , except if the current paragraph is right-to-left (see Bidirectional Editing).

C-n <DOWN> Move down one screen line ( next-line ). This command attempts to keep the horizontal position unchanged, so if you start in the middle of one line, you move to the middle of the next.

C-p <UP> Move up one screen line ( previous-line ). This command preserves position within the line, like C-n .

C-a <Home> Move to the beginning of the line ( move-beginning-of-line ).

C-e <End> Move to the end of the line ( move-end-of-line ).

M-f Move forward one word ( forward-word ). See Words.

C-<RIGHT> M-<RIGHT> This command ( right-word ) behaves like M-f , except it moves backward by one word if the current paragraph is right-to-left. See Bidirectional Editing.

M-b Move backward one word ( backward-word ). See Words.

C-<LEFT> M-<LEFT> This command ( left-word ) behaves like M-b , except it moves forward by one word if the current paragraph is right-to-left. See Bidirectional Editing.

M-r Without moving the text on the screen, reposition point on the left margin of the center-most text line of the window; on subsequent consecutive invocations, move point to the left margin of the top-most line, the bottom-most line, and so forth, in cyclic order ( move-to-window-line-top-bottom ). A numeric argument says which screen line to place point on, counting downward from the top of the window (zero means the top line). A negative argument counts lines up from the bottom (−1 means the bottom line). See Arguments, for more information on numeric arguments.

M-< Move to the top of the buffer ( beginning-of-buffer ). With numeric argument n , move to n /10 of the way from the top. On graphical displays, C-<HOME> does the same.

M-> Move to the end of the buffer ( end-of-buffer ). On graphical displays, C-<END> does the same.

C-v <PageDown> <next> Scroll the display one screen forward, and move point onscreen if necessary ( scroll-up-command ). See Scrolling.

M-v <PageUp> <prior> Scroll one screen backward, and move point onscreen if necessary ( scroll-down-command ). See Scrolling.

M-g c Read a number n and move point to buffer position n . Position 1 is the beginning of the buffer.

M-g M-g M-g g Read a number n and move point to the beginning of line number n ( goto-line ). Line 1 is the beginning of the buffer. If point is on or just after a number in the buffer, that is the default for n . Just type <RET> in the minibuffer to use it. You can also specify n by giving M-g M-g a numeric prefix argument. See Select Buffer, for the behavior of M-g M-g when you give it a plain prefix argument.

M-g <TAB> Read a number n and move to column n in the current line. Column 0 is the leftmost column. If called with a prefix argument, move to the column number specified by the argument's numeric value.

C-x C-n Use the current column of point as the semipermanent goal column for C-n and C-p ( set-goal-column ) in the current buffer. When a semipermanent goal column is in effect, those commands always try to move to this column, or as close as possible to it, after moving vertically. The goal column remains in effect until canceled.

C-u C-x C-n Cancel the goal column. Henceforth, C-n and C-p try to preserve the horizontal position, as usual.

When a line of text in the buffer is longer than the width of the window, Emacs usually displays it on two or more screen lines . For convenience, C-n and C-p move point by screen lines, as do the equivalent keys <down> and <up> . You can force these commands to move according to logical lines (i.e., according to the text lines in the buffer) by setting the variable line-move-visual to nil ; if a logical line occupies multiple screen lines, the cursor then skips over the additional screen lines. For details, see Continuation Lines. See Variables, for how to set variables such as line-move-visual .

Unlike C-n and C-p , most of the Emacs commands that work on lines work on logical lines. For instance, C-a ( move-beginning-of-line ) and C-e ( move-end-of-line ) respectively move to the beginning and end of the logical line. Whenever we encounter commands that work on screen lines, such as C-n and C-p , we will point these out.

When line-move-visual is nil , you can also set the variable track-eol to a non- nil value. Then C-n and C-p , when starting at the end of the logical line, move to the end of the next logical line. Normally, track-eol is nil .

C-n normally stops at the end of the buffer when you use it on the last line in the buffer. However, if you set the variable next-line-add-newlines to a non- nil value, C-n on the last line of a buffer creates an additional line at the end and moves down into it.

7.3 Erasing Text

<DEL> <BACKSPACE> Delete the character before point, or the region if it is active ( delete-backward-char ).

<Delete> Delete the character after point, or the region if it is active ( delete-forward-char ).

C-d Delete the character after point ( delete-char ).

C-k Kill to the end of the line ( kill-line ).

M-d Kill forward to the end of the next word ( kill-word ).

M-<DEL> M-<BACKSPACE> Kill back to the beginning of the previous word ( backward-kill-word ).

The <DEL> ( delete-backward-char ) command removes the character before point, moving the cursor and the characters after it backwards. If point was at the beginning of a line, this deletes the preceding newline, joining this line to the previous one.

If, however, the region is active, <DEL> instead deletes the text in the region. See Mark, for a description of the region.

On most keyboards, <DEL> is labeled <BACKSPACE>, but we refer to it as <DEL> in this manual. (Do not confuse <DEL> with the <Delete> key; we will discuss <Delete> momentarily.) On some text terminals, Emacs may not recognize the <DEL> key properly. See DEL Does Not Delete, if you encounter this problem.

The <Delete> ( delete-forward-char ) command deletes in the opposite direction: it deletes the character after point, i.e., the character under the cursor. If point was at the end of a line, this joins the following line onto this one. Like <DEL> , it deletes the text in the region if the region is active (see Mark).

C-d ( delete-char ) deletes the character after point, similar to <Delete>, but regardless of whether the region is active.

See Deletion, for more detailed information about the above deletion commands.

C-k ( kill-line ) erases (kills) a line at a time. If you type C-k at the beginning or middle of a line, it kills all the text up to the end of the line. If you type C-k at the end of a line, it joins that line with the following line.

See Killing, for more information about C-k and related commands.

7.4 Undoing Changes

C-/ C-x u C-_ Undo one entry of the undo records—usually, one command worth ( undo ). (The first key might be unavailable on text-mode displays.)

Emacs records a list of changes made in the buffer text, so you can undo recent changes. This is done using the undo command, which is bound to C-/ (as well as C-x u and C-_ ). Normally, this command undoes the last change, moving point back to where it was before the change. The undo command applies only to changes in the buffer; you can't use it to undo cursor motion.

Although each editing command usually makes a separate entry in the undo records, very simple commands may be grouped together. Sometimes, an entry may cover just part of a complex command.

If you repeat C-/ (or its aliases), each repetition undoes another, earlier change, back to the limit of the undo information available. If all recorded changes have already been undone, the undo command displays an error message and does nothing.

To learn more about the undo command, see Undo.

7.5 Files

Text that you insert in an Emacs buffer lasts only as long as the Emacs session. To keep any text permanently, you must put it in a file .

Suppose there is a file named test.emacs in your home directory. To begin editing this file in Emacs, type

C-x C-f test.emacs <RET>

Here the file name is given as an argument to the command C-x C-f ( find-file ). That command uses the minibuffer to read the argument, and you type <RET> to terminate the argument (see Minibuffer).

Emacs obeys this command by visiting the file: it creates a buffer, copies the contents of the file into the buffer, and then displays the buffer for editing. If you alter the text, you can save the new text in the file by typing C-x C-s ( save-buffer ). This copies the altered buffer contents back into the file test.emacs , making them permanent. Until you save, the changed text exists only inside Emacs, and the file test.emacs is unaltered.

To create a file, just visit it with C-x C-f as if it already existed. This creates an empty buffer, in which you can insert the text you want to put in the file. Emacs actually creates the file the first time you save this buffer with C-x C-s .

To learn more about using files in Emacs, see Files.

7.6 Help

If you forget what a key does, you can find out by typing C-h k ( describe-key ), followed by the key of interest; for example, C-h k C-n tells you what C-n does.

The prefix key C-h stands for “help”. The key <F1> serves as an alias for C-h . Apart from C-h k , there are many other help commands providing different kinds of help.

See Help, for details.

7.7 Blank Lines

Here are special commands and techniques for inserting and deleting blank lines.

C-o Insert a blank line after the cursor ( open-line ).

C-x C-o Delete all but one of many consecutive blank lines ( delete-blank-lines ).

We have seen how <RET> ( newline ) starts a new line of text. However, it may be easier to see what you are doing if you first make a blank line and then insert the desired text into it. This is easy to do using the key C-o ( open-line ), which inserts a newline after point but leaves point in front of the newline. After C-o , type the text for the new line.

You can make several blank lines by typing C-o several times, or by giving it a numeric argument specifying how many blank lines to make. See Arguments, for how. If you have a fill prefix, the C-o command inserts the fill prefix on the new line, if typed at the beginning of a line. See Fill Prefix.

The easy way to get rid of extra blank lines is with the command C-x C-o ( delete-blank-lines ). If point lies within a run of several blank lines, C-x C-o deletes all but one of them. If point is on a single blank line, C-x C-o deletes it. If point is on a nonblank line, C-x C-o deletes all following blank lines, if any exists.

7.8 Continuation Lines

Sometimes, a line of text in the buffer—a logical line —is too long to fit in the window, and Emacs displays it as two or more screen lines . This is called line wrapping or continuation , and the long logical line is called a continued line . On a graphical display, Emacs indicates line wrapping with small bent arrows in the left and right window fringes. On a text terminal, Emacs indicates line wrapping by displaying a ‘ \ ’ character at the right margin.

Most commands that act on lines act on logical lines, not screen lines. For instance, C-k kills a logical line. As described earlier, C-n ( next-line ) and C-p ( previous-line ) are special exceptions: they move point down and up, respectively, by one screen line (see Moving Point).

Emacs can optionally truncate long logical lines instead of continuing them. This means that every logical line occupies a single screen line; if it is longer than the width of the window, the rest of the line is not displayed. On a graphical display, a truncated line is indicated by a small straight arrow in the right fringe; on a text terminal, it is indicated by a ‘ $ ’ character in the right margin. See Line Truncation.

By default, continued lines are wrapped at the right window edge. Since the wrapping may occur in the middle of a word, continued lines can be difficult to read. The usual solution is to break your lines before they get too long, by inserting newlines. If you prefer, you can make Emacs insert a newline automatically when a line gets too long, by using Auto Fill mode. See Filling.

Sometimes, you may need to edit files containing many long logical lines, and it may not be practical to break them all up by adding newlines. In that case, you can use Visual Line mode, which enables word wrapping : instead of wrapping long lines exactly at the right window edge, Emacs wraps them at the word boundaries (i.e., space or tab characters) nearest to the right window edge. Visual Line mode also redefines editing commands such as C-a , C-n , and C-k to operate on screen lines rather than logical lines. See Visual Line Mode.

7.9 Cursor Position Information

Here are commands to get information about the size and position of parts of the buffer, and to count words and lines.

M-x what-line Display the line number of point.

M-x line-number-mode M-x column-number-mode Toggle automatic display of the current line number or column number. See Optional Mode Line. If you want to have a line number displayed before each line, see Display Custom.

M-= Display the number of lines, words, and characters that are present in the region ( count-words-region ). See Mark, for information about the region.

M-x count-words Display the number of lines, words, and characters that are present in the buffer. If the region is active (see Mark), display the numbers for the region instead.

C-x = Display the character code of character after point, character position of point, and column of point ( what-cursor-position ).

M-x hl-line-mode Enable or disable highlighting of the current line. See Cursor Display.

M-x size-indication-mode Toggle automatic display of the size of the buffer. See Optional Mode Line.

M-x what-line displays the current line number in the echo area. This command is usually redundant because the current line number is shown in the mode line (see Mode Line). However, if you narrow the buffer, the mode line shows the line number relative to the accessible portion (see Narrowing). By contrast, what-line displays both the line number relative to the narrowed region and the line number relative to the whole buffer.

M-= ( count-words-region ) displays a message reporting the number of lines, words, and characters in the region (see Mark, for an explanation of the region). With a prefix argument, C-u M-= , the command displays a count for the entire buffer.

The command M-x count-words does the same job, but with a different calling convention. It displays a count for the region if the region is active, and for the buffer otherwise.

The command C-x = ( what-cursor-position ) shows information about the current cursor position and the buffer contents at that position. It displays a line in the echo area that looks like this:

Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53

After ‘ Char: ’, this shows the character in the buffer at point. The text inside the parenthesis shows the corresponding decimal, octal and hex character codes; for more information about how C-x = displays character information, see International Chars. After ‘ point= ’ is the position of point as a character count (the first character in the buffer is position 1, the second character is position 2, and so on). The number after that is the total number of characters in the buffer, and the number in parenthesis expresses the position as a percentage of the total. After ‘ column= ’ is the horizontal position of point, in columns counting from the left edge of the window.

If the buffer has been narrowed, making some of the text at the beginning and the end temporarily inaccessible, C-x = displays additional text describing the currently accessible range. For example, it might display this:

Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0

where the two extra numbers give the smallest and largest character position that point is allowed to assume. The characters between those two positions are the accessible ones. See Narrowing.

Related, but different feature is display-line-numbers-mode (see Display Custom).

7.10 Numeric Arguments

In the terminology of mathematics and computing, argument means “data provided to a function or operation”. You can give any Emacs command a numeric argument (also called a prefix argument ). Some commands interpret the argument as a repetition count. For example, giving C-f an argument of ten causes it to move point forward by ten characters instead of one. With these commands, no argument is equivalent to an argument of one, and negative arguments cause them to move or act in the opposite direction.

The easiest way to specify a numeric argument is to type a digit and/or a minus sign while holding down the <Meta> key. For example,

M-5 C-n

moves down five lines. The keys M-1 , M-2 , and so on, as well as M-- , are bound to commands ( digit-argument and negative-argument ) that set up an argument for the next command. M-- without digits normally means −1.

If you enter more than one digit, you need not hold down the <Meta> key for the second and subsequent digits. Thus, to move down fifty lines, type

M-5 0 C-n

Note that this does not insert five copies of ‘ 0 ’ and move down one line, as you might expect—the ‘ 0 ’ is treated as part of the prefix argument.

(What if you do want to insert five copies of ‘ 0 ’? Type M-5 C-u 0 . Here, C-u terminates the prefix argument, so that the next keystroke begins the command that you want to execute. Note that this meaning of C-u applies only to this case. For the usual role of C-u , see below.)

Instead of typing M-1 , M-2 , and so on, another way to specify a numeric argument is to type C-u ( universal-argument ) followed by some digits, or (for a negative argument) a minus sign followed by digits. A minus sign without digits normally means −1.

C-u alone has the special meaning of “four times”: it multiplies the argument for the next command by four. C-u C-u multiplies it by sixteen. Thus, C-u C-u C-f moves forward sixteen characters. Other useful combinations are C-u C-n , C-u C-u C-n (move down a good fraction of a screen), C-u C-u C-o (make sixteen blank lines), and C-u C-k (kill four lines).

You can use a numeric argument before a self-inserting character to insert multiple copies of it. This is straightforward when the character is not a digit; for example, C-u 6 4 a inserts 64 copies of the character ‘ a ’. But this does not work for inserting digits; C-u 6 4 1 specifies an argument of 641. You can separate the argument from the digit to insert with another C-u ; for example, C-u 6 4 C-u 1 does insert 64 copies of the character ‘ 1 ’.

Some commands care whether there is an argument, but ignore its value. For example, the command M-q ( fill-paragraph ) fills text; with an argument, it justifies the text as well. (See Filling, for more information on M-q .) For these commands, it is enough to specify the argument with a single C-u .

Some commands use the value of the argument as a repeat count but do something special when there is no argument. For example, the command C-k ( kill-line ) with argument n kills n lines, including their terminating newlines. But C-k with no argument is special: it kills the text up to the next newline, or, if point is right at the end of the line, it kills the newline itself. Thus, two C-k commands with no arguments can kill a nonblank line, just like C-k with an argument of one. (See Killing, for more information on C-k .)

A few commands treat a plain C-u differently from an ordinary argument. A few others may treat an argument of just a minus sign differently from an argument of −1. These unusual cases are described when they come up; they exist to make an individual command more convenient, and they are documented in that command's documentation string.

We use the term prefix argument to emphasize that you type such arguments before the command, and to distinguish them from minibuffer arguments (see Minibuffer), which are entered after invoking the command.

On graphical displays, C-0 , C-1 , etc. act the same as M-0 , M-1 , etc.

7.11 Repeating a Command

Many simple commands, such as those invoked with a single key or with M-x command-name <RET> , can be repeated by invoking them with a numeric argument that serves as a repeat count (see Arguments). However, if the command you want to repeat prompts for input, or uses a numeric argument in another way, that method won't work.

The command C-x z ( repeat ) provides another way to repeat an Emacs command many times. This command repeats the previous Emacs command, whatever that was. Repeating a command uses the same arguments that were used before; it does not read new arguments each time.

To repeat the command more than once, type additional z 's: each z repeats the command one more time. Repetition ends when you type a character other than z or press a mouse button.

For example, suppose you type C-u 2 0 C-d to delete 20 characters. You can repeat that command (including its argument) three additional times, to delete a total of 80 characters, by typing C-x z z z . The first C-x z repeats the command once, and each subsequent z repeats it once again.

8 The Minibuffer

The minibuffer is where Emacs commands read complicated arguments, such as file names, buffer names, Emacs command names, or Lisp expressions. We call it the “minibuffer” because it's a special-purpose buffer with a small amount of screen space. You can use the usual Emacs editing commands in the minibuffer to edit the argument text.

8.1 Using the Minibuffer

When the minibuffer is in use, it appears in the echo area, with a cursor. The minibuffer starts with a prompt , usually ending with a colon. The prompt states what kind of input is expected, and how it will be used. The prompt is highlighted using the minibuffer-prompt face (see Faces).

The simplest way to enter a minibuffer argument is to type the text, then <RET> to submit the argument and exit the minibuffer. Alternatively, you can type C-g to exit the minibuffer by canceling the command asking for the argument (see Quitting).

Sometimes, the prompt shows a default argument , inside parentheses before the colon. This default will be used as the argument if you just type <RET>. For example, commands that read buffer names usually show a buffer name as the default; you can type <RET> to operate on that default buffer.

If you enable Minibuffer Electric Default mode, a global minor mode, Emacs hides the default argument as soon as you modify the contents of the minibuffer (since typing <RET> would no longer submit that default). If you ever bring back the original minibuffer text, the prompt again shows the default. Furthermore, if you change the variable minibuffer-eldef-shorten-default to a non- nil value, the default argument is displayed as ‘ [ default-arg ] ’ instead of ‘ (default default-arg ) ’, saving some screen space. To enable this minor mode, type M-x minibuffer-electric-default-mode .

Since the minibuffer appears in the echo area, it can conflict with other uses of the echo area. If an error message or an informative message is emitted while the minibuffer is active, the message hides the minibuffer for a few seconds, or until you type something; then the minibuffer comes back. While the minibuffer is in use, Emacs does not echo keystrokes.

8.2 Minibuffers for File Names

Commands such as C-x C-f ( find-file ) use the minibuffer to read a file name argument (see Basic Files). When the minibuffer is used to read a file name, it typically starts out with some initial text ending in a slash. This is the default directory . For example, it may start out like this:

Find file: /u2/emacs/src/

Here, ‘ Find file: ’ is the prompt and ‘ /u2/emacs/src/ ’ is the default directory. If you now type buffer.c as input, that specifies the file /u2/emacs/src/buffer.c . See File Names, for information about the default directory.

Alternative defaults for the file name you may want are available by typing M-n , see Minibuffer History.

You can specify a file in the parent directory with .. : /a/b/../foo.el is equivalent to /a/foo.el . Alternatively, you can use M-<DEL> to kill directory names backwards (see Words).

To specify a file in a completely different directory, you can kill the entire default with C-a C-k (see Minibuffer Edit). Alternatively, you can ignore the default, and enter an absolute file name starting with a slash or a tilde after the default directory. For example, you can specify /etc/termcap as follows:

Find file: /u2/emacs/src//etc/termcap

A double slash causes Emacs to ignore everything before the second slash in the pair. In the example above, /u2/emacs/src/ is ignored, so the argument you supplied is /etc/termcap . The ignored part of the file name is dimmed if the terminal allows it. (To disable this dimming, turn off File Name Shadow mode with the command M-x file-name-shadow-mode .)

When completing remote file names (see Remote Files), a double slash behaves slightly differently: it causes Emacs to ignore only the file-name part, leaving the rest (method, host and username, etc.) intact. Typing three slashes in a row ignores everything in remote file names. See File name completion.

Emacs interprets ~/ as your home directory. Thus, ~/foo/bar.txt specifies a file named bar.txt , inside a directory named foo , which is in turn located in your home directory. In addition, ~ user-id / means the home directory of a user whose login name is user-id . Any leading directory name in front of the ~ is ignored: thus, /u2/emacs/~/foo/bar.txt is equivalent to ~/foo/bar.txt .

On MS-Windows and MS-DOS systems, where a user doesn't always have a home directory, Emacs uses several alternatives. For MS-Windows, see Windows HOME; for MS-DOS, see MS-DOS File Names. On these systems, the ~ user-id / construct is supported only for the current user, i.e., only if user-id is the current user's login name.

To prevent Emacs from inserting the default directory when reading file names, change the variable insert-default-directory to nil . In that case, the minibuffer starts out empty. Nonetheless, relative file name arguments are still interpreted based on the same default directory.

You can also enter remote file names in the minibuffer. See Remote Files.

8.3 Editing in the Minibuffer

The minibuffer is an Emacs buffer, albeit a peculiar one, and the usual Emacs commands are available for editing the argument text. (The prompt, however, is read-only , and cannot be changed.)

Since <RET> in the minibuffer submits the argument, you can't use it to insert a newline. You can do that with C-q C-j , which inserts a C-j control character, which is formally equivalent to a newline character (see Inserting Text). Alternatively, you can use the C-o ( open-line ) command (see Blank Lines).

Inside a minibuffer, the keys <TAB>, <SPC>, and ? are often bound to completion commands , which allow you to easily fill in the desired text without typing all of it. See Completion. As with <RET>, you can use C-q to insert a <TAB>, <SPC>, or ‘ ? ’ character.

For convenience, C-a ( move-beginning-of-line ) in a minibuffer moves point to the beginning of the argument text, not the beginning of the prompt. For example, this allows you to erase the entire argument with C-a C-k .

When the minibuffer is active, the echo area is treated much like an ordinary Emacs window. For instance, you can switch to another window (with C-x o ), edit text there, then return to the minibuffer window to finish the argument. You can even kill text in another window, return to the minibuffer window, and yank the text into the argument. There are some restrictions on the minibuffer window, however: for instance, you cannot split it. See Windows.

Normally, the minibuffer window occupies a single screen line. However, if you add two or more lines' worth of text into the minibuffer, it expands automatically to accommodate the text. The variable resize-mini-windows controls the resizing of the minibuffer. The default value is grow-only , which means the behavior we have just described. If the value is t , the minibuffer window will also shrink automatically if you remove some lines of text from the minibuffer, down to a minimum of one screen line. If the value is nil , the minibuffer window never changes size automatically, but you can use the usual window-resizing commands on it (see Windows).

The variable max-mini-window-height controls the maximum height for resizing the minibuffer window. A floating-point number specifies a fraction of the frame's height; an integer specifies the maximum number of lines; nil means do not resize the minibuffer window automatically. The default value is 0.25.

The C-M-v command in the minibuffer scrolls the help text from commands that display help text of any sort in another window. You can also scroll the help text with M-<PageUp> and M-<PageDown> (or, equivalently, M-<prior> and M-<next> ). This is especially useful with long lists of possible completions. See Other Window.

Emacs normally disallows most commands that use the minibuffer while the minibuffer is active. To allow such commands in the minibuffer, set the variable enable-recursive-minibuffers to t .

When not active, the minibuffer is in minibuffer-inactive-mode , and clicking mouse-1 there shows the *Messages* buffer. If you use a dedicated frame for minibuffers, Emacs also recognizes certain keys there, for example, n to make a new frame.

8.4 Completion

You can often use a feature called completion to help enter arguments. This means that after you type part of the argument, Emacs can fill in the rest, or some of it, based on what was typed so far.

When completion is available, certain keys (usually <TAB>, <RET>, and <SPC>) are rebound in the minibuffer to special completion commands (see Completion Commands). These commands attempt to complete the text in the minibuffer, based on a set of completion alternatives provided by the command that requested the argument. You can usually type ? to see a list of completion alternatives.

Although completion is usually done in the minibuffer, the feature is sometimes available in ordinary buffers too. See Symbol Completion.

8.4.1 Completion Example

A simple example may help here. M-x uses the minibuffer to read the name of a command, so completion works by matching the minibuffer text against the names of existing Emacs commands. Suppose you wish to run the command auto-fill-mode . You can do that by typing M-x auto-fill-mode <RET> , but it is easier to use completion.

If you type M-x a u <TAB> , the <TAB> looks for completion alternatives (in this case, command names) that start with ‘ au ’. There are several, including auto-fill-mode and autoconf-mode , but they all begin with auto , so the ‘ au ’ in the minibuffer completes to ‘ auto ’. (More commands may be defined in your Emacs session. For example, if a command called authorize-me was defined, Emacs could only complete as far as ‘ aut ’.)

If you type <TAB> again immediately, it cannot determine the next character; it could be ‘ - ’, ‘ a ’, or ‘ c ’. So it does not add any characters; instead, <TAB> displays a list of all possible completions in another window.

Next, type -f . The minibuffer now contains ‘ auto-f ’, and the only command name that starts with this is auto-fill-mode . If you now type <TAB>, completion fills in the rest of the argument ‘ auto-fill-mode ’ into the minibuffer.

Hence, typing just a u <TAB> - f <TAB> allows you to enter ‘ auto-fill-mode ’.

8.4.2 Completion Commands

Here is a list of the completion commands defined in the minibuffer when completion is allowed.

<TAB> Complete the text in the minibuffer as much as possible; if unable to complete, display a list of possible completions ( minibuffer-complete ).

<SPC> Complete up to one word from the minibuffer text before point ( minibuffer-complete-word ). This command is not available for arguments that often include spaces, such as file names.

<RET> Submit the text in the minibuffer as the argument, possibly completing first ( minibuffer-complete-and-exit ). See Completion Exit.

? Display a list of completions ( minibuffer-completion-help ).

<TAB> ( minibuffer-complete ) is the most fundamental completion command. It searches for all possible completions that match the existing minibuffer text, and attempts to complete as much as it can. See Completion Styles, for how completion alternatives are chosen.

<SPC> ( minibuffer-complete-word ) completes like <TAB>, but only up to the next hyphen or space. If you have ‘ auto-f ’ in the minibuffer and type <SPC>, it finds that the completion is ‘ auto-fill-mode ’, but it only inserts ‘ ill- ’, giving ‘ auto-fill- ’. Another <SPC> at this point completes all the way to ‘ auto-fill-mode ’.

If <TAB> or <SPC> is unable to complete, it displays a list of matching completion alternatives (if there are any) in another window. You can display the same list with ? ( minibuffer-completion-help ). The following commands can be used with the completion list:

M-v <PageUp> <prior> Typing M-v , while in the minibuffer, selects the window showing the completion list ( switch-to-completions ). This paves the way for using the commands below. <PageUp> or <prior> does the same. You can also select the window in other ways (see Windows).

<RET> mouse-1 mouse-2 While in the completion list buffer, this chooses the completion at point ( choose-completion ).

<RIGHT> While in the completion list buffer, this moves point to the following completion alternative ( next-completion ).

<LEFT> While in the completion list buffer, this moves point to the previous completion alternative ( previous-completion ).

8.4.3 Completion Exit

When a command reads an argument using the minibuffer with completion, it also controls what happens when you type <RET> ( minibuffer-complete-and-exit ) to submit the argument. There are four types of behavior:

Strict completion accepts only exact completion matches. Typing <RET> exits the minibuffer only if the minibuffer text is an exact match, or completes to one. Otherwise, Emacs refuses to exit the minibuffer; instead it tries to complete, and if no completion can be done it momentarily displays ‘ [No match] ’ after the minibuffer text. (You can still leave the minibuffer by typing C-g to cancel the command.) An example of a command that uses this behavior is M-x , since it is meaningless for it to accept a non-existent command name.

accepts only exact completion matches. Typing <RET> exits the minibuffer only if the minibuffer text is an exact match, or completes to one. Otherwise, Emacs refuses to exit the minibuffer; instead it tries to complete, and if no completion can be done it momentarily displays ‘ ’ after the minibuffer text. (You can still leave the minibuffer by typing to cancel the command.) Cautious completion is like strict completion, except <RET> exits only if the text is already an exact match. If the text completes to an exact match, <RET> performs that completion but does not exit yet; you must type a second <RET> to exit. Cautious completion is used for reading file names for files that must already exist, for example.

is like strict completion, except <RET> exits only if the text is already an exact match. If the text completes to an exact match, <RET> performs that completion but does not exit yet; you must type a second <RET> to exit. Permissive completion allows any input; the completion candidates are just suggestions. Typing <RET> does not complete, it just submits the argument as you have entered it.

allows any input; the completion candidates are just suggestions. Typing <RET> does not complete, it just submits the argument as you have entered it. Permissive completion with confirmation is like permissive completion, with an exception: if you typed <TAB> and this completed the text up to some intermediate state (i.e., one that is not yet an exact completion match), typing <RET> right afterward does not submit the argument. Instead, Emacs asks for confirmation by momentarily displaying ‘ [Confirm] ’ after the text; type <RET> again to confirm and submit the text. This catches a common mistake, in which one types <RET> before realizing that <TAB> did not complete as far as desired. You can tweak the confirmation behavior by customizing the variable confirm-nonexistent-file-or-buffer . The default value, after-completion , gives the behavior we have just described. If you change it to nil , Emacs does not ask for confirmation, falling back on permissive completion. If you change it to any other non- nil value, Emacs asks for confirmation whether or not the preceding command was <TAB>. This behavior is used by most commands that read file names, like C-x C-f , and commands that read buffer names, like C-x b .

8.4.4 How Completion Alternatives Are Chosen

Completion commands work by narrowing a large list of possible completion alternatives to a smaller subset that matches what you have typed in the minibuffer. In Completion Example, we gave a simple example of such matching. The procedure of determining what constitutes a match is quite intricate. Emacs attempts to offer plausible completions under most circumstances.

Emacs performs completion using one or more completion styles —sets of criteria for matching minibuffer text to completion alternatives. During completion, Emacs tries each completion style in turn. If a style yields one or more matches, that is used as the list of completion alternatives. If a style produces no matches, Emacs falls back on the next style.

The list variable completion-styles specifies the completion styles to use. Each list element is the name of a completion style (a Lisp symbol). The default completion styles are (in order):

basic A matching completion alternative must have the same beginning as the text in the minibuffer before point. Furthermore, if there is any text in the minibuffer after point, the rest of the completion alternative must contain that text as a substring.

partial-completion This aggressive completion style divides the minibuffer text into words separated by hyphens or spaces, and completes each word separately. (For example, when completing command names, ‘ em-l-m ’ completes to ‘ emacs-lisp-mode ’.) Furthermore, a ‘ * ’ in the minibuffer text is treated as a wildcard —it matches any string of characters at the corresponding position in the completion alternative.

emacs22 This completion style is similar to basic , except that it ignores the text in the minibuffer after point. It is so-named because it corresponds to the completion behavior in Emacs 22.

The following additional completion styles are also defined, and you can add them to completion-styles if you wish (see Customization):

substring A matching completion alternative must contain the text in the minibuffer before point, and the text in the minibuffer after point, as substrings (in that same order). Thus, if the text in the minibuffer is ‘ foobar ’, with point between ‘ foo ’ and ‘ bar ’, that matches ‘ a foo b bar c ’, where a , b , and c can be any string including the empty string.

initials This very aggressive completion style attempts to complete acronyms and initialisms. For example, when completing command names, it matches ‘ lch ’ to ‘ list-command-history ’.

There is also a very simple completion style called emacs21 . In this style, if the text in the minibuffer is ‘ foobar ’, only matches starting with ‘ foobar ’ are considered.

You can use different completion styles in different situations, by setting the variable completion-category-overrides . For example, the default setting says to use only basic and substring completion for buffer names.

8.4.5 Completion Options

Case is significant when completing case-sensitive arguments, such as command names. For example, when completing command names, ‘ AU ’ does not complete to ‘ auto-fill-mode ’. Case differences are ignored when completing arguments in which case does not matter.

When completing file names, case differences are ignored if the variable read-file-name-completion-ignore-case is non- nil . The default value is nil on systems that have case-sensitive file-names, such as GNU/Linux; it is non- nil on systems that have case-insensitive file-names, such as Microsoft Windows. When completing buffer names, case differences are ignored if the variable read-buffer-completion-ignore-case is non- nil ; the default is nil .

When completing file names, Emacs usually omits certain alternatives that are considered unlikely to be chosen, as determined by the list variable completion-ignored-extensions . Each element in the list should be a string; any file name ending in such a string is ignored as a completion alternative. Any element ending in a slash ( / ) represents a subdirectory name. The standard value of completion-ignored-extensions has several elements including ".o" , ".elc" , and "~" . For example, if a directory contains ‘ foo.c ’ and ‘ foo.elc ’, ‘ foo ’ completes to ‘ foo.c ’. However, if all possible completions end in otherwise-ignored strings, they are not ignored: in the previous example, ‘ foo.e ’ completes to ‘ foo.elc ’. Emacs disregards completion-ignored-extensions when showing completion alternatives in the completion list.

Shell completion is an extended version of filename completion, see Shell Options.

If completion-auto-help is set to nil , the completion commands never display the completion list buffer; you must type ? to display the list. If the value is lazy , Emacs only shows the completion list buffer on the second attempt to complete. In other words, if there is nothing to complete, the first <TAB> echoes ‘ Next char not unique ’; the second <TAB> shows the completion list buffer.

If completion-cycle-threshold is non- nil , completion commands can cycle through completion alternatives. Normally, if there is more than one completion alternative for the text in the minibuffer, a completion command completes up to the longest common substring. If you change completion-cycle-threshold to t , the completion command instead completes to the first of those completion alternatives; each subsequent invocation of the completion command replaces that with the next completion alternative, in a cyclic manner. If you give completion-cycle-threshold a numeric value n , completion commands switch to this cycling behavior only when there are n or fewer alternatives.

8.5 Minibuffer History

Every argument that you enter with the minibuffer is saved in a minibuffer history list so you can easily use it again later. You can use the following arguments to quickly fetch an earlier argument into the minibuffer:

M-p Move to the previous item in the minibuffer history, an earlier argument ( previous-history-element ).

M-n Move to the next item in the minibuffer history ( next-history-element ).

<UP> <DOWN> Like M-p and M-n , but move to the previous or next line of a multi-line item before going to the previous history item ( previous-line-or-history-element and next-line-or-history-element ) .

M-r regexp <RET> Move to an earlier item in the minibuffer history that matches regexp ( previous-matching-history-element ).

M-s regexp <RET> Move to a later item in the minibuffer history that matches regexp ( next-matching-history-element ).

While in the minibuffer, M-p ( previous-history-element ) moves through the minibuffer history list, one item at a time. Each M-p fetches an earlier item from the history list into the minibuffer, replacing its existing contents. Typing M-n ( next-history-element ) moves through the minibuffer history list in the opposite direction, fetching later entries into the minibuffer.

If you type M-n in the minibuffer when there are no later entries in the minibuffer history (e.g., if you haven't previously typed M-p ), Emacs tries fetching from a list of default arguments: values that you are likely to enter. You can think of this as moving through the “future history”.

The “future history” for file names includes several possible alternatives you may find useful, such as the file name or the URL at point in the current buffer. The defaults put into the “future history” in this case are controlled by the functions mentioned in the value of the option file-name-at-point-functions . By default, its value invokes the ffap package (see FFAP), which tries to guess the default file or URL from the text around point. To disable this guessing, customize the option to a nil value, then the “future history” of file names will include only the file, if any, visited by the current buffer, and the default directory.

The arrow keys <UP> and <DOWN> work like M-p and M-n , but if the current history item is longer than a single line, they allow you to move to the previous or next line of the current history item before going to the previous or next history item.

If you edit the text inserted by the M-p or M-n minibuffer history commands, this does not change its entry in the history list. However, the edited argument does go at the end of the history list when you submit it.

You can use M-r ( previous-matching-history-element ) to search through older elements in the history list, and M-s ( next-matching-history-element ) to search through newer entries. Each of these commands asks for a regular expression as an argument, and fetches the first matching entry into the minibuffer. See Regexps, for an explanation of regular expressions. A numeric prefix argument n means to fetch the n th matching entry. These commands are unusual, in that they use the minibuffer to read the regular expression argument, even though they are invoked from the minibuffer. An upper-case letter in the regular expression makes the search case-sensitive (see Lax Search).

You can also search through the history using an incremental search. See Isearch Minibuffer.

Emacs keeps separate history lists for several different kinds of arguments. For example, there is a list for file names, used by all the commands that read file names. Other history lists include buffer names, command names (used by M-x ), and command arguments (used by commands like query-replace ).

The variable history-length specifies the maximum length of a minibuffer history list; adding a new element deletes the oldest element if the list gets too long. If the value is t , there is no maximum length.

The variable history-delete-duplicates specifies whether to delete duplicates in history. If it is non- nil , adding a new element deletes from the list all other elements that are equal to it. The default is nil .

8.6 Repeating Minibuffer Commands

Every command that uses the minibuffer once is recorded on a special history list, the command history , together with the values of its arguments, so that you can repeat the entire command. In particular, every use of M-x is recorded there, since M-x uses the minibuffer to read the command name.

C-x <ESC> <ESC> Re-execute a recent minibuffer command from the command history ( repeat-complex-command ).

M-x list-command-history Display the entire command history, showing all the commands C-x <ESC> <ESC> can repeat, most recent first.

C-x <ESC> <ESC> re-executes a recent command that used the minibuffer. With no argument, it repeats the last such command. A numeric argument specifies which command to repeat; 1 means the last one, 2 the previous, and so on.

C-x <ESC> <ESC> works by turning the previous command into a Lisp expression and then entering a minibuffer initialized with the text for that expression. Even if you don't know Lisp, it will probably be obvious which command is displayed for repetition. If you type just <RET>, that repeats the command unchanged. You can also change the command by editing the Lisp expression before you execute it. The executed command is added to the front of the command history unless it is identical to the most recent item.

Once inside the minibuffer for C-x <ESC> <ESC> , you can use the usual minibuffer history commands (see Minibuffer History) to move through the history list. After finding the desired previous command, you can edit its expression as usual and then execute it by typing <RET>.

Incremental search does not, strictly speaking, use the minibuffer. Therefore, although it behaves like a complex command, it normally does not appear in the history list for C-x <ESC> <ESC> . You can make incremental search commands appear in the history by setting isearch-resume-in-command-history to a non- nil value. See Incremental Search.

The list of previous minibuffer-using commands is stored as a Lisp list in the variable command-history . Each element is a Lisp expression that describes one command and its arguments. Lisp programs can re-execute a command by calling eval with the command-history element.

8.7 Entering passwords

Sometimes, you may need to enter a password into Emacs. For instance, when you tell Emacs to visit a file on another machine via a network protocol such as FTP, you often need to supply a password to gain access to the machine (see Remote Files).

Entering a password is similar to using a minibuffer. Emacs displays a prompt in the echo area (such as ‘ Password: ’); after you type the required password, press <RET> to submit it. To prevent others from seeing your password, every character you type is displayed as a dot (‘ . ’) instead of its usual form.

Most of the features and commands associated with the minibuffer cannot be used when entering a password. There is no history or completion, and you cannot change windows or perform any other action with Emacs until you have submitted the password.

While you are typing the password, you may press <DEL> to delete backwards, removing the last character entered. C-u deletes everything you have typed so far. C-g quits the password prompt (see Quitting). C-y inserts the current kill into the password (see Killing). You may type either <RET> or <ESC> to submit the password. Any other self-inserting character key inserts the associated character into the password, and all other input is ignored.

8.8 Yes or No Prompts

An Emacs command may require you to answer a yes-or-no question during the course of its execution. Such queries come in two main varieties.

For the first type of yes-or-no query, the prompt ends with ‘ (y or n) ’. Such a query does not actually use the minibuffer; the prompt appears in the echo area, and you answer by typing either ‘ y ’ or ‘ n ’, which immediately delivers the response. For example, if you type C-x C-w ( write-file ) to save a buffer, and enter the name of an existing file, Emacs issues a prompt like this:

File ‘foo.el’ exists; overwrite? (y or n)

Because this query does not actually use the minibuffer, the usual minibuffer editing commands cannot be used. However, you can perform some window scrolling operations while the query is active: C-l recenters the selected window; C-v (or <PageDown>, or <next>) scrolls forward; M-v (or <PageUp>, or <prior>) scrolls backward; C-M-v scrolls forward in the next window; and C-M-S-v scrolls backward in the next window. Typing C-g dismisses the query, and quits the command that issued it (see Quitting).

The second type of yes-or-no query is typically employed if giving the wrong answer would have serious consequences; it uses the minibuffer, and features a prompt ending with ‘ (yes or no) ’. For example, if you invoke C-x k ( kill-buffer ) on a file-visiting buffer with unsaved changes, Emacs activates the minibuffer with a prompt like this:

Buffer foo.el modified; kill anyway? (yes or no)

To answer, you must type ‘ yes ’ or ‘ no ’ into the minibuffer, followed by <RET>. The minibuffer behaves as described in the previous sections; you can switch to another window with C-x o , use the history commands M-p and M-n , etc. Type C-g to quit the minibuffer and the querying command.

9 Running Commands by Name

Every Emacs command has a name that you can use to run it. For convenience, many commands also have key bindings. You can run those commands by typing the keys, or run them by name. Most Emacs commands have no key bindings, so the only way to run them is by name. (See Key Bindings, for how to set up key bindings.)

By convention, a command name consists of one or more words, separated by hyphens; for example, auto-fill-mode or manual-entry . Command names mostly use complete English words to make them easier to remember.

To run a command by name, start with M-x , type the command name, then terminate it with <RET>. M-x uses the minibuffer to read the command name. The string ‘ M-x ’ appears at the beginning of the minibuffer as a prompt to remind you to enter a command name to be run. <RET> exits the minibuffer and runs the command. See Minibuffer, for more information on the minibuffer.

You can use completion to enter the command name. For example, to invoke the command forward-char , you can type

M-x forward-char <RET>

or

M-x forw <TAB> c <RET>

Note that forward-char is the same command that you invoke with the key C-f . The existence of a key binding does not stop you from running the command by name.

When M-x completes on commands, it ignores the commands that are declared obsolete ; for these, you will have to type their full name. Obsolete commands are those for which newer, better alternatives exist, and which are slated for removal in some future Emacs release.

To cancel the M-x and not run a command, type C-g instead of entering the command name. This takes you back to command level.

To pass a numeric argument to the command you are invoking with M-x , specify the numeric argument before M-x . The argument value appears in the prompt while the command name is being read, and finally M-x passes the argument to that command. For example, to pass the numeric argument of 42 to the command forward-char you can type C-u 42 M-x forward-char <RET> .

When the command you run with M-x has a key binding, Emacs mentions this in the echo area after running the command. For example, if you type M-x forward-word , the message says that you can run the same command by typing M-f . You can turn off these messages by setting the variable suggest-key-bindings to nil . The value of suggest-key-bindings can also be a number, in which case Emacs will show the binding for that many seconds before removing it from display. The default behavior is to display the binding for 2 seconds.

Commands that don't have key bindings, can still be invoked after typing less than their full name at the ‘ M-x ’ prompt. Emacs mentions such shorthands in the echo area if they are significantly shorter than the full command name, and extended-command-suggest-shorter is non- nil . The setting of suggest-key-bindings affects these hints as well.

In this manual, when we speak of running a command by name, we often omit the <RET> that terminates the name. Thus we might say M-x auto-fill-mode rather than M-x auto-fill-mode <RET> . We mention the <RET> only for emphasis, such as when the command is followed by arguments.

M-x works by running the command execute-extended-command , which is responsible for reading the name of another command and invoking it.

10 Help

Emacs provides a wide variety of help commands, all accessible through the prefix key C-h (or, equivalently, the function key <F1>). These help commands are described in the following sections. You can also type C-h C-h to view a list of help commands ( help-for-help ). You can scroll the list with <SPC> and <DEL>, then type the help command you want. To cancel, type C-g .

Many help commands display their information in a special help buffer . In this buffer, you can type <SPC> and <DEL> to scroll and type <RET> to follow hyperlinks. See Help Mode.

If you are looking for a certain feature, but don't know what it is called or where to look, we recommend three methods. First, try an apropos command, then try searching the manual index, then look in the FAQ and the package keywords.

C-h a topics <RET> This searches for commands whose names match the argument topics . The argument can be a keyword, a list of keywords, or a regular expression (see Regexps). See Apropos.

C-h i d m emacs <RET> i topic <RET> This searches for topic in the indices of the Emacs Info manual, displaying the first match found. Press , to see subsequent matches. You can use a regular expression as topic .

C-h i d m emacs <RET> s topic <RET> Similar, but searches the text of the manual rather than the indices.

C-h C-f This displays the Emacs FAQ, using Info.

C-h p This displays the available Emacs packages based on keywords. See Package Keywords.

C-h or <F1> mean “help” in various other contexts as well. For instance, you can type them after a prefix key to view a list of the keys that can follow the prefix key. (You can also use ? in this context. A few prefix keys don't support C-h or ? in this way, because they define other meanings for those inputs, but they all support <F1>.)

10.1 Help Summary

Here is a summary of help commands for accessing the built-in documentation. Most of these are described in more detail in the following sections.

C-h a topics <RET> Display a list of commands whose names match topics ( apropos-command ).

C-h b Display all active key bindings; minor mode bindings first, then those of the major mode, then global bindings ( describe-bindings ).

C-h c key Show the name of the command that the key sequence key is bound to ( describe-key-briefly ). Here c stands for “character”. For more extensive information on key , use C-h k .

C-h d topics <RET> Display the commands and variables whose documentation matches topics ( apropos-documentation ).

C-h e Display the *Messages* buffer ( view-echo-area-messages ).

C-h f function <RET> Display documentation on the Lisp function named function ( describe-function ). Since commands are Lisp functions, this works for commands too.

C-h h Display the HELLO file, which shows examples of various character sets.

C-h i Run Info, the GNU documentation browser ( info ). The Emacs manual is available in Info.

C-h k key Display the name and documentation of the command that key runs ( describe-key ).

C-h l Display a description of your last 300 keystrokes ( view-lossage ).

C-h m Display documentation of the current major mode and minor modes ( describe-mode ).

C-h n Display news of recent Emacs changes ( view-emacs-news ).

C-h o symbol Display documentation of the Lisp symbol named symbol ( describe-symbol ). This will show the documentation of all kinds of symbols: functions, variables, and faces.

C-h p Find packages by topic keyword ( finder-by-keyword ). This lists packages using a package menu buffer. See Packages.

C-h P package <RET> Display documentation about the specified package ( describe-package ).

C-h r Display the Emacs manual in Info ( info-emacs-manual ).

C-h s Display the contents of the current syntax table ( describe-syntax ). The syntax table says which characters are opening delimiters, which are parts of words, and so on. See Syntax Tables, for details.

C-h t Enter the Emacs interactive tutorial ( help-with-tutorial ).

C-h v var <RET> Display the documentation of the Lisp variable var ( describe-variable ).

C-h w command <RET> Show which keys run the command named command ( where-is ).

C-h C coding <RET> Describe the coding system coding ( describe-coding-system ).

C-h C <RET> Describe the coding systems currently in use.

C-h F command <RET> Enter Info and go to the node that documents the Emacs command command ( Info-goto-emacs-command-node ).

C-h I method <RET> Describe the input method method ( describe-input-method ).

C-h K key Enter Info and go to the node that documents the key sequence key ( Info-goto-emacs-key-command-node ).

C-h L language-env <RET> Display information on the character sets, coding systems, and input methods used in language environment language-env ( describe-language-environment ).

C-h S symbol <RET> Display the Info documentation on symbol symbol according to the programming language you are editing ( info-lookup-symbol ).

C-h . Display the help message for a special text area, if point is in one ( display-local-help ). (These include, for example, links in *Help* buffers.)

10.2 Documentation for a Key

The help commands to get information about a key sequence are C-h c ( describe-key-briefly ) and C-h k ( describe-key ).

C-h c key displays in the echo area the name of the command that key is bound to. For example, C-h c C-f displays ‘ forward-char ’.

C-h k key is similar but gives more information: it displays a help buffer containing the command's documentation string , which describes exactly what the command does.

C-h K key displays the section of the Emacs manual that describes the command corresponding to key .

C-h c , C-h k and C-h K work for any sort of key sequences, including function keys, menus, and mouse events (except that C-h c ignores mouse movement events). For instance, after C-h k you can select a menu item from the menu bar, to view the documentation string of the command it runs.

C-h w command <RET> lists the keys that are bound to command . It displays the list 