Using Multiple Buffers
**********************

Text you are editing in Emacs resides in an object called a buffer.  Each time you visit a file, Emacs creates a buffer to hold the file's text.  Each time you invoke Dired, Emacs creates a buffer to hold the directory listing.  If you send a message with C-x m, a buffer named *mail* is used to hold the text of the message. When you ask for a command's documentation, it appears in a buffer called *Help*.

At any time, one and only one buffer is selected.  It is also called the current buffer.  Saying a command operates on ``the buffer'' really means that the command operates on the selected buffer, as most commands do.

When Emacs creates multiple windows, each window has a chosen buffer which is displayed there, but at any time only one of the windows is selected and its chosen buffer is the selected buffer.  Each window's mode line displays the name of the buffer the window is displaying (see Windows).

Each buffer has a name which can be of any length but is case-sensitive.  You can select a buffer using its name.  Most buffers are created when you visit files; their names are derived from the files' names.  You can also create an empty buffer with any name you want.  A newly started Emacs has a buffer named *scratch* which you can use for evaluating Lisp expressions in Emacs.

Each buffer records what file it is visiting, whether it is modified, and what major mode and minor modes are in effect in it (see Major Modes).  Any Emacs variable can be made local to a particular buffer, meaning its value in that buffer can be different from the value in other buffers.  See Locals.

Creating and Selecting Buffers
==============================

C-x b BUFFER RET
     Select or create a buffer named BUFFER (switch-to-buffer).

C-x 4 b BUFFER RET
     Similar, but select a buffer named BUFFER in another window (switch-to-buffer-other-window).

M-x switch-to-other-buffer N
     Switch to the previous buffer.

To select a buffer named BUFNAME, type C-x b BUFNAME RET.  This is the command switch-to-buffer with argument BUFNAME.  You can use completion on an abbreviation for the buffer name you want (see Completion).  An empty argument to C-x b specifies the most recently selected buffer that is not displayed in any window.

Most buffers are created when you visit files, or use Emacs commands that display text.  You can also create a buffer explicitly by typing C-x b BUFNAME RET, which creates a new, empty buffer that is not visiting any file, and selects it for editing.  The new buffer's major mode is determined by the value of default-major-mode (see Major Modes).  Buffers not visiting files are usually used for making notes to yourself.  If you try to save one, you are asked for the file name to use.

The function switch-to-buffer-other-frame is similar to switch-to-buffer except that it creates a new frame in which to display the selected buffer.

Use M-x switch-to-other-buffer to visit the previous buffer. If you supply a positive integer N, the Nth most recent buffer is displayed. If you supply an argument of 0, the current buffer is moved to the bottom of the buffer stack.

Note that you can also use C-x C-f and any other command for visiting a file to switch buffers.  See Visiting.

Listing Existing Buffers
========================

C-x C-b
     List the existing buffers (list-buffers).

To print a list of all existing buffers, type C-x C-b.  Each line in the list shows one buffer's name, major mode, and visited file. A * at the beginning of a line indicates the buffer has been ``modified''.  If several buffers are modified, it may be time to save some with C-x s (see Saving).  A % indicates a read-only buffer.  A . marks the selected buffer.  Here is an example of a buffer list:

      MR Buffer         Size  Mode           File
      -- ------         ----  ----           ----
     .*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
         *Help*         1287  Fundamental
         files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
       % RMAIL          64042 RMAIL          /u/rms/RMAIL
      *% man            747   Dired		/u2/emacs/man/
         net.emacs      343885 Fundamental   /u/rms/net.emacs
         fileio.c       27691 C              /u2/emacs/src/fileio.c
         NEWS           67340 Text           /u2/emacs/etc/NEWS
         *scratch*	   0	 Lisp Interaction

Note that the buffer *Help* was made by a help request; it is not visiting any file.  The buffer man was made by Dired on the directory /u2/emacs/man/.

As you move the mouse over the *Buffer List* buffer, the lines are highlighted.  This visual cue indicates that clicking the right mouse button (button3) will pop up a menu of commands on the buffer represented by this line.  This menu duplicates most of those commands which are bound to keys in the *Buffer List* buffer.

Miscellaneous Buffer Operations
===============================

C-x C-q
     Toggle read-only status of buffer (toggle-read-only).

M-x rename-buffer
     Change the name of the current buffer.

M-x view-buffer
     Scroll through a buffer.

A buffer can be read-only, which means that commands to change its text are not allowed.  Normally, read-only buffers are created by subsystems such as Dired and Rmail that have special commands to operate on the text.  Emacs also creates a read-only buffer if you visit a file that is protected.  To make changes in a read-only buffer, use the command C-x C-q (toggle-read-only).  It makes a read-only buffer writable, and makes a writable buffer read-only.  This works by setting the variable buffer-read-only, which has a local value in each buffer and makes a buffer read-only if its value is non-nil.

M-x rename-buffer changes the name of the current buffer, prompting for the new name in the minibuffer.  There is no default.  If you specify a name that is used by a different buffer, an error is signalled and renaming is not done.

M-x view-buffer is similar to M-x view-file (see Misc File Ops), but it examines an already existing Emacs buffer.  View mode provides convenient commands for scrolling through the buffer but not for changing it.  When you exit View mode, the resulting value of point remains in effect.

To copy text from one buffer to another, use the commands M-x append-to-buffer and M-x insert-buffer.  See Accumulating Text.

Killing Buffers
===============

After using Emacs for a while, you may accumulate a large number of buffers and may want to eliminate the ones you no longer need.  There are several commands for doing this.

C-x k
     Kill a buffer, specified by name (kill-buffer).

M-x kill-some-buffers
     Offer to kill each buffer, one by one.

C-x k (kill-buffer) kills one buffer, whose name you specify in the minibuffer.  If you type just RET in the minibuffer, the default, killing the current buffer, is used.  If the current buffer is killed, the buffer that has been selected recently but does not appear in any window now is selected.  If the buffer being killed contains unsaved changes, you are asked to confirm with yes before the buffer is killed.

The command M-x kill-some-buffers asks about each buffer, one by one.  An answer of y means to kill the buffer.  Killing the current buffer or a buffer containing unsaved changes selects a new buffer or asks for confirmation just like kill-buffer.

Operating on Several Buffers
============================

The buffer-menu facility is like a ``Dired for buffers''; it allows you to request operations on various Emacs buffers by editing a buffer containing a list of them.  You can save buffers, kill them (here called deleting them, for consistency with Dired), or display them.

M-x buffer-menu
     Begin editing a buffer listing all Emacs buffers.

The command buffer-menu writes a list of all Emacs buffers into the buffer *Buffer List*, and selects that buffer in Buffer Menu mode.  The buffer is read-only.  You can only change it using the special commands described in this section.  Most of the commands are graphic characters.  You can use  Emacs cursor motion commands in the *Buffer List* buffer.  If the cursor is on a line describing a buffer, the following  special commands apply to that buffer:

d
     Request to delete (kill) the buffer, then move down.  A D before the buffer name on a line indicates a deletion request.  Requested deletions actually take place when you use the x command.

k
     Synonym for d.

C-d
     Like d but move up afterwards instead of down.

s
     Request to save the buffer.  An S befor the buffer name on a line indicates the request.  Requested saves actually take place when you use the x command.  You can request both saving and deletion for the same buffer.

~
     Mark buffer ``unmodified''.  The command ~ does this immediately when typed.

x
     Perform previously requested deletions and saves.

u
     Remove any request made for the current line, and move down.

DEL
     Move to previous line and remove any request made for that line.

All commands that add or remove flags to request later operations also move down a line.  They accept a numeric argument as a repeat count, unless otherwise specified.

There are also special commands to use the buffer list to select another buffer, and to specify one or more other buffers for display in additional windows.

1
     Select the buffer in a full-frame window.  This command takes effect immediately.

2
     Immediately set up two windows, with this buffer in one and the buffer selected before *Buffer List* in the other.

f
     Immediately select the buffer in place of the *Buffer List* buffer.

o
     Immediately select the buffer in another window as if by C-x 4 b, leaving *Buffer List* visible.

q
     Immediately select this buffer, and display any buffers previously flagged with the m command in other windows.  If there are no buffers flagged with m, this command is equivalent to 1.

m
     Flag this buffer to be displayed in another window if the q command is used.  The request shows as a > at the beginning of the line.  The same buffer may not have both a delete request and a display request.

Going back between a buffer-menu buffer and other Emacs buffers is easy.  You can, for example, switch from the *Buffer List* buffer to another Emacs buffer, and edit there.  You can then reselect the buffer-menu buffer and perform operations already requested, or you can kill that buffer or pay no further attention to it. All that buffer-menu does directly is create and select a suitable buffer, and turn on Buffer Menu mode.  All the other capabilities of the buffer menu are implemented by special commands provided in Buffer Menu mode.

The only difference between buffer-menu and list-buffers is that buffer-menu selects the *Buffer List* buffer and list-buffers does not.  If you run list-buffers (that is, type C-x C-b) and select the buffer list manually, you can use all the commands described here.