The Emacs Editor

1.1 Point

The cursor in the selected window shows the location where most editing commands take effect, which is called point². 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 Displaying the Cursor, 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 Using Multiple 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 Customization of Display, 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 The 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 from 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 Using Emacs as a 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 and Graphical Displays). 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 Using Multiple 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 Features.

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 Features.)

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 Editing Levels.

You can change the appearance of the mode line as well as the format of its contents. See Optional Mode Line Features. In addition, the mode line is mouse-sensitive; clicking on different parts of the mode line performs various commands. See Mode Line Mouse Commands. 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 Documentation for a Key).

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.

8.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 Convenience Features for Indentation) 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 Text). 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.
• 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 (unless followed by RET); 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 in The Emacs Lisp Reference Manual. 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 Numeric Arguments).

As an alternative to C-x 8, you can select the corresponding transient input method by typing C-u C-x \ iso-transl RET, then temporarily activating this transient input method by typing C-x \ [ will insert the same character ‘ (see transient input method).

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.

8.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 Numeric 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. 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 c a numeric prefix argument.

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 Creating and Selecting Buffers, for the behavior of M-g M-g when you give it a plain prefix argument. Alternatively, you can use the command goto-line-relative to move point to the line relative to the accessible portion of the narrowed buffer.

goto-line has its own history list (see Minibuffer History). You can have either a single list shared between all buffers (the default) or a separate list for each buffer, by customizing the user option goto-line-history-local.

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 (set-goal-column) in the current buffer. When a semipermanent goal column is in effect, C-n, C-p, <prior> and <next> 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.

8.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 The Mark and the Region, 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 If DEL Fails to 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 The Mark and the Region).

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 and Moving Text, for more information about C-k and related commands.

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

On a terminal that supports the Control modifier on all other keys, the easiest way to invoke undo is with C-/, since that doesn’t need the Shift modifier. On terminals which allow only the ASCII control characters, C-/ does not exist, but for many of them C-/ still works because it actually sends C-_ to Emacs, while many others allow you to omit the Shift modifier when you type C-_ (in effect pressing C--), making that the most convenient way to invoke undo.

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.

8.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 The 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 File Handling.

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

8.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 Numeric 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 The 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.

8.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 Changing the Location of 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 Text.

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.

8.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 Features. If you want to have a line number displayed before each line, see Customization of Display.

M-=

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

M-x count-words

Display the number of lines, sentences, words, and characters that are present in the buffer. If the region is active (see The Mark and the Region), 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 Displaying the Cursor.

M-x size-indication-mode

Toggle automatic display of the size of the buffer. See Optional Mode Line Features.

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 The 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, sentences, words, and characters in the region (see The Mark and the Region, 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 Introduction to International Character Sets. 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 user option what-cursor-show-names is non-nil, the name of the character, as defined by the Unicode Character Database, is shown as well. The part in parentheses would then become:

(99, #o143, #x63, LATIN SMALL LETTER C)

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 Customization of Display).

8.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 Text, 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 and Moving Text, 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 The 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.

8.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 Numeric 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.

You can also activate repeat-mode which allows repeating commands bound to sequences of two or more keys by typing a single character. For example, after typing C-x u (undo, see Undo) to undo the most recent edits, you can undo many more edits by typing u u u…. Similarly, type C-x o o o… instead of C-x o C-x o C-x o… to switch to the window several windows away. This works by entering a transient repeating mode after you type the full key sequence that invokes the command; the single-key shortcuts are shown in the echo area.

Only some commands support repetition in repeat-mode; type M-x describe-repeat-maps RET to see which ones.

The single-character shortcuts enabled by the transient repeating mode do not need to be identical: for example, after typing C-x {, either { or } or ^ or v, or any series that mixes these characters in any order, will resize the selected window in respective ways. Similarly, after M-g n or M-g p, typing any sequence of n and/or p in any mix will repeat next-error and previous-error to navigate in a *compilation* or *grep* buffer (see Compilation Mode).

Typing any key other than those defined to repeat the previous command exits the transient repeating mode, and then the key you typed is executed normally. You can also define a key which will exit the transient repeating mode without executing the key which caused the exit. To this end, customize the user option repeat-exit-key to name a key; one natural value is RET. Finally, it’s possible to break the repetition chain automatically after some amount of idle time: customize the user option repeat-exit-timeout to specify the idle time in seconds after which this transient repetition mode will be turned off automatically.

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 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, 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).

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, and move to the position of the bookmark at the same time.

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.

15.1 Scrolling

If a window is too small to display all the text in its buffer, it displays only a portion of it. Scrolling commands change which portion of the buffer is displayed.

Scrolling forward or up advances the portion of the buffer displayed in the window; equivalently, it moves the buffer text upwards relative to the window. Scrolling backward or down displays an earlier portion of the buffer, and moves the text downwards relative to the window.

In Emacs, scrolling up or down refers to the direction that the text moves in the window, not the direction that the window moves relative to the text. This terminology was adopted by Emacs before the modern meaning of “scrolling up” and “scrolling down” became widespread. Hence, the strange result that PageDown scrolls up in the Emacs sense.

The portion of a buffer displayed in a window always contains point. If you move point past the bottom or top of the window, scrolling occurs automatically to bring it back onscreen (see Automatic Scrolling). You can also scroll explicitly with these commands:

C-v

PageDown

next

Scroll forward by nearly a full window (scroll-up-command).

M-v

PageUp

prior

Scroll backward (scroll-down-command).

C-v (scroll-up-command) scrolls forward by nearly the whole window height. The effect is to take the two lines at the bottom of the window and put them at the top, followed by lines that were not previously visible. If point was in the text that scrolled off the top, it ends up on the window’s new topmost line. The PageDown (or next) key is equivalent to C-v.

M-v (scroll-down-command) scrolls backward in a similar way. The PageUp (or prior) key is equivalent to M-v.

The number of lines of overlap left by these scroll commands is controlled by the variable next-screen-context-lines, whose default value is 2. You can supply the commands with a numeric prefix argument, n, to scroll by n lines; Emacs attempts to leave point unchanged, so that the text and point move up or down together. C-v with a negative argument is like M-v and vice versa.

By default, these commands signal an error (by beeping or flashing the screen) if no more scrolling is possible, because the window has reached the beginning or end of the buffer. If you change the variable scroll-error-top-bottom to t, these commands move point to the farthest possible position. If point is already there, the commands signal an error.

Some users like scroll commands to keep point at the same screen position, so that scrolling back to the same screen conveniently returns point to its original position. You can enable this behavior via the variable scroll-preserve-screen-position. If the value is t, Emacs adjusts point to keep the cursor at the same screen position whenever a scroll command moves it off-window, rather than moving it to the topmost or bottommost line. With any other non-nil value, Emacs adjusts point this way even if the scroll command leaves point in the window. This variable affects all the scroll commands documented in this section, as well as scrolling with the mouse wheel (see Mouse Commands for Editing); in general, it affects any command that has a non-nil scroll-command property. See Property Lists in The Emacs Lisp Reference Manual. The same property also causes Emacs not to exit incremental search when one of these commands is invoked and isearch-allow-scroll is non-nil (see Not Exiting Incremental Search).

Sometimes, particularly when you hold down keys such as C-v and M-v, activating keyboard auto-repeat, Emacs fails to keep up with the rapid rate of scrolling requested; the display doesn’t update and Emacs can become unresponsive to input for quite a long time. You can counter this sluggishness by setting the variable fast-but-imprecise-scrolling to a non-nil value. This instructs the scrolling commands not to fontify (see Font Lock mode) any unfontified text they scroll over, instead to assume it has the default face. This can cause Emacs to scroll to somewhat wrong buffer positions when the faces in use are not all the same size, even with single (i.e., without auto-repeat) scrolling operations.

As an alternative to setting fast-but-imprecise-scrolling you might prefer to enable jit-lock deferred fontification (see Font Lock mode). To do this, customize jit-lock-defer-time to a small positive number such as 0.25, or even 0.1 if you type quickly. This gives you less jerky scrolling when you hold down C-v, but the window contents after any action which scrolls into a fresh portion of the buffer will be momentarily unfontified.

Finally, a third alternative to these variables is redisplay-skip-fontification-on-input. If this variable is non-nil, skip some fontifications if there’s input pending. This usually does not affect the display because redisplay is completely skipped anyway if input was pending, but it can make scrolling smoother by avoiding unnecessary fontification.

The commands M-x scroll-up and M-x scroll-down behave similarly to scroll-up-command and scroll-down-command, except they do not obey scroll-error-top-bottom. Prior to Emacs 24, these were the default commands for scrolling up and down. The commands M-x scroll-up-line and M-x scroll-down-line scroll the current window by one line at a time. If you intend to use any of these commands, you might want to give them key bindings (see Rebinding Keys in Your Init File).

15.2 Recentering

C-l

Scroll the selected window so the current line is the center-most text line; on subsequent consecutive invocations, make the current line the top line, the bottom line, and so on in cyclic order. Possibly redisplay the screen too (recenter-top-bottom).

C-M-S-l

Scroll the other window; this is equivalent to C-l acting on the other window.

M-x recenter

Scroll the selected window so the current line is the center-most text line. Possibly redisplay the screen too.

C-M-l

Scroll heuristically to bring useful information onto the screen (reposition-window).

The C-l (recenter-top-bottom) command recenters the selected window, scrolling it so that the current screen line is exactly in the center of the window, or as close to the center as possible.

Typing C-l twice in a row (C-l C-l) scrolls the window so that point is on the topmost screen line. Typing a third C-l scrolls the window so that point is on the bottom-most screen line. Each successive C-l cycles through these three positions.

You can change the cycling order by customizing the list variable recenter-positions. Each list element should be the symbol top, middle, or bottom, or a number; an integer means to move the line to the specified screen line, while a floating-point number between 0.0 and 1.0 specifies a percentage of the screen space from the top of the window. The default, (middle top bottom), is the cycling order described above. Furthermore, if you change the variable scroll-margin to a non-zero value n, C-l always leaves at least n screen lines between point and the top or bottom of the window (see Automatic Scrolling).

You can also give C-l a prefix argument. A plain prefix argument, C-u C-l, simply recenters the line showing point. A positive argument n moves line showing point n lines down from the top of the window. An argument of zero moves point’s line to the top of the window. A negative argument −n moves point’s line n lines from the bottom of the window. When given an argument, C-l does not clear the screen or cycle through different screen positions.

If the variable recenter-redisplay has a non-nil value, each invocation of C-l also clears and redisplays the screen; the special value tty (the default) says to do this on text-terminal frames only. Redisplaying is useful in case the screen becomes garbled for any reason (see Garbage on the Screen).

The more primitive command M-x recenter behaves like recenter-top-bottom, but does not cycle among screen positions.

C-M-l (reposition-window) scrolls the current window heuristically in a way designed to get useful information onto the screen. For example, in a Lisp file, this command tries to get the entire current defun onto the screen if possible.

15.3 Automatic Scrolling