The Emacs Editor

9.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 Text 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 and Aborting).

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. You can customize how the default argument is shown with the user option minibuffer-default-prompt-format.

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. 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 is displayed in brackets after the minibuffer text for a few seconds, or until you type something; then the message disappears. While the minibuffer is in use, Emacs does not echo keystrokes.

While using the minibuffer, you can switch to a different frame, perhaps to note text you need to enter (see Frame Commands). By default, the active minibuffer moves to this new frame. If you set the user option minibuffer-follows-selected-frame to nil, then the minibuffer stays in the frame where you opened it, and you must switch back to that frame in order to complete (or abort) the current command. If you set that option to a value which is neither nil nor t, the minibuffer moves frame only after a recursive minibuffer has been opened in the current command (see (elisp)Recursive Mini). This option is mainly to retain (approximately) the behavior prior to Emacs 28.1. Note that the effect of the command, when you finally finish using the minibuffer, always takes place in the frame where you first opened it. The sole exception is that when that frame no longer exists, the action takes place in the currently selected frame.

9.2 Minibuffers for File Names

Commands such as C-x C-f (find-file) use the minibuffer to read a file name argument (see 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 Editing in the Minibuffer). 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 in The Tramp Manual.

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 HOME and Startup Directories on MS-Windows; for MS-DOS, see File Names on MS-DOS. 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.

9.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. If you want to make SPC and ? insert normally instead of starting completion, you can put the following in your init file:

(keymap-unset minibuffer-local-completion-map "SPC")
(keymap-unset minibuffer-local-completion-map "?")

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 Multiple 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 Multiple 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 Using Other Windows.

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. You might need also to enable minibuffer-depth-indicate-mode to show the current recursion depth in the minibuffer prompt on recursive use of the minibuffer.

When active, the minibuffer is usually in minibuffer-mode. This is an internal Emacs mode without any special features.

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.

9.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 Completion for Symbol Names.

• Completion Example
• Completion Commands
• Completion Exit
• How Completion Alternatives Are Chosen
• Completion Options

9.5 Minibuffer History

Everything you type in the minibuffer is saved in a minibuffer history list so you can easily use it again later. This includes completion candidates (such as file names, buffer names, command names, etc.) and any other kind of minibuffer input. You can use the following commands to quickly fetch an earlier or alternative response 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 Finding Files and URLs at Point), 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 Syntax of Regular Expressions, for an explanation of regular expressions. A numeric prefix argument n means to fetch the nth 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 Matching During Searching).

You can also search through the history using an incremental search. See Searching the 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.

9.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.

9.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 an asterisk (‘*’) 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 and Aborting). C-y inserts the current kill into the password (see Killing and Moving Text). 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.

9.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)’. You answer the query by typing a single key, either ‘y’ or ‘n’, which immediately exits the minibuffer and 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)

The second type of yes-or-no query is typically employed if giving the wrong answer would have serious consequences; it thus features a longer 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.

With both types of yes-or-no query the minibuffer behaves as described in the previous sections; you can recenter the selected window with C-l, scroll that window (C-v or PageDown scrolls forward, M-v or PageUp scrolls backward), switch to another window with C-x o, use the history commands M-p and M-n, etc. Type C-g to dismiss the query, and quit the minibuffer and the querying command (see Quitting and Aborting).

11.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). See Apropos.

C-h b

Display all active key bindings; minor mode bindings first, then those of the major mode, then global bindings (describe-bindings). See Other Help Commands.

C-h C-q

Toggle display of a window showing popular commands and their key bindings. See Other Help Commands.

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. See Documentation for a Key.

C-h d topics RET

Display the commands and variables whose documentation matches topics (apropos-documentation). See Apropos.

C-h e

Display the *Messages* buffer (view-echo-area-messages). See Other Help Commands.

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, but you can also use C-h x. See Help by Command or Variable Name.

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. See Other Help Commands.

C-h k key

Display the name and documentation of the command that key runs (describe-key). See Documentation for a Key.

C-h l

Display a description of your last 300 keystrokes (view-lossage). See Other Help Commands.

C-h m

Display documentation of the current major mode and minor modes (describe-mode). See Other Help Commands.

C-h n

Display news of recent Emacs changes (view-emacs-news). See Help Files.

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. See Help by Command or Variable Name.

C-h p

Find packages by topic keyword (finder-by-keyword). See Keyword Search for Packages. This lists packages using a package menu buffer. See Emacs Lisp Packages.

C-h P package RET

Display documentation about the specified package (describe-package). See Keyword Search for Packages.

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). See Other Help Commands. The syntax table says which characters are opening delimiters, which are parts of words, and so on. See Syntax Tables in The Emacs Lisp Reference Manual, 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). See Help by Command or Variable Name.

C-h w command RET

Show which keys run the command named command (where-is). See Documentation for a Key.

C-h x command RET

Display documentation on the named command (describe-command). See Help by Command or Variable Name.

C-h C coding RET

Describe the coding system coding (describe-coding-system). See Coding Systems.

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). See Help by Command or Variable Name.

C-h I method RET

Describe the input method method (describe-input-method). See Selecting an 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). See Documentation for a Key.

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). See Language Environments.

C-h S symbol RET

Display the Info documentation on symbol symbol according to the programming language you are editing (info-lookup-symbol). See Other Help Commands.

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.) See Help on Active Text and Tooltips. If you invoke this command with a prefix argument, C-u C-h ., and point is on a button or a widget, this command will pop a new buffer that describes that button/widget.

11.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 in the echo area. If it says the command is not on any key, that means you must use M-x to run it. C-h w runs the command where-is.

Some modes in Emacs use various buttons (see Buttons in The Emacs Lisp Reference Manual) and widgets (see Introduction in Emacs Widgets) that can be clicked to perform some action. To find out what function is ultimately invoked by these buttons, Emacs provides the button-describe and widget-describe commands, that should be run with point over the button.

11.3 Help by Command or Variable Name

C-h x command RET (describe-command) displays the documentation of the named command, in a window. For example,

C-h x auto-fill-mode RET

displays the documentation of auto-fill-mode. This is how you would get the documentation of a command that is not bound to any key (one which you would normally run using M-x).

C-h f function RET (describe-function) displays the documentation of Lisp function. This command is intended for Lisp functions that you use in a Lisp program. For example, if you have just written the expression (make-vector len) and want to check that you are using make-vector properly, type C-h f make-vector RET. Additionally, since all commands are Lisp functions, you can also use this command to view the documentation of any command.

If you type C-h f RET, it describes the function called by the innermost Lisp expression in the buffer around point, provided that function name is a valid, defined Lisp function. (That name appears as the default while you enter the argument.) For example, if point is located following the text ‘(make-vector (car x)’, the innermost list containing point is the one that starts with ‘(make-vector’, so C-h f RET describes the function make-vector.

C-h f is also useful just to verify that you spelled a function name correctly. If the minibuffer prompt for C-h f shows the function name from the buffer as the default, it means that name is defined as a Lisp function. Type C-g to cancel the C-h f command if you don’t really want to view the documentation.

If you request help for an autoloaded function whose autoload form (see Autoload in The Emacs Lisp Reference Manual) doesn’t provide a doc string, the *Help* buffer won’t have any doc string to display. In that case, if help-enable-symbol-autoload is non-nil, Emacs will try to load the file in which the function is defined to see whether there’s a doc string there.

You can get an overview of functions relevant for a particular topic by using the M-x shortdoc command. This will prompt you for an area of interest, e.g., string, and pop you to a buffer where many of the functions relevant for handling strings are listed.

C-h v (describe-variable) is like C-h f but describes Lisp variables instead of Lisp functions. Its default is the Lisp symbol around or before point, if that is the name of a defined Lisp variable. See Variables.

Help buffers that describe Emacs variables and functions normally have hyperlinks to the corresponding source code, if you have the source files installed (see Hyperlinking and Web Navigation Features).

To find a command’s documentation in a manual, use C-h F (Info-goto-emacs-command-node). This knows about various manuals, not just the Emacs manual, and finds the right one.

C-h o (describe-symbol) is like C-h f and C-h v, but it describes any symbol, be it a function, a variable, or a face. If the symbol has more than one definition, like it has both definition as a function and as a variable, this command will show the documentation of all of them, one after the other.

If the completions-detailed user option is non-nil, some commands provide details about the possible values when displaying completions. For instance, C-h o TAB will then include the first line of the doc string, and will also say whether each symbol is a function or a variable (and so on). Which details are included varies depending on the command used.

11.4 Apropos

The apropos commands answer questions like, “What are the commands for working with files?” More precisely, you specify your query as an apropos pattern, which is either a word, a list of words separated by whitespace, or a regular expression.

Each of the following apropos commands reads an apropos pattern in the minibuffer, searches for items that match the pattern, and displays the results in a different window.

C-h a ¶

Search for commands (apropos-command). With a prefix argument, search for noninteractive functions too.

M-x apropos ¶

Search for functions and variables. Both interactive functions (commands) and noninteractive functions can be found by this.

M-x apropos-user-option ¶

Search for user-customizable variables. With a prefix argument, search for non-customizable variables too.

M-x apropos-variable ¶

Search for variables. With a prefix argument, search for customizable variables only.

M-x apropos-local-variable ¶

Search for buffer-local variables.

M-x apropos-value ¶

Search for variables whose values match the specified pattern. With a prefix argument, search also for functions with definitions matching the pattern, and Lisp symbols with properties matching the pattern.

M-x apropos-local-value ¶

Search for buffer-local variables whose values match the specified pattern.

C-h d ¶

Search for functions and variables whose documentation strings match the specified pattern (apropos-documentation).

The simplest kind of apropos pattern is one word. Anything containing that word matches the pattern. Thus, to find commands that work on files, type C-h a file RET. This displays a list of all command names that contain ‘file’, including copy-file, find-file, and so on. Each command name comes with a brief description and a list of keys you can currently invoke it with. In our example, it would say that you can invoke find-file by typing C-x C-f.

By default, the window showing the apropos buffer with the results of the query is not selected, but you can cause it to be selected by customizing the variable help-window-select to any non-nil value.

For more information about a function definition, variable or symbol property listed in an apropos buffer, you can click on it with mouse-1 or mouse-2, or move there and type RET.

When you specify more than one word in the apropos pattern, a name must contain at least two of the words in order to match. Thus, if you are looking for commands to kill a chunk of text before point, you could try C-h a kill back backward behind before RET. The real command name kill-backward will match that; if there were a command kill-text-before, it would also match, since it contains two of the specified words.

For even greater flexibility, you can specify a regular expression (see Syntax of Regular Expressions). An apropos pattern is interpreted as a regular expression if it contains any of the regular expression special characters, ‘^$*+?.\[’.

Following the conventions for naming Emacs commands, here are some words that you’ll find useful in apropos patterns. By using them in C-h a, you will also get a feel for the naming conventions.

char, line, word, sentence, paragraph, region, page, sexp, list, defun, rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, forward, backward, next, previous, up, down, search, goto, kill, delete, mark, insert, yank, fill, indent, case, change, set, what, list, find, view, describe, default.

If the variable apropos-do-all is non-nil, most apropos commands behave as if they had been given a prefix argument. There is one exception: apropos-variable without a prefix argument will always search for all variables, no matter what the value of apropos-do-all is.

By default, all apropos commands except apropos-documentation list their results in alphabetical order. If the variable apropos-sort-by-scores is non-nil, these commands instead try to guess the relevance of each result, and display the most relevant ones first. The apropos-documentation command lists its results in order of relevance by default; to list them in alphabetical order, change the variable apropos-documentation-sort-by-scores to nil.

11.5 Help Mode Commands

Help buffers have Help mode as their major mode. Help mode provides the same commands as View mode (see View Mode); for instance, SPC scrolls forward, and DEL or S-SPC scrolls backward. It also provides a few special commands:

RET

Follow a cross reference at point (help-follow).

TAB

Move point forward to the next hyperlink (forward-button).

S-TAB

Move point back to the previous hyperlink (backward-button).

mouse-1

mouse-2

Follow a hyperlink that you click on.

n

p

Move forward and back between pages in the Help buffer.

C-c C-c

Show all documentation about the symbol at point (help-follow-symbol).

C-c C-f

r

Go forward in history of help commands (help-go-forward).

C-c C-b

l

Go back in history of help commands (help-go-back).

s

View the source of the current help topic (if any) (help-view-source).

i

Look up the current topic in the manual(s) (help-goto-info).

I

Look up the current topic in the Emacs Lisp manual (help-goto-lispref-info).

c

Customize the variable or the face (help-customize).

When a function name, variable name, or face name (see Text Faces) appears in the documentation in the help buffer, it is normally an underlined hyperlink. To view the associated documentation, move point there and type RET (help-follow), or click on the hyperlink with mouse-1 or mouse-2. Doing so replaces the contents of the help buffer; to retrace your steps, type C-c C-b or l (help-go-back). While retracing your steps, you can go forward by using C-c C-f or r (help-go-forward).

To move between hyperlinks in a help buffer, use TAB (forward-button) to move forward to the next hyperlink and S-TAB (backward-button) to move back to the previous hyperlink. These commands act cyclically; for instance, typing TAB at the last hyperlink moves back to the first hyperlink.

By default, many links in the help buffer are displayed surrounded by quote characters. If the help-clean-buttons user option is non-nil, these quote characters are removed from the buffer.

Help buffers produced by some Help commands (like C-h b, which shows a long list of key bindings) are divided into pages by the ‘^L’ character. In such buffers, the n (help-goto-next-page) command will take you to the next start of page, and the p (help-goto-previous-page) command will take you to the previous start of page. This way you can quickly navigate between the different kinds of documentation in a help buffer.

A help buffer can also contain hyperlinks to Info manuals, source code definitions, and URLs (web pages). The first two are opened in Emacs, and the third using a web browser via the browse-url command (see Following URLs).

To view all documentation about any symbol in the text, move point to the symbol and type C-c C-c (help-follow-symbol). This shows the documentation for all the meanings of the symbol—as a variable, as a function, and/or as a face.

11.6 Keyword Search for Packages

Most optional features in Emacs are grouped into packages. Emacs contains several hundred built-in packages, and more can be installed over the network (see Emacs Lisp Packages).

To make it easier to find packages related to a topic, most packages are associated with one or more keywords based on what they do. Type C-h p (finder-by-keyword) to bring up a list of package keywords, together with a description of what the keywords mean. To view a list of packages for a given keyword, type RET on that line; this displays the list of packages in a Package Menu buffer (see The Package Menu Buffer).

C-h P (describe-package) prompts for the name of a package (see Emacs Lisp Packages), and displays a help buffer describing the attributes of the package and the features that it implements. The buffer lists the keywords that relate to the package in the form of buttons. Click on a button with mouse-1 or mouse-2 to see the list of other packages related to that keyword.

11.7 Help for International Language Support

For information on a specific language environment (see Language Environments), type C-h L (describe-language-environment). This displays a help buffer describing the languages supported by the language environment, and listing the associated character sets, coding systems, and input methods, as well as some sample text for that language environment.

The command C-h h (view-hello-file) displays the file etc/HELLO, which demonstrates various character sets by showing how to say “hello” in many languages.

The command C-h I (describe-input-method) describes an input method—either a specified input method, or by default the input method currently in use. See Input Methods.

The command C-h C (describe-coding-system) describes coding systems—either a specified coding system, or the ones currently in use. See Coding Systems.

11.8 Other Help Commands

C-h i (info) runs the Info program, which browses structured documentation files. C-h 4 i (info-other-window) does the same, but shows the Info buffer in another window. The entire Emacs manual is available within Info, along with many other manuals for the GNU system. Type h after entering Info to run a tutorial on using Info.

With a numeric argument n, C-h i selects the Info buffer ‘*info*<n>’. This is useful if you want to browse multiple Info manuals simultaneously. If you specify just C-u as the prefix argument, C-h i prompts for the name of a documentation file, so you can browse a file which doesn’t have an entry in the top-level Info menu.

The help commands C-h F function RET and C-h K key, described above, enter Info and go straight to the documentation of function or key.

When editing a program, if you have an Info version of the manual for the programming language, you can use C-h S (info-lookup-symbol) to find an entry for a symbol (keyword, function or variable) in the proper manual. The details of how this command works depend on the major mode.

If something surprising happens, and you are not sure what you typed, use C-h l (view-lossage). C-h l displays your last input keystrokes and the commands they invoked. By default, Emacs stores the last 300 keystrokes; if you wish, you can change this number with the command lossage-size. If you see commands that you are not familiar with, you can use C-h k or C-h f to find out what they do.

To review recent echo area messages, use C-h e (view-echo-area-messages). This displays the buffer *Messages*, where those messages are kept.

Each Emacs major mode typically redefines a few keys and makes other changes in how editing works. C-h m (describe-mode) displays documentation on the current major mode, which normally describes the commands and features that are changed in this mode, and also its key bindings.

C-h b (describe-bindings) and C-h s (describe-syntax) show other information about the current environment within Emacs. C-h b displays a list of all the key bindings now in effect: first the local bindings of the current minor modes, then the local bindings defined by the current major mode, and finally the global bindings (see Customizing Key Bindings). C-h s displays the contents of the syntax table, with explanations of each character’s syntax (see Syntax Tables in The Emacs Lisp Reference Manual).

C-h C-q (help-quick-toggle) toggles on and off the display of a buffer showing the most popular Emacs commands and their respective key bindings (a.k.a. “cheat sheet”). The contents of that buffer are created by the command help-quick. Each key binding shown in this buffer is a button: click on it with mouse-1 or mouse-2 to show the documentation of the command bound to that key sequence.

You can get a list of subcommands for a particular prefix key by typing C-h, ?, or F1 (describe-prefix-bindings) after the prefix key. (There are a few prefix keys for which not all of these keys work—those that provide their own bindings for that key. One of these prefix keys is ESC, because ESC C-h and ESC ? are actually C-M-h (mark-defun) and M-? (xref-find-references), respectively. However, ESC F1 works fine.)

Finally, M-x describe-keymap prompts for the name of a keymap, with completion, and displays a listing of all key bindings in that keymap.

11.9 Help Files

Apart from the built-in documentation and manuals, Emacs contains several other files describing topics like copying conditions, release notes, instructions for debugging and reporting bugs, and so forth. You can use the following commands to view these files. Apart from C-h g, they all have the form C-h C-char.

C-h C-c

Display the rules under which you can copy and redistribute Emacs (describe-copying).

C-h C-d

Display help for debugging Emacs (view-emacs-debugging).

C-h C-e

Display information about where to get external packages (view-external-packages).

C-h C-f

Display the Emacs frequently-answered-questions list (view-emacs-FAQ).

C-h g

Visit the page with information about the GNU Project (describe-gnu-project).

C-h C-m

Display information about ordering printed copies of Emacs manuals (view-order-manuals).

C-h C-n

Display the news, which lists the new features in this version of Emacs (view-emacs-news).

C-h C-o

Display how to order or download the latest version of Emacs and other GNU software (describe-distribution).

C-h C-p

Display the list of known Emacs problems, sometimes with suggested workarounds (view-emacs-problems).

C-h C-t

Display the Emacs to-do list (view-emacs-todo).

C-h C-w

Display the full details on the complete absence of warranty for GNU Emacs (describe-no-warranty).

11.10 Help on Active Text and Tooltips

In Emacs, stretches of active text (text that does something special in response to mouse clicks or RET) often have associated help text. This includes hyperlinks in Emacs buffers, as well as parts of the mode line. On graphical displays, as well as some text terminals which support mouse tracking, moving the mouse over the active text displays the help text as a tooltip. See Tooltips.

On terminals that don’t support mouse-tracking, you can display the help text for active buffer text at point by typing C-h . (display-local-help). This shows the help text in the echo area. To display help text automatically whenever it is available at point, set the variable help-at-pt-display-when-idle to t.

12.1 Setting the Mark

Here are some commands for setting the mark:

C-SPC

Set the mark at point, and activate it (set-mark-command).

C-@

The same.

C-x C-x

Set the mark at point, and activate it; then move point where the mark used to be (exchange-point-and-mark).

Drag-mouse-1

Set point and the mark around the text you drag across.

mouse-3

Set the mark at point, then move point to where you click (mouse-save-then-kill).

Shifted cursor motion keys

Set the mark at point if the mark is inactive, then move point. See Shift Selection.

The most common way to set the mark is with C-SPC (set-mark-command)⁵. This sets the mark where point is, and activates it. You can then move point away, leaving the mark behind.

For example, suppose you wish to convert part of the buffer to upper case. To accomplish this, go to one end of the desired text, type C-SPC, and move point until the desired portion of text is highlighted. Now type C-x C-u (upcase-region). This converts the text in the region to upper case, and then deactivates the mark.

Whenever the mark is active, you can deactivate it by typing C-g (see Quitting and Aborting). Most commands that operate on the region also automatically deactivate the mark, like C-x C-u in the above example.

Instead of setting the mark in order to operate on a region, you can also use it to remember a position in the buffer (by typing C-SPC C-SPC), and later jump back there (by typing C-u C-SPC). See The Mark Ring, for details.

The command C-x C-x (exchange-point-and-mark) exchanges the positions of point and the mark. C-x C-x is useful when you are satisfied with the position of point but want to move the other end of the region (where the mark is). Using C-x C-x a second time, if necessary, puts the mark at the new position with point back at its original position. Normally, if the mark is inactive, this command first reactivates the mark wherever it was last set, to ensure that the region is left highlighted. However, if you call it with a prefix argument, it leaves the mark inactive and the region unhighlighted; you can use this to jump to the mark in a manner similar to C-u C-SPC.

You can also set the mark with the mouse. If you press the left mouse button (down-mouse-1) and drag the mouse across a range of text, this sets the mark where you first pressed the mouse button and puts point where you release it. Alternatively, clicking the right mouse button (mouse-3) sets the mark at point and then moves point to where you clicked. See Mouse Commands for Editing, for a more detailed description of these mouse commands.

Finally, you can set the mark by holding down the shift key while typing certain cursor motion commands (such as S-RIGHT, S-C-f, S-C-n, etc.). This is called shift-selection. It sets the mark at point before moving point, but only if there is no active mark set via a previous shift-selection or mouse commands. The mark set by mouse commands and by shift-selection behaves slightly differently from the usual mark: any subsequent unshifted cursor motion command deactivates it automatically. For details, see Shift Selection.

Many commands that insert text, such as C-y (yank), set the mark at the other end of the inserted text, without activating it. This lets you easily return to that position (see The Mark Ring). You can tell that a command does this when it shows ‘Mark set’ in the echo area.

Under X, every time the active region changes, Emacs saves the text in the region to the primary selection. This lets you insert that text into other X applications with mouse-2 clicks. See Cut and Paste with Other Window Applications.

12.2 Commands to Mark Textual Objects

Here are commands for placing point and the mark around a textual object such as a word, list, paragraph or page:

M-@

Set mark at the end of the next word (mark-word). This does not move point.

C-M-@

Set mark after end of following balanced expression (mark-sexp). This does not move point.

M-h

Move point to the beginning of the current paragraph, and set mark at the end (mark-paragraph).

C-M-h

Move point to the beginning of the current defun, and set mark at the end (mark-defun).

C-x C-p

Move point to the beginning of the current page, and set mark at the end (mark-page).

C-x h

Move point to the beginning of the buffer, and set mark at the end (mark-whole-buffer).

M-@ (mark-word) sets the mark at the end of the next word (see Words, for information about words). Repeated invocations of this command extend the region by advancing the mark one word at a time. As an exception, if the mark is active and located before point, M-@ moves the mark backwards from its current position one word at a time.

This command also accepts a numeric argument n, which tells it to advance the mark by n words. A negative argument -n moves the mark back by n words.

Similarly, C-M-@ (mark-sexp) puts the mark at the end of the next balanced expression (see Expressions with Balanced Parentheses). Repeated invocations extend the region to subsequent expressions, while positive or negative numeric arguments move the mark forward or backward by the specified number of expressions.

The other commands in the above list set both point and mark, so as to delimit an object in the buffer. M-h (mark-paragraph) marks paragraphs (see Paragraphs), C-M-h (mark-defun) marks top-level definitions (see Moving by Defuns), and C-x C-p (mark-page) marks pages (see Pages). Repeated invocations again play the same role, extending the region to consecutive objects; similarly, numeric arguments specify how many objects to move the mark by.

C-x h (mark-whole-buffer) sets up the entire buffer as the region, by putting point at the beginning and the mark at the end.

12.3 Operating on the Region

Once you have a region, here are some of the ways you can operate on it:

• Kill it with C-w (see Killing and Moving Text).
• Copy it to the kill ring with M-w (see Yanking).
• Convert case with C-x C-l or C-x C-u (see Case Conversion Commands).
• Undo changes within it using C-u C-/ (see Undo).
• Replace text within it using M-% (see Query Replace).
• Indent it with C-x TAB or C-M-\ (see Indentation).
• Fill it as text with M-x fill-region (see Filling Text).
• Check the spelling of words within it with M-$ (see Checking and Correcting Spelling).
• Evaluate it as Lisp code with M-x eval-region (see Evaluating Emacs Lisp Expressions).
• Save it in a register with C-x r s (see Registers).
• Save it in a buffer or a file (see Accumulating Text).

Some commands have a default behavior when the mark is inactive, but operate on the region if the mark is active. For example, M-$ (ispell-word) normally checks the spelling of the word at point, but it checks the text in the region if the mark is active (see Checking and Correcting Spelling). Normally, such commands use their default behavior if the region is empty (i.e., if mark and point are at the same position). If you want them to operate on the empty region, change the variable use-empty-active-region to t.

As described in Erasing Text, the DEL (backward-delete-char) and Delete (delete-forward-char) commands also act this way. If the mark is active, they delete the text in the region. (As an exception, if you supply a numeric argument n, where n is not one, these commands delete n characters regardless of whether the mark is active). If you change the variable delete-active-region to nil, then these commands don’t act differently when the mark is active. If you change the value to kill, these commands kill the region instead of deleting it (see Killing and Moving Text).

Other commands always operate on the region, and have no default behavior. Such commands usually have the word region in their names, like C-w (kill-region) and C-x C-u (upcase-region). If the mark is inactive, they operate on the inactive region—that is, on the text between point and the position at which the mark was last set (see The Mark Ring). To disable this behavior, change the variable mark-even-if-inactive to nil. Then these commands will instead signal an error if the mark is inactive.

By default, text insertion occurs normally even if the mark is active—for example, typing a inserts the character ‘a’, then deactivates the mark. Delete Selection mode, a minor mode, modifies this behavior: if you enable that mode, then inserting text while the mark is active causes the text in the region to be deleted first. However, you can tune this behavior by customizing the delete-selection-temporary-region option. Its default value is nil, but you can set it to t, in which case only temporarily-active regions will be replaced: those which are set by dragging the mouse (see Setting the Mark) or by shift-selection (see Shift Selection), as well as by C-u C-x C-x when Transient Mark Mode is disabled. You can further tune the behavior by setting delete-selection-temporary-region to selection: then temporary regions by C-u C-x C-x won’t be replaced, only the ones activated by dragging the mouse or shift-selection. To toggle Delete Selection mode on or off, type M-x delete-selection-mode.

12.4 The Mark Ring

Each buffer remembers previous locations of the mark, in the mark ring. Commands that set the mark also push the old mark onto this ring. One of the uses of the mark ring is to remember spots that you may want to go back to.

C-SPC C-SPC

Set the mark, pushing it onto the mark ring, without activating it.

C-u C-SPC

Move point to where the mark was, and restore the mark from the ring of former marks.

The command C-SPC C-SPC is handy when you want to use the mark to remember a position to which you may wish to return. It pushes the current point onto the mark ring, without activating the mark (which would cause Emacs to highlight the region). This is actually two consecutive invocations of C-SPC (set-mark-command); the first C-SPC sets the mark, and the second C-SPC deactivates it. (When Transient Mark mode is off, C-SPC C-SPC instead activates Transient Mark mode temporarily; see Disabling Transient Mark Mode.)

To return to a marked position, use set-mark-command with a prefix argument: C-u C-SPC. This moves point to where the mark was, and deactivates the mark if it was active. Each subsequent C-u C-SPC jumps to a prior position stored in the mark ring. The positions you move through in this way are not lost; they go to the end of the ring.

If you set set-mark-command-repeat-pop to non-nil, then immediately after you type C-u C-SPC, you can type C-SPC instead of C-u C-SPC to cycle through the mark ring. By default, set-mark-command-repeat-pop is nil.

Each buffer has its own mark ring. All editing commands use the current buffer’s mark ring. In particular, C-u C-SPC always stays in the same buffer.

The variable mark-ring-max specifies the maximum number of entries to keep in the mark ring. This defaults to 16 entries. If that many entries exist and another one is pushed, the earliest one in the list is discarded. Repeating C-u C-SPC cycles through the positions currently in the ring.

If you want to move back to the same place over and over, the mark ring may not be convenient enough. If so, you can record the position in a register for later retrieval (see Saving Positions in Registers).

12.5 The Global Mark Ring

In addition to the ordinary mark ring that belongs to each buffer, Emacs has a single global mark ring. Each time you set a mark, this is recorded in the global mark ring in addition to the current buffer’s own mark ring, if you have switched buffers since the previous mark setting. Hence, the global mark ring records a sequence of buffers that you have been in, and, for each buffer, a place where you set the mark. The length of the global mark ring is controlled by global-mark-ring-max, and is 16 by default.

The command C-x C-SPC (pop-global-mark) jumps to the buffer and position of the latest entry in the global ring. It also rotates the ring, so that successive uses of C-x C-SPC take you to earlier buffers and mark positions.

12.6 Shift Selection

If you hold down the shift key while typing a cursor motion command, this sets the mark before moving point, so that the region extends from the original position of point to its new position. This feature is referred to as shift-selection. It is similar to the way text is selected in other editors.

The mark set via shift-selection behaves a little differently from what we have described above. Firstly, in addition to the usual ways of deactivating the mark (such as changing the buffer text or typing C-g), the mark is deactivated by any unshifted cursor motion command. Secondly, any subsequent shifted cursor motion command avoids setting the mark anew. Therefore, a series of shifted cursor motion commands will continuously adjust the region.

Shift-selection only works if the shifted cursor motion key is not already bound to a separate command (see Customization). For example, if you bind S-C-f to another command, typing S-C-f runs that command instead of performing a shift-selected version of C-f (forward-char).

A mark set via mouse commands behaves the same as a mark set via shift-selection (see Setting the Mark). For example, if you specify a region by dragging the mouse, you can continue to extend the region using shifted cursor motion commands. In either case, any unshifted cursor motion command deactivates the mark.

To turn off shift-selection, set shift-select-mode to nil. Doing so does not disable setting the mark via mouse commands. If you set shift-select-mode to the value permanent, cursor motion keys that were not shift-translated will not deactivate the mark, so, for example, the region set by prior commands can be extended by shift-selection, and unshifted cursor motion keys will extend the region set by shift-selection.

12.7 Disabling Transient Mark Mode

The default behavior of the mark and region, in which setting the mark activates it and highlights the region, is called Transient Mark mode. This is a minor mode that is enabled by default in interactive sessions. It can be toggled with M-x transient-mark-mode, or with the ‘Highlight Active Region’ menu item in the ‘Options’ menu. Turning it off switches Emacs to an alternative mode of operation:

• Setting the mark, with commands like C-SPC or C-x C-x, does not highlight the region. Therefore, you can’t tell by looking where the mark is located; you have to remember.

  The usual solution to this problem is to set the mark and then use it soon, before you forget where it is. You can also check where the mark is by using C-x C-x, which exchanges the positions of the point and the mark (see Setting the Mark).

• Some commands, which ordinarily act on the region when the mark is active, no longer do so. For example, normally M-% (query-replace) performs replacements within the region, if the mark is active. When Transient Mark mode is off, it always operates from point to the end of the buffer. Commands that act this way are identified in their own documentation.

While Transient Mark mode is off, you can activate it temporarily using C-SPC C-SPC or C-u C-x C-x.

C-SPC C-SPC ¶

Set the mark at point (like plain C-SPC) and enable Transient Mark mode just once, until the mark is deactivated. (This is not really a separate command; you are using the C-SPC command twice.)

C-u C-x C-x ¶

Exchange point and mark, activate the mark and enable Transient Mark mode temporarily, until the mark is next deactivated. (This is the C-x C-x command, exchange-point-and-mark, with a prefix argument.)

These commands set or activate the mark, and enable Transient Mark mode only until the mark is deactivated. One reason you may want to use them is that some commands operate on the entire buffer instead of the region when Transient Mark mode is off. Enabling Transient Mark mode momentarily gives you a way to use these commands on the region.

When you specify a region with the mouse (see Setting the Mark), or with shift-selection (see Shift Selection), this likewise activates Transient Mark mode temporarily and highlights the region.

13.1 Deletion and Killing

Most commands which erase text from the buffer save it in the kill ring (see The Kill Ring). These are known as kill commands, and their names normally contain the word ‘kill’ (e.g., kill-line). The kill ring stores several recent kills, not just the last one, so killing is a very safe operation: you don’t have to worry much about losing text that you previously killed. The kill ring is shared by all buffers, so text that is killed in one buffer can be yanked into another buffer.

When you use C-/ (undo) to undo a kill command (see Undo), that brings the killed text back into the buffer, but does not remove it from the kill ring.

On graphical displays, killing text also copies it to the system clipboard. See “Cut and Paste” Operations on Graphical Displays.

Commands that erase text but do not save it in the kill ring are known as delete commands; their names usually contain the word ‘delete’. These include C-d (delete-char) and DEL (delete-backward-char), which delete only one character at a time, and those commands that delete only spaces or newlines. Commands that can erase significant amounts of nontrivial data generally do a kill operation instead.

You can also use the mouse to kill and yank. See “Cut and Paste” Operations on Graphical Displays.

• Deletion
• Killing by Lines
• Other Kill Commands
• Options for Killing

(setq kill-transform-function
      (lambda (string)
        (and (not (string-blank-p string))
             string)))

13.2 Yanking

Yanking means reinserting text previously killed. The usual way to move or copy text is to kill it and then yank it elsewhere.

C-y

Yank the last kill into the buffer, at point (yank).

M-y

Either replace the text just yanked with an earlier batch of killed text (yank-pop), or allow to select from the list of previously-killed batches of text. See Yanking Earlier Kills.

C-M-w

Cause the following command, if it is a kill command, to append to the previous kill (append-next-kill). See Appending Kills.

The basic yanking command is C-y (yank). It inserts the most recent kill, leaving the cursor at the end of the inserted text. It also sets the mark at the beginning of the inserted text, without activating the mark; this lets you jump easily to that position, if you wish, with C-u C-SPC (see The Mark Ring).

With a plain prefix argument (C-u C-y), the command instead leaves the cursor in front of the inserted text, and sets the mark at the end. Using any other prefix argument specifies an earlier kill; e.g., C-u 4 C-y reinserts the fourth most recent kill. See Yanking Earlier Kills.

On graphical displays and on capable text-mode displays, C-y first checks if another application has placed any text in the system clipboard more recently than the last Emacs kill. If so, it inserts the clipboard’s text instead. Thus, Emacs effectively treats “cut” or “copy” clipboard operations performed in other applications like Emacs kills, except that they are not recorded in the kill ring. See “Cut and Paste” Operations on Graphical Displays, for details.

• The Kill Ring
• Yanking Earlier Kills
• Appending Kills

This is a line ∗of sample text.

13.3 “Cut and Paste” Operations on Graphical Displays

In most graphical desktop environments, you can transfer data (usually text) between different applications using a system facility called the clipboard. On X, two other similar facilities are available: the primary selection and the secondary selection. When Emacs is run on a graphical display, its kill and yank commands integrate with these facilities, so that you can easily transfer text between Emacs and other graphical applications.

By default, Emacs uses UTF-8 as the coding system for inter-program text transfers. If you find that the pasted text is not what you expected, you can specify another coding system by typing C-x RET x or C-x RET X. You can also request a different data type by customizing x-select-request-type. See Coding Systems for Interprocess Communication.

• Using the Clipboard
• Cut and Paste with Other Window Applications
• Secondary Selection

13.4 Accumulating Text

Usually we copy or move text by killing it and yanking it, but there are other convenient methods for copying one block of text in many places, or for copying many scattered blocks of text into one place. Here we describe the commands to accumulate scattered pieces of text into a buffer or into a file.

M-x append-to-buffer

Append region to the contents of a specified buffer.

M-x prepend-to-buffer

Prepend region to the contents of a specified buffer.

M-x copy-to-buffer

Copy region into a specified buffer, deleting that buffer’s old contents.

M-x insert-buffer

Insert the contents of a specified buffer into current buffer at point.

M-x append-to-file

Append region to the contents of a specified file, at the end.

To accumulate text into a buffer, use M-x append-to-buffer. This reads a buffer name, then inserts a copy of the region into the buffer specified. If you specify a nonexistent buffer, append-to-buffer creates the buffer. The text is inserted wherever point is in that buffer. If you have been using the buffer for editing, the copied text goes into the middle of the text of the buffer, starting from wherever point happens to be at that moment.

Point in that buffer is left at the end of the copied text, so successive uses of append-to-buffer accumulate the text in the specified buffer in the same order as they were copied. Strictly speaking, append-to-buffer does not always append to the text already in the buffer—it appends only if point in that buffer is at the end. However, if append-to-buffer is the only command you use to alter a buffer, then point is always at the end.

M-x prepend-to-buffer is just like append-to-buffer except that point in the other buffer is left before the copied text, so successive uses of this command add text in reverse order. M-x copy-to-buffer is similar, except that any existing text in the other buffer is deleted, so the buffer is left containing just the text newly copied into it.

The command C-x x i (insert-buffer) can be used to retrieve the accumulated text from another buffer. This prompts for the name of a buffer, and inserts a copy of all the text in that buffer into the current buffer at point, leaving point at the beginning of the inserted text. It also adds the position of the end of the inserted text to the mark ring, without activating the mark. See Using Multiple Buffers, for background information on buffers.

Instead of accumulating text in a buffer, you can append text directly into a file with M-x append-to-file. This prompts for a filename, and adds the text of the region to the end of the specified file. The file is changed immediately on disk.

You should use append-to-file only with files that are not being visited in Emacs. Using it on a file that you are editing in Emacs would change the file behind Emacs’s back, which can lead to losing some of your editing.

Another way to move text around is to store it in a register. See Registers.

13.5 Rectangles

Rectangle commands operate on rectangular areas of the text: all the characters between a certain pair of columns, in a certain range of lines. Emacs has commands to kill rectangles, yank killed rectangles, clear them out, fill them with blanks or text, or delete them. Rectangle commands are useful with text in multicolumn formats, and for changing text into or out of such formats.

To specify a rectangle for a command to work on, set the mark at one corner and point at the opposite corner. The rectangle thus specified is called the region-rectangle. If point and the mark are in the same column, the region-rectangle is empty. If they are in the same line, the region-rectangle is one line high.

The region-rectangle is controlled in much the same way as the region is controlled. But remember that a given combination of point and mark values can be interpreted either as a region or as a rectangle, depending on the command that uses them.

A rectangular region can also be marked using the mouse: click and drag C-M-mouse-1 from one corner of the rectangle to the opposite.

C-x r k

Kill the text of the region-rectangle, saving its contents as the last killed rectangle (kill-rectangle).

C-x r M-w

Save the text of the region-rectangle as the last killed rectangle (copy-rectangle-as-kill).

C-x r d

Delete the text of the region-rectangle (delete-rectangle).

C-x r y

Yank the last killed rectangle with its upper left corner at point (yank-rectangle).

C-x r o

Insert blank space to fill the space of the region-rectangle (open-rectangle). This pushes the previous contents of the region-rectangle to the right.

C-x r N

Insert line numbers along the left edge of the region-rectangle (rectangle-number-lines). This pushes the previous contents of the region-rectangle to the right.

C-x r c

Clear the region-rectangle by replacing all of its contents with spaces (clear-rectangle).

M-x delete-whitespace-rectangle

Delete whitespace in each of the lines on the specified rectangle, starting from the left edge column of the rectangle.

C-x r t string RET

Replace rectangle contents with string on each line (string-rectangle).

M-x string-insert-rectangle RET string RET

Insert string on each line of the rectangle.

C-x SPC

Toggle Rectangle Mark mode (rectangle-mark-mode). When this mode is active, the region-rectangle is highlighted and can be shrunk/grown, and the standard kill and yank commands operate on it.

The rectangle operations fall into two classes: commands to erase or insert rectangles, and commands to make blank rectangles.

There are two ways to erase the text in a rectangle: C-x r d (delete-rectangle) to delete the text outright, or C-x r k (kill-rectangle) to remove the text and save it as the last killed rectangle. In both cases, erasing the region-rectangle is like erasing the specified text on each line of the rectangle; if there is any following text on the line, it moves backwards to fill the gap.

Killing a rectangle is not killing in the usual sense; the rectangle is not stored in the kill ring, but in a special place that only records the most recent rectangle killed. This is because yanking a rectangle is so different from yanking linear text that different yank commands have to be used. Yank-popping is not defined for rectangles.

C-x r M-w (copy-rectangle-as-kill) is the equivalent of M-w for rectangles: it records the rectangle as the last killed rectangle, without deleting the text from the buffer.

To yank the last killed rectangle, type C-x r y (yank-rectangle). The rectangle’s first line is inserted at point, the rectangle’s second line is inserted at the same horizontal position one line vertically below, and so on. The number of lines affected is determined by the height of the saved rectangle.

For example, you can convert two single-column lists into a double-column list by killing one of the single-column lists as a rectangle, and then yanking it beside the other list.

You can also copy rectangles into and out of registers with C-x r r r and C-x r i r. See Saving Rectangles in Registers.

There are two commands you can use for making blank rectangles: C-x r c (clear-rectangle) blanks out existing text in the region-rectangle, and C-x r o (open-rectangle) inserts a blank rectangle.

M-x delete-whitespace-rectangle deletes horizontal whitespace starting from a particular column. This applies to each of the lines in the rectangle, and the column is specified by the left edge of the rectangle. The right edge of the rectangle does not make any difference to this command.

The command C-x r N (rectangle-number-lines) inserts line numbers along the left edge of the region-rectangle. Normally, the numbering begins from 1 (for the first line of the rectangle). With a prefix argument, the command prompts for a number to begin from, and for a format string with which to print the numbers (see Formatting Strings in The Emacs Lisp Reference Manual).

The command C-x r t (string-rectangle) replaces the contents of a region-rectangle with a string on each line. The string’s width need not be the same as the width of the rectangle. If the string’s width is less, the text after the rectangle shifts left; if the string is wider than the rectangle, the text after the rectangle shifts right.

The command M-x string-insert-rectangle is similar to string-rectangle, but inserts the string on each line, shifting the original text to the right.

The command C-x SPC (rectangle-mark-mode) toggles whether the region-rectangle or the standard region is highlighted (first activating the region if necessary). When this mode is enabled, commands that resize the region (C-f, C-n etc.) do so in a rectangular fashion, and killing and yanking operate on the rectangle. See Killing and Moving Text. The mode persists only as long as the region is active.

The region-rectangle works only when the mark is active. In particular, when Transient Mark mode is off (see Disabling Transient Mark Mode), in addition to typing C-x SPC you will need to activate the mark.

Unlike the standard region, the region-rectangle can have its corners extended past the end of buffer, or inside stretches of white space that point normally cannot enter, like in the middle of a TAB character.

When the region is active (see The Mark and the Region) and in rectangle-mark-mode, C-x C-x runs the command rectangle-exchange-point-and-mark, which cycles between the four corners of the region-rectangle. This comes in handy if you want to modify the dimensions of the region-rectangle before invoking an operation on the marked text.

13.6 CUA Bindings

The command M-x cua-mode sets up key bindings that are compatible with the Common User Access (CUA) system used in many other applications.

When CUA mode is enabled, the keys C-x, C-c, C-v, and C-z invoke commands that cut (kill), copy, paste (yank), and undo respectively. The C-x and C-c keys perform cut and copy only if the region is active. Otherwise, they still act as prefix keys, so that standard Emacs commands like C-x C-c still work. Note that this means the variable mark-even-if-inactive has no effect for C-x and C-c (see Operating on the Region).

To enter an Emacs command like C-x C-f while the mark is active, use one of the following methods: either hold Shift together with the prefix key, e.g., S-C-x C-f, or quickly type the prefix key twice, e.g., C-x C-x C-f.

To disable the overriding of standard Emacs binding by CUA mode, while retaining the other features of CUA mode described below, set the variable cua-enable-cua-keys to nil.

CUA mode by default activates Delete-Selection mode (see Mouse Commands for Editing) so that typed text replaces the active region. To use CUA without this behavior, set the variable cua-delete-selection to nil.

CUA mode provides enhanced rectangle support with visible rectangle highlighting. Use C-RET to start a rectangle, extend it using the movement commands, and cut or copy it using C-x or C-c. RET moves the cursor to the next (clockwise) corner of the rectangle, so you can easily expand it in any direction. Normal text you type is inserted to the left or right of each line in the rectangle (on the same side as the cursor).

You can use this rectangle support without activating CUA by calling the cua-rectangle-mark-mode command. There’s also the standard command rectangle-mark-mode, see Rectangles.

With CUA you can easily copy text and rectangles into and out of registers by providing a one-digit numeric prefix to the kill, copy, and yank commands, e.g., C-1 C-c copies the region into register 1, and C-2 C-v yanks the contents of register 2.

CUA mode also has a global mark feature which allows easy moving and copying of text between buffers. Use C-S-SPC to toggle the global mark on and off. When the global mark is on, all text that you kill or copy is automatically inserted at the global mark, and text you type is inserted at the global mark rather than at the current position.

For example, to copy words from various buffers into a word list in a given buffer, set the global mark in the target buffer, then navigate to each of the words you want in the list, mark it (e.g., with S-M-f), copy it to the list with C-c or M-w, and insert a newline after the word in the target list by pressing RET.

14.1 Saving Positions in Registers

C-x r SPC r

Record the position of point and the current buffer in register r (point-to-register).

C-x r j r

Jump to the position and buffer saved in register r (jump-to-register).

Typing C-x r SPC (point-to-register), followed by a character r, saves both the position of point and the current buffer in register r. The register retains this information until you store something else in it.

The command C-x r j r switches to the buffer recorded in register r, pushes a mark, and moves point to the recorded position. (The mark is not pushed if point was already at the recorded position, or in successive calls to the command.) The contents of the register are not changed, so you can jump to the saved position any number of times.

If you use C-x r j to go to a saved position, but the buffer it was saved from has been killed, C-x r j tries to create the buffer again by visiting the same file. Of course, this works only for buffers that were visiting files.

14.2 Saving Text in Registers

When you want to insert a copy of the same piece of text several times, it may be inconvenient to yank it from the kill ring, since each subsequent kill moves that entry further down the ring. An alternative is to store the text in a register and later retrieve it.

C-x r s r

Copy region into register r (copy-to-register).

C-x r i r

Insert text from register r (insert-register).

M-x append-to-register RET r

Append region to text in register r.

When register r contains text, you can use C-x r + (increment-register) to append to that register. Note that command C-x r + behaves differently if r contains a number. See Keeping Numbers in Registers.

M-x prepend-to-register RET r

Prepend region to text in register r.

C-x r s r stores a copy of the text of the region into the register named r. If the mark is inactive, Emacs first reactivates the mark where it was last set. The mark is deactivated at the end of this command. See The Mark and the Region. C-u C-x r s r, the same command with a prefix argument, copies the text into register r and deletes the text from the buffer as well; you can think of this as moving the region text into the register.

M-x append-to-register RET r appends the copy of the text in the region to the text already stored in the register named r. If invoked with a prefix argument, it deletes the region after appending it to the register. The command prepend-to-register is similar, except that it prepends the region text to the text in the register instead of appending it.

When you are collecting text using append-to-register and prepend-to-register, you may want to separate individual collected pieces using a separator. In that case, configure a register-separator and store the separator text in to that register. For example, to get double newlines as text separator during the collection process, you can use the following setting.

(setq register-separator ?+)
(set-register register-separator "\n\n")

C-x r i r inserts in the buffer the text from register r. Normally it leaves point after the text and sets the mark before, without activating it. With a prefix argument, it instead puts point before the text and the mark after.

14.3 Saving Rectangles in Registers

A register can contain a rectangle instead of linear text. See Rectangles, for basic information on how to specify a rectangle in the buffer.

C-x r r r

Copy the region-rectangle into register r (copy-rectangle-to-register). With prefix argument, delete it as well.

C-x r i r

Insert the rectangle stored in register r (if it contains a rectangle) (insert-register).

The C-x r i r (insert-register) command, previously documented in Saving Text in Registers, inserts a rectangle rather than a text string, if the register contains a rectangle.

14.4 Saving Window and Frame Configurations in Registers

You can save the window configuration of the selected frame in a register, or even the configuration of all windows in all frames, and restore the configuration later. See Convenience Features for Window Handling, for information about window configurations.

C-x r w r

Save the state of the selected frame’s windows in register r (window-configuration-to-register).

C-x r f r

Save the state of all frames, including all their windows (a.k.a. frameset), in register r (frameset-to-register).

Use C-x r j r to restore a window or frame configuration. This is the same command used to restore a cursor position. When you restore a frame configuration, any existing frames not included in the configuration become invisible. If you wish to delete these frames instead, use C-u C-x r j r.

14.5 Keeping Numbers in Registers

There are commands to store a number in a register, to insert the number in the buffer in decimal, and to increment it. These commands can be useful in keyboard macros (see Keyboard Macros).

C-u number C-x r n r ¶

Store number into register r (number-to-register).

C-u number C-x r + r ¶

If r contains a number, increment the number in that register by number. Note that command C-x r + (increment-register) behaves differently if r contains text. See Saving Text in Registers.

C-x r i r

Insert the number from register r into the buffer.

C-x r i is the same command used to insert any other sort of register contents into the buffer. C-x r + with no numeric argument increments the register value by 1; C-x r n with no numeric argument stores zero in the register.

14.6 Keeping File and Buffer Names in Registers

If you visit certain file names frequently, you can visit them more conveniently if you put their names in registers. Here’s the Lisp code used to put a file name into register r:

(set-register r '(file . name))

For example,

(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))

puts the file name shown in register ‘z’.

To visit the file whose name is in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frame configuration.)

Similarly, if there are certain buffers you visit frequently, you can put their names in registers. For instance, if you visit the ‘*Messages*’ buffer often, you can use the following snippet to put that buffer into the ‘m’ register:

(set-register ?m '(buffer . "*Messages*"))

To switch to the buffer whose name is in register r, type C-x r j r.

14.7 Keyboard Macro Registers

If you need to execute a keyboard macro (see Keyboard Macros) frequently, it is more convenient to put it in a register or save it (see Naming and Saving Keyboard Macros). C-x C-k x r (kmacro-to-register) stores the last keyboard macro in register r.

To execute the keyboard macro in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frameset.)

14.8 Bookmarks

Bookmarks are somewhat like registers in that they record positions you can jump to. Unlike registers, they have long names, and they persist automatically from one Emacs session to the next. The prototypical use of bookmarks is to record where you were reading in various files.

C-x r m RET

Set the bookmark for the visited file, at point.

C-x r m bookmark RET

Set the bookmark named bookmark at point (bookmark-set).

C-x r M bookmark RET

Like C-x r m, but don’t overwrite an existing bookmark.

C-x r b bookmark RET

Jump to the bookmark named bookmark (bookmark-jump).

C-x r l

List all bookmarks (list-bookmarks).

M-x bookmark-save

Save all the current bookmark values in the default bookmark file.

To record the current position in the visited file, use the command C-x r m, which sets a bookmark using the visited file name as the default for the bookmark name. If you name each bookmark after the file it points to, then you can conveniently revisit any of those files with C-x r b (bookmark-jump), and move to the position of the bookmark at the same time.

In addition to recording the current position, on graphical displays C-x r m places a special image on the left fringe (see Window Fringes) of the screen line corresponding to the recorded position, to indicate that there’s a bookmark there. This can be controlled by the user option bookmark-fringe-mark: customize it to nil to disable the fringe mark. The default value is bookmark-mark, which is the bitmap used for this purpose. When you later use C-x r b to jump back to the bookmark, the fringe mark will be again shown on the fringe.

The command C-x r M (bookmark-set-no-overwrite) works like C-x r m, but it signals an error if the specified bookmark already exists, instead of overwriting it.

To display a list of all your bookmarks in a separate buffer, type C-x r l (list-bookmarks). If you switch to that buffer, you can use it to edit your bookmark definitions or annotate the bookmarks. Type C-h m in the bookmark buffer for more information about its special editing commands.

When you kill Emacs, Emacs saves your bookmarks, if you have changed any bookmark values. You can also save the bookmarks at any time with the M-x bookmark-save command. Bookmarks are saved to the file ~/.emacs.d/bookmarks (for compatibility with older versions of Emacs, if you have a file named ~/.emacs.bmk, that is used instead). The bookmark commands load your default bookmark file automatically. This saving and loading is how bookmarks persist from one Emacs session to the next.

If you set the variable bookmark-save-flag to 1, each command that sets a bookmark will also save your bookmarks; this way, you don’t lose any bookmark values even if Emacs crashes. The value, if a number, says how many bookmark modifications should go by between saving. If you set this variable to nil, Emacs only saves bookmarks if you explicitly use M-x bookmark-save.

The variable bookmark-default-file specifies the file in which to save bookmarks by default.

If you set the variable bookmark-use-annotations to t, setting a bookmark will query for an annotation. If a bookmark has an annotation, it is automatically shown in a separate window when you jump to the bookmark.

Bookmark position values are saved with surrounding context, so that bookmark-jump can find the proper position even if the file is modified slightly. The variable bookmark-search-size says how many characters of context to record on each side of the bookmark’s position. (In buffers that are visiting encrypted files, no context is saved in the bookmarks file no matter the value of this variable.)

Here are some additional commands for working with bookmarks:

M-x bookmark-load RET filename RET ¶

Load a file named filename that contains a list of bookmark values. You can use this command, as well as bookmark-write, to work with other files of bookmark values in addition to your default bookmark file.

M-x bookmark-write RET filename RET ¶

Save all the current bookmark values in the file filename.

M-x bookmark-delete RET bookmark RET ¶

Delete the bookmark named bookmark.

M-x bookmark-insert-location RET bookmark RET ¶

Insert in the buffer the name of the file that bookmark bookmark points to.

M-x bookmark-insert RET bookmark RET ¶

Insert in the buffer the contents of the file that bookmark bookmark points to.