1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Buffers, Windows, Files, Top
6 @chapter Using Multiple Buffers
9 The text you are editing in Emacs resides in an object called a
10 @dfn{buffer}. Each time you visit a file, a buffer is created to hold the
11 file's text. Each time you invoke Dired, a buffer is created to hold the
12 directory listing. If you send a message with @kbd{C-x m}, a buffer named
13 @samp{*mail*} is used to hold the text of the message. When you ask for a
14 command's documentation, that appears in a buffer called @samp{*Help*}.
16 @cindex selected buffer
17 @cindex current buffer
18 At any time, one and only one buffer is @dfn{selected}. It is also
19 called the @dfn{current buffer}. Often we say that a command operates on
20 ``the buffer'' as if there were only one; but really this means that the
21 command operates on the selected buffer (most commands do).
23 When Emacs has multiple windows, each window has its own chosen
24 buffer and displays it; at any time, only one of the windows is
25 selected, and its chosen buffer is the selected buffer. Each window's
26 mode line normally displays the name of the window's chosen buffer
29 Each buffer has a name, which can be of any length, and you can select
30 any buffer by giving its name. Most buffers are made by visiting files,
31 and their names are derived from the files' names. But you can also create
32 an empty buffer with any name you want. A newly started Emacs has a buffer
33 named @samp{*scratch*} which can be used for evaluating Lisp expressions in
34 Emacs. The distinction between upper and lower case matters in buffer
37 Each buffer records individually what file it is visiting, whether it is
38 modified, and what major mode and minor modes are in effect in it
39 (@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a
40 particular buffer, meaning its value in that buffer can be different from
41 the value in other buffers. @xref{Locals}.
44 * Select Buffer:: Creating a new buffer or reselecting an old one.
45 * List Buffers:: Getting a list of buffers that exist.
46 * Misc Buffer:: Renaming; changing read-onlyness; copying text.
47 * Kill Buffer:: Killing buffers you no longer need.
48 * Several Buffers:: How to go through the list of all buffers
49 and operate variously on several of them.
50 * Indirect Buffers:: An indirect buffer shares the text of another buffer.
51 * Buffer Convenience:: Convenience and customization features for
56 @section Creating and Selecting Buffers
57 @cindex change buffers
58 @cindex switch buffers
61 @item C-x b @var{buffer} @key{RET}
62 Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
63 @item C-x 4 b @var{buffer} @key{RET}
64 Similar, but select @var{buffer} in another window
65 (@code{switch-to-buffer-other-window}).
66 @item C-x 5 b @var{buffer} @key{RET}
67 Similar, but select @var{buffer} in a separate frame
68 (@code{switch-to-buffer-other-frame}).
72 @findex switch-to-buffer-other-window
74 @findex switch-to-buffer-other-frame
76 @findex switch-to-buffer
77 To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
78 @key{RET}}. This runs the command @code{switch-to-buffer} with argument
79 @var{bufname}. You can use completion on an abbreviation for the buffer
80 name you want (@pxref{Completion}). An empty argument to @kbd{C-x b}
81 specifies the most recently selected buffer that is not displayed in any
84 Most buffers are created by visiting files, or by Emacs commands that
85 want to display some text, but you can also create a buffer explicitly
86 by typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty
87 buffer that is not visiting any file, and selects it for editing. Such
88 buffers are used for making notes to yourself. If you try to save one,
89 you are asked for the file name to use. The new buffer's major mode is
90 determined by the value of @code{default-major-mode} (@pxref{Major
93 Note that @kbd{C-x C-f}, and any other command for visiting a file,
94 can also be used to switch to an existing file-visiting buffer.
97 Emacs uses buffer names that start with a space for internal purposes.
98 It treats these buffers specially in minor ways---for example, by
99 default they do not record undo information. It is best to avoid using
100 such buffer names yourself.
103 @section Listing Existing Buffers
107 List the existing buffers (@code{list-buffers}).
110 @cindex listing current buffers
113 To display a list of all the buffers that exist, type @kbd{C-x C-b}.
114 Each line in the list shows one buffer's name, major mode and visited
115 file. The buffers are listed in the order that they were current; the
116 buffers that were current most recently come first.
118 @samp{*} at the beginning of a line indicates the buffer is ``modified.''
119 If several buffers are modified, it may be time to save some with @kbd{C-x s}
120 (@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.} marks the
121 selected buffer. Here is an example of a buffer list:@refill
124 MR Buffer Size Mode File
125 -- ------ ---- ---- ----
126 .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
127 *Help* 1287 Fundamental
128 files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
129 % RMAIL 64042 RMAIL /u/rms/RMAIL
130 *% man 747 Dired /u2/emacs/man/
131 net.emacs 343885 Fundamental /u/rms/net.emacs
132 fileio.c 27691 C /u2/emacs/src/fileio.c
133 NEWS 67340 Text /u2/emacs/etc/NEWS
134 *scratch* 0 Lisp Interaction
138 Note that the buffer @samp{*Help*} was made by a help request; it is
139 not visiting any file. The buffer @code{man} was made by Dired on the
140 directory @file{/u2/emacs/man/}. You can list only buffers that are
141 visiting files by giving the command a prefix; for instance, by typing
146 @section Miscellaneous Buffer Operations
150 Toggle read-only status of buffer (@code{vc-toggle-read-only}).
151 @item M-x rename-buffer @key{RET} @var{name} @key{RET}
152 Change the name of the current buffer.
153 @item M-x rename-uniquely
154 Rename the current buffer by adding @samp{<@var{number}>} to the end.
155 @item M-x view-buffer @key{RET} @var{buffer} @key{RET}
156 Scroll through buffer @var{buffer}.
160 @c Don't index vc-toggle-read-only here, it is indexed in files.texi,
161 @c in the node "Basic VC Editing".
162 @c @findex vc-toggle-read-only
163 @vindex buffer-read-only
164 @cindex read-only buffer
165 A buffer can be @dfn{read-only}, which means that commands to change
166 its contents are not allowed. The mode line indicates read-only
167 buffers with @samp{%%} or @samp{%*} near the left margin. Read-only
168 buffers are usually made by subsystems such as Dired and Rmail that
169 have special commands to operate on the text; also by visiting a file
170 whose access control says you cannot write it.
172 If you wish to make changes in a read-only buffer, use the command
173 @kbd{C-x C-q} (@code{vc-toggle-read-only}). It makes a read-only buffer
174 writable, and makes a writable buffer read-only. In most cases, this
175 works by setting the variable @code{buffer-read-only}, which has a local
176 value in each buffer and makes the buffer read-only if its value is
177 non-@code{nil}. If the file is maintained with version control,
178 @kbd{C-x C-q} works through the version control system to change the
179 read-only status of the file as well as the buffer. @xref{Version
182 @findex rename-buffer
183 @kbd{M-x rename-buffer} changes the name of the current buffer. Specify
184 the new name as a minibuffer argument. There is no default. If you
185 specify a name that is in use for some other buffer, an error happens and
188 @kbd{M-x rename-uniquely} renames the current buffer to a similar name
189 with a numeric suffix added to make it both different and unique. This
190 command does not need an argument. It is useful for creating multiple
191 shell buffers: if you rename the @samp{*Shell*} buffer, then do @kbd{M-x
192 shell} again, it makes a new shell buffer named @samp{*Shell*};
193 meanwhile, the old shell buffer continues to exist under its new name.
194 This method is also good for mail buffers, compilation buffers, and most
195 Emacs features that create special buffers with particular names.
198 @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
199 File Ops}) except that it examines an already existing Emacs buffer.
200 View mode provides commands for scrolling through the buffer
201 conveniently but not for changing it. When you exit View mode with
202 @kbd{q}, that switches back to the buffer (and the position) which was
203 previously displayed in the window. Alternatively, if you exit View
204 mode with @kbd{e}, the buffer and the value of point that resulted from
205 your perusal remain in effect.
207 The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
208 can be used to copy text from one buffer to another. @xref{Accumulating
212 @section Killing Buffers
214 @cindex killing buffers
215 If you continue an Emacs session for a while, you may accumulate a
216 large number of buffers. You may then find it convenient to @dfn{kill}
217 the buffers you no longer need. On most operating systems, killing a
218 buffer releases its space back to the operating system so that other
219 programs can use it. Here are some commands for killing buffers:
223 @item C-x k @var{bufname} @key{RET}
224 Kill buffer @var{bufname} (@code{kill-buffer}).
225 @item M-x kill-some-buffers
226 Offer to kill each buffer, one by one.
230 @findex kill-some-buffers
233 @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
234 specify in the minibuffer. The default, used if you type just @key{RET}
235 in the minibuffer, is to kill the current buffer. If you kill the
236 current buffer, another buffer is selected; one that has been selected
237 recently but does not appear in any window now. If you ask to kill a
238 file-visiting buffer that is modified (has unsaved editing), then you
239 must confirm with @kbd{yes} before the buffer is killed.
241 The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
242 one. An answer of @kbd{y} means to kill the buffer. Killing the current
243 buffer or a buffer containing unsaved changes selects a new buffer or asks
244 for confirmation just like @code{kill-buffer}.
246 The buffer menu feature (@pxref{Several Buffers}) is also convenient
247 for killing various buffers.
249 @vindex kill-buffer-hook
250 If you want to do something special every time a buffer is killed, you
251 can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}).
253 @findex clean-buffer-list
254 If you run one Emacs session for a period of days, as many people do,
255 it can fill up with buffers that you used several days ago. The command
256 @kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills
257 all the unmodified buffers that you have not used for a long time. An
258 ordinary buffer is killed if it has not been displayed for three days;
259 however, you can specify certain buffers that should never be killed
260 automatically, and others that should be killed if they have been unused
263 @cindex Midnight mode
264 @vindex midnight-mode
265 @vindex midnight-hook
266 You can also have this buffer purging done for you, every day at
267 midnight, by enabling Midnight mode. Midnight mode operates each day at
268 midnight; at that time, it runs @code{clean-buffer-list}, or whichever
269 functions you have placed in the normal hook @code{midnight-hook}
272 To enable Midnight mode, use the Customization buffer to set the
273 variable @code{midnight-mode} to @code{t}. @xref{Easy Customization}.
275 @node Several Buffers
276 @section Operating on Several Buffers
279 The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
280 you to request operations on various Emacs buffers by editing an Emacs
281 buffer containing a list of them. You can save buffers, kill them
282 (here called @dfn{deleting} them, for consistency with Dired), or display
286 @item M-x buffer-menu
287 Begin editing a buffer listing all Emacs buffers.
291 The command @code{buffer-menu} writes a list of all Emacs buffers into
292 the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
293 mode. The buffer is read-only, and can be changed only through the
294 special commands described in this section. The usual Emacs cursor
295 motion commands can be used in the @samp{*Buffer List*} buffer. The
296 following commands apply to the buffer described on the current line.
300 Request to delete (kill) the buffer, then move down. The request
301 shows as a @samp{D} on the line, before the buffer name. Requested
302 deletions take place when you type the @kbd{x} command.
304 Like @kbd{d} but move up afterwards instead of down.
306 Request to save the buffer. The request shows as an @samp{S} on the
307 line. Requested saves take place when you type the @kbd{x} command.
308 You may request both saving and deletion for the same buffer.
310 Perform previously requested deletions and saves.
312 Remove any request made for the current line, and move down.
314 Move to previous line and remove any request made for that line.
317 The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
318 flags also move down (or up) one line. They accept a numeric argument
321 These commands operate immediately on the buffer listed on the current
326 Mark the buffer ``unmodified.'' The command @kbd{~} does this
327 immediately when you type it.
329 Toggle the buffer's read-only flag. The command @kbd{%} does
330 this immediately when you type it.
332 Visit the buffer as a tags table. @xref{Select Tags Table}.
335 There are also commands to select another buffer or buffers:
339 Quit the buffer menu---immediately display the most recent formerly
340 visible buffer in its place.
343 Immediately select this line's buffer in place of the @samp{*Buffer
346 Immediately select this line's buffer in another window as if by
347 @kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
349 Immediately display this line's buffer in another window, but don't
352 Immediately select this line's buffer in a full-screen window.
354 Immediately set up two windows, with this line's buffer in one, and the
355 previously selected buffer (aside from the buffer @samp{*Buffer List*})
358 Bury the buffer listed on this line.
360 Mark this line's buffer to be displayed in another window if you exit
361 with the @kbd{v} command. The request shows as a @samp{>} at the
362 beginning of the line. (A single buffer may not have both a delete
363 request and a display request.)
365 Immediately select this line's buffer, and also display in other windows
366 any buffers previously marked with the @kbd{m} command. If you have not
367 marked any buffers, this command is equivalent to @kbd{1}.
370 All that @code{buffer-menu} does directly is create and switch to a
371 suitable buffer, and turn on Buffer Menu mode. Everything else
372 described above is implemented by the special commands provided in
373 Buffer Menu mode. One consequence of this is that you can switch from
374 the @samp{*Buffer List*} buffer to another Emacs buffer, and edit there.
375 You can reselect the @samp{*Buffer List*} buffer later, to perform the
376 operations already requested, or you can kill it, or pay no further
379 The only difference between @code{buffer-menu} and @code{list-buffers}
380 is that @code{buffer-menu} switches to the @samp{*Buffer List*} buffer
381 in the selected window; @code{list-buffers} displays it in another
382 window. If you run @code{list-buffers} (that is, type @kbd{C-x C-b})
383 and select the buffer list manually, you can use all of the commands
386 The buffer @samp{*Buffer List*} is not updated automatically when
387 buffers are created and killed; its contents are just text. If you have
388 created, deleted or renamed buffers, the way to update @samp{*Buffer
389 List*} to show what you have done is to type @kbd{g}
390 (@code{revert-buffer}) or repeat the @code{buffer-menu} command.
392 @node Indirect Buffers
393 @section Indirect Buffers
394 @cindex indirect buffer
397 An @dfn{indirect buffer} shares the text of some other buffer, which
398 is called the @dfn{base buffer} of the indirect buffer. In some ways it
399 is the analogue, for buffers, of a symbolic link between files.
402 @findex make-indirect-buffer
403 @item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
404 Create an indirect buffer named @var{indirect-name} whose base buffer
405 is @var{base-buffer}.
406 @findex clone-indirect-buffer
407 @item M-x clone-indirect-buffer @key{RET}
408 Create an indirect buffer that is a twin copy of the current buffer.
411 @findex clone-indirect-buffer-other-window
412 Create an indirect buffer that is a twin copy of the current buffer, and
413 select it in another window (@code{clone-indirect-buffer-other-window}).
416 The text of the indirect buffer is always identical to the text of its
417 base buffer; changes made by editing either one are visible immediately
418 in the other. But in all other respects, the indirect buffer and its
419 base buffer are completely separate. They have different names,
420 different values of point, different narrowing, different markers,
421 different major modes, and different local variables.
423 An indirect buffer cannot visit a file, but its base buffer can. If
424 you try to save the indirect buffer, that actually works by saving the
425 base buffer. Killing the base buffer effectively kills the indirect
426 buffer, but killing an indirect buffer has no effect on its base buffer.
428 One way to use indirect buffers is to display multiple views of an
429 outline. @xref{Outline Views}.
431 @cindex multiple @samp{*info*} and @samp{*Help*} buffers
432 A quick and handy way to make an indirect buffer is with the command
433 @kbd{M-x clone-indirect-buffer}. It creates and selects an indirect
434 buffer whose base buffer is the current buffer. With a numeric
435 argument, it prompts for the name of the indirect buffer; otherwise it
436 defaults to the name of the current buffer, modifying it by adding a
437 @samp{<@var{n}>} prefix if required. @kbd{C-x 4 c}
438 (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x
439 clone-indirect-buffer}, but it selects the cloned buffer in another
440 window. These commands come in handy if you want to create new
441 @samp{*info*} or @samp{*Help*} buffers, for example.
443 The more general way is with the command @kbd{M-x
444 make-indirect-buffer}. It creates an indirect buffer from buffer
445 @var{base-buffer}, under the name @var{indirect-name}. It prompts for
446 both @var{base-buffer} and @var{indirect-name} using the minibuffer.
448 @node Buffer Convenience
449 @section Convenience Features and Customization of Buffer Handling
451 This section describes several modes and features that make it more
452 convenient to switch between buffers.
455 * Uniquify:: Buffer names can contain directory parts.
456 * Iswitchb:: Switching between buffers with substrings.
457 * Buffer Menus:: Configurable buffer menu.
461 @subsection Making Buffer Names Unique
463 @cindex unique buffer names
464 @cindex directories in buffer names
465 When several buffers visit identically-named files, Emacs must give
466 the buffers distinct names. The usual method for making buffer names
467 unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer
468 names (all but one of them).
470 @vindex uniquify-buffer-name-style
471 Other methods work by adding parts of each file's directory to the
472 buffer name. To select one, customize the variable
473 @code{uniquify-buffer-name-style} (@pxref{Easy Customization}).
475 For instance, the @code{forward} naming method puts part of the
476 directory name at the beginning of the buffer name; using this method,
477 buffers visiting @file{/u/mernst/tmp/Makefile} and
478 @file{/usr/projects/zaphod/Makefile} would be named
479 @samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead
480 of @samp{Makefile} and @samp{Makefile<2>}).
482 By contrast, the @code{post-forward} naming method would call the
483 buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the
484 @code{reverse} naming method would call them @samp{Makefile\tmp} and
485 @samp{Makefile\zaphod}. The nontrivial difference between
486 @code{post-forward} and @code{reverse} occurs when just one directory
487 name is not enough to distinguish two files; then @code{reverse} puts
488 the directory names in reverse order, so that @file{/top/middle/file}
489 becomes @samp{file\middle\top}, while @code{post-forward} puts them in
490 forward order after the file name, as in @samp{file|top/middle}.
492 Which rule to follow for putting the directory names in the buffer
493 name is not very important if you are going to @emph{look} at the
494 buffer names before you type one. But as an experienced user, if you
495 know the rule, you won't have to look. And then you may find that one
496 rule or another is easier for you to remember and utilize fast.
499 @subsection Switching Between Buffers using Substrings
501 @findex iswitchb-mode
502 @cindex Iswitchb mode
503 @cindex mode, Iswitchb
504 @kindex C-x b @r{(Iswitchb mode)}
505 @kindex C-x 4 b @r{(Iswitchb mode)}
506 @kindex C-x 5 b @r{(Iswitchb mode)}
507 @kindex C-x 4 C-o @r{(Iswitchb mode)}
509 Iswitchb global minor mode provides convenient switching between
510 buffers using substrings of their names. It replaces the normal
511 definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x
512 4 C-o} with alternative commands that are somewhat ``smarter.''
514 When one of these commands prompts you for a buffer name, you can
515 type in just a substring of the name you want to choose. As you enter
516 the substring, Iswitchb mode continuously displays a list of buffers
517 that match the substring you have typed.
519 At any time, you can type @key{RET} to select the first buffer in
520 the list. So the way to select a particular buffer is to make it the
521 first in the list. There are two ways to do this. You can type more
522 of the buffer name and thus narrow down the list, excluding unwanted
523 buffers above the desired one. Alternatively, you can use @kbd{C-s}
524 and @kbd{C-r} to rotate the list until the desired buffer is first.
526 @key{TAB} while entering the buffer name performs completion on the
527 string you have entered, based on the displayed list of buffers.
529 To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize
530 the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy
534 @subsection Customizing Buffer Menus
537 @cindex buffer list, customizable
540 Make a list of buffers similarly to @kbd{M-x list-buffers} but
544 @kbd{M-x bs-show} pops up a buffer list similar to the one normally
545 displayed by @kbd{C-x C-b} but which you can customize. If you prefer
546 this to the usual buffer list, you can bind this command to @kbd{C-x
547 C-b}. To customize this buffer list, use the @code{bs} Custom group
548 (@pxref{Easy Customization}).
554 @findex mouse-buffer-menu
555 @kindex C-Down-Mouse-1
556 MSB global minor mode (``MSB'' stands for ``mouse select buffer'')
557 provides a different and customizable mouse buffer menu which you may
558 prefer. It replaces the bindings of @code{mouse-buffer-menu},
559 normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You
560 can customize the menu in the @code{msb} Custom group.