1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001
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}.
43 @cindex buffer size, maximum
44 A buffer's size cannot be larger than some maximum, which is defined
45 by largest buffer position representable by the @dfn{Emacs integer} data
46 type. This is because Emacs tracks buffer positions using that data
47 type. For 32-bit machines, the largest buffer size is 128 megabytes.
50 * Select Buffer:: Creating a new buffer or reselecting an old one.
51 * List Buffers:: Getting a list of buffers that exist.
52 * Misc Buffer:: Renaming; changing read-onlyness; copying text.
53 * Kill Buffer:: Killing buffers you no longer need.
54 * Several Buffers:: How to go through the list of all buffers
55 and operate variously on several of them.
56 * Indirect Buffers:: An indirect buffer shares the text of another buffer.
57 * Buffer Convenience:: Convenience and customization features for
62 @section Creating and Selecting Buffers
63 @cindex change buffers
64 @cindex switch buffers
67 @item C-x b @var{buffer} @key{RET}
68 Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
69 @item C-x 4 b @var{buffer} @key{RET}
70 Similar, but select @var{buffer} in another window
71 (@code{switch-to-buffer-other-window}).
72 @item C-x 5 b @var{buffer} @key{RET}
73 Similar, but select @var{buffer} in a separate frame
74 (@code{switch-to-buffer-other-frame}).
78 @findex switch-to-buffer
79 To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
80 @key{RET}}. This runs the command @code{switch-to-buffer} with argument
81 @var{bufname}. You can use completion on an abbreviation for the buffer
82 name you want (@pxref{Completion}). An empty argument to @kbd{C-x b}
83 specifies the most recently selected buffer that is not displayed in any
87 @findex switch-to-buffer-other-window
88 @vindex even-window-heights
89 To select a buffer in a window other than the current one, type
90 @kbd{C-x 4 b @var{bufname} @key{RET}}. This runs the command
91 @code{switch-to-buffer-other-window} which displays the buffer
92 @var{bufname} in another window. By default, if displaying the buffer
93 causes two vertically adjacent windows to be displayed, the heights of
94 those windows are evened out; to countermand that and preserve the
95 window configuration, set the variable @code{even-window-heights} to
99 @findex switch-to-buffer-other-frame
100 Similarly, @kbd{C-x 5 b @var{buffer} @key{RET}} runs the command
101 @code{switch-to-buffer-other-frame} which selects a buffer in another
104 @vindex display-buffer-reuse-frames
105 You can control how certain buffers are handled by these commands by
106 customizing the variables @code{special-display-buffer-names},
107 @code{special-display-regexps}, @code{same-window-buffer-names}, and
108 @code{same-window-regexps}. See @ref{Force Same Window}, and
109 @ref{Special Buffer Frames}, for more about these variables. In
110 addition, if the value of @code{display-buffer-reuse-frames} is
111 non-@code{nil}, and the buffer you want to switch to is already
112 displayed in some frame, Emacs will raise that frame.
114 Most buffers are created by visiting files, or by Emacs commands that
115 want to display some text, but you can also create a buffer explicitly
116 by typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty
117 buffer that is not visiting any file, and selects it for editing. Such
118 buffers are used for making notes to yourself. If you try to save one,
119 you are asked for the file name to use. The new buffer's major mode is
120 determined by the value of @code{default-major-mode} (@pxref{Major
123 Note that @kbd{C-x C-f}, and any other command for visiting a file,
124 can also be used to switch to an existing file-visiting buffer.
127 Emacs uses buffer names that start with a space for internal purposes.
128 It treats these buffers specially in minor ways---for example, by
129 default they do not record undo information. It is best to avoid using
130 such buffer names yourself.
133 @section Listing Existing Buffers
137 List the existing buffers (@code{list-buffers}).
140 @cindex listing current buffers
143 To display a list of all the buffers that exist, type @kbd{C-x C-b}.
144 Each line in the list shows one buffer's name, major mode and visited
145 file. The buffers are listed in the order that they were current; the
146 buffers that were current most recently come first.
148 @samp{*} at the beginning of a line indicates the buffer is ``modified.''
149 If several buffers are modified, it may be time to save some with @kbd{C-x s}
150 (@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.} marks the
151 selected buffer. Here is an example of a buffer list:@refill
154 MR Buffer Size Mode File
155 -- ------ ---- ---- ----
156 .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
157 *Help* 1287 Fundamental
158 files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
159 % RMAIL 64042 RMAIL /u/rms/RMAIL
160 *% man 747 Dired /u2/emacs/man/
161 net.emacs 343885 Fundamental /u/rms/net.emacs
162 fileio.c 27691 C /u2/emacs/src/fileio.c
163 NEWS 67340 Text /u2/emacs/etc/NEWS
164 *scratch* 0 Lisp Interaction
168 Note that the buffer @samp{*Help*} was made by a help request; it is
169 not visiting any file. The buffer @code{man} was made by Dired on the
170 directory @file{/u2/emacs/man/}. You can list only buffers that are
171 visiting files by giving the command a prefix; for instance, by typing
176 @section Miscellaneous Buffer Operations
180 Toggle read-only status of buffer (@code{vc-toggle-read-only}).
181 @item M-x rename-buffer @key{RET} @var{name} @key{RET}
182 Change the name of the current buffer.
183 @item M-x rename-uniquely
184 Rename the current buffer by adding @samp{<@var{number}>} to the end.
185 @item M-x view-buffer @key{RET} @var{buffer} @key{RET}
186 Scroll through buffer @var{buffer}.
190 @c Don't index vc-toggle-read-only here, it is indexed in files.texi,
191 @c in the node "Basic VC Editing".
192 @c @findex vc-toggle-read-only
193 @vindex buffer-read-only
194 @cindex read-only buffer
195 A buffer can be @dfn{read-only}, which means that commands to change
196 its contents are not allowed. The mode line indicates read-only
197 buffers with @samp{%%} or @samp{%*} near the left margin. Read-only
198 buffers are usually made by subsystems such as Dired and Rmail that
199 have special commands to operate on the text; also by visiting a file
200 whose access control says you cannot write it.
202 If you wish to make changes in a read-only buffer, use the command
203 @kbd{C-x C-q} (@code{vc-toggle-read-only}). It makes a read-only buffer
204 writable, and makes a writable buffer read-only. In most cases, this
205 works by setting the variable @code{buffer-read-only}, which has a local
206 value in each buffer and makes the buffer read-only if its value is
207 non-@code{nil}. If the file is maintained with version control,
208 @kbd{C-x C-q} works through the version control system to change the
209 read-only status of the file as well as the buffer. @xref{Version
212 @findex rename-buffer
213 @kbd{M-x rename-buffer} changes the name of the current buffer. Specify
214 the new name as a minibuffer argument. There is no default. If you
215 specify a name that is in use for some other buffer, an error happens and
218 @kbd{M-x rename-uniquely} renames the current buffer to a similar name
219 with a numeric suffix added to make it both different and unique. This
220 command does not need an argument. It is useful for creating multiple
221 shell buffers: if you rename the @samp{*Shell*} buffer, then do @kbd{M-x
222 shell} again, it makes a new shell buffer named @samp{*Shell*};
223 meanwhile, the old shell buffer continues to exist under its new name.
224 This method is also good for mail buffers, compilation buffers, and most
225 Emacs features that create special buffers with particular names.
228 @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
229 File Ops}) except that it examines an already existing Emacs buffer.
230 View mode provides commands for scrolling through the buffer
231 conveniently but not for changing it. When you exit View mode with
232 @kbd{q}, that switches back to the buffer (and the position) which was
233 previously displayed in the window. Alternatively, if you exit View
234 mode with @kbd{e}, the buffer and the value of point that resulted from
235 your perusal remain in effect.
237 The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
238 can be used to copy text from one buffer to another. @xref{Accumulating
242 @section Killing Buffers
244 @cindex killing buffers
245 If you continue an Emacs session for a while, you may accumulate a
246 large number of buffers. You may then find it convenient to @dfn{kill}
247 the buffers you no longer need. On most operating systems, killing a
248 buffer releases its space back to the operating system so that other
249 programs can use it. Here are some commands for killing buffers:
253 @item C-x k @var{bufname} @key{RET}
254 Kill buffer @var{bufname} (@code{kill-buffer}).
255 @item M-x kill-some-buffers
256 Offer to kill each buffer, one by one.
260 @findex kill-some-buffers
263 @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
264 specify in the minibuffer. The default, used if you type just @key{RET}
265 in the minibuffer, is to kill the current buffer. If you kill the
266 current buffer, another buffer is selected; one that has been selected
267 recently but does not appear in any window now. If you ask to kill a
268 file-visiting buffer that is modified (has unsaved editing), then you
269 must confirm with @kbd{yes} before the buffer is killed.
271 The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
272 one. An answer of @kbd{y} means to kill the buffer. Killing the current
273 buffer or a buffer containing unsaved changes selects a new buffer or asks
274 for confirmation just like @code{kill-buffer}.
276 The buffer menu feature (@pxref{Several Buffers}) is also convenient
277 for killing various buffers.
279 @vindex kill-buffer-hook
280 If you want to do something special every time a buffer is killed, you
281 can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}).
283 @findex clean-buffer-list
284 If you run one Emacs session for a period of days, as many people do,
285 it can fill up with buffers that you used several days ago. The command
286 @kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills
287 all the unmodified buffers that you have not used for a long time. An
288 ordinary buffer is killed if it has not been displayed for three days;
289 however, you can specify certain buffers that should never be killed
290 automatically, and others that should be killed if they have been unused
293 @cindex Midnight mode
294 @vindex midnight-mode
295 @vindex midnight-hook
296 You can also have this buffer purging done for you, every day at
297 midnight, by enabling Midnight mode. Midnight mode operates each day at
298 midnight; at that time, it runs @code{clean-buffer-list}, or whichever
299 functions you have placed in the normal hook @code{midnight-hook}
302 To enable Midnight mode, use the Customization buffer to set the
303 variable @code{midnight-mode} to @code{t}. @xref{Easy Customization}.
305 @node Several Buffers
306 @section Operating on Several Buffers
309 The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
310 you to request operations on various Emacs buffers by editing an Emacs
311 buffer containing a list of them. You can save buffers, kill them
312 (here called @dfn{deleting} them, for consistency with Dired), or display
316 @item M-x buffer-menu
317 Begin editing a buffer listing all Emacs buffers.
321 The command @code{buffer-menu} writes a list of all Emacs buffers into
322 the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
323 mode. The buffer is read-only, and can be changed only through the
324 special commands described in this section. The usual Emacs cursor
325 motion commands can be used in the @samp{*Buffer List*} buffer. The
326 following commands apply to the buffer described on the current line.
330 Request to delete (kill) the buffer, then move down. The request
331 shows as a @samp{D} on the line, before the buffer name. Requested
332 deletions take place when you type the @kbd{x} command.
334 Like @kbd{d} but move up afterwards instead of down.
336 Request to save the buffer. The request shows as an @samp{S} on the
337 line. Requested saves take place when you type the @kbd{x} command.
338 You may request both saving and deletion for the same buffer.
340 Perform previously requested deletions and saves.
342 Remove any request made for the current line, and move down.
344 Move to previous line and remove any request made for that line.
347 The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
348 flags also move down (or up) one line. They accept a numeric argument
351 These commands operate immediately on the buffer listed on the current
356 Mark the buffer ``unmodified.'' The command @kbd{~} does this
357 immediately when you type it.
359 Toggle the buffer's read-only flag. The command @kbd{%} does
360 this immediately when you type it.
362 Visit the buffer as a tags table. @xref{Select Tags Table}.
365 There are also commands to select another buffer or buffers:
369 Quit the buffer menu---immediately display the most recent formerly
370 visible buffer in its place.
373 Immediately select this line's buffer in place of the @samp{*Buffer
376 Immediately select this line's buffer in another window as if by
377 @kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
379 Immediately display this line's buffer in another window, but don't
382 Immediately select this line's buffer in a full-screen window.
384 Immediately set up two windows, with this line's buffer in one, and the
385 previously selected buffer (aside from the buffer @samp{*Buffer List*})
388 Bury the buffer listed on this line.
390 Mark this line's buffer to be displayed in another window if you exit
391 with the @kbd{v} command. The request shows as a @samp{>} at the
392 beginning of the line. (A single buffer may not have both a delete
393 request and a display request.)
395 Immediately select this line's buffer, and also display in other windows
396 any buffers previously marked with the @kbd{m} command. If you have not
397 marked any buffers, this command is equivalent to @kbd{1}.
400 All that @code{buffer-menu} does directly is create and switch to a
401 suitable buffer, and turn on Buffer Menu mode. Everything else
402 described above is implemented by the special commands provided in
403 Buffer Menu mode. One consequence of this is that you can switch from
404 the @samp{*Buffer List*} buffer to another Emacs buffer, and edit there.
405 You can reselect the @samp{*Buffer List*} buffer later, to perform the
406 operations already requested, or you can kill it, or pay no further
409 The only difference between @code{buffer-menu} and @code{list-buffers}
410 is that @code{buffer-menu} switches to the @samp{*Buffer List*} buffer
411 in the selected window; @code{list-buffers} displays it in another
412 window. If you run @code{list-buffers} (that is, type @kbd{C-x C-b})
413 and select the buffer list manually, you can use all of the commands
416 The buffer @samp{*Buffer List*} is not updated automatically when
417 buffers are created and killed; its contents are just text. If you have
418 created, deleted or renamed buffers, the way to update @samp{*Buffer
419 List*} to show what you have done is to type @kbd{g}
420 (@code{revert-buffer}) or repeat the @code{buffer-menu} command.
422 @node Indirect Buffers
423 @section Indirect Buffers
424 @cindex indirect buffer
427 An @dfn{indirect buffer} shares the text of some other buffer, which
428 is called the @dfn{base buffer} of the indirect buffer. In some ways it
429 is the analogue, for buffers, of a symbolic link between files.
432 @findex make-indirect-buffer
433 @item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
434 Create an indirect buffer named @var{indirect-name} whose base buffer
435 is @var{base-buffer}.
436 @findex clone-indirect-buffer
437 @item M-x clone-indirect-buffer @key{RET}
438 Create an indirect buffer that is a twin copy of the current buffer.
441 @findex clone-indirect-buffer-other-window
442 Create an indirect buffer that is a twin copy of the current buffer, and
443 select it in another window (@code{clone-indirect-buffer-other-window}).
446 The text of the indirect buffer is always identical to the text of its
447 base buffer; changes made by editing either one are visible immediately
448 in the other. But in all other respects, the indirect buffer and its
449 base buffer are completely separate. They have different names,
450 different values of point, different narrowing, different markers,
451 different major modes, and different local variables.
453 An indirect buffer cannot visit a file, but its base buffer can. If
454 you try to save the indirect buffer, that actually works by saving the
455 base buffer. Killing the base buffer effectively kills the indirect
456 buffer, but killing an indirect buffer has no effect on its base buffer.
458 One way to use indirect buffers is to display multiple views of an
459 outline. @xref{Outline Views}.
461 @cindex multiple @samp{*info*} and @samp{*Help*} buffers
462 A quick and handy way to make an indirect buffer is with the command
463 @kbd{M-x clone-indirect-buffer}. It creates and selects an indirect
464 buffer whose base buffer is the current buffer. With a numeric
465 argument, it prompts for the name of the indirect buffer; otherwise it
466 defaults to the name of the current buffer, modifying it by adding a
467 @samp{<@var{n}>} prefix if required. @kbd{C-x 4 c}
468 (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x
469 clone-indirect-buffer}, but it selects the cloned buffer in another
470 window. These commands come in handy if you want to create new
471 @samp{*info*} or @samp{*Help*} buffers, for example.
473 The more general way is with the command @kbd{M-x
474 make-indirect-buffer}. It creates an indirect buffer from buffer
475 @var{base-buffer}, under the name @var{indirect-name}. It prompts for
476 both @var{base-buffer} and @var{indirect-name} using the minibuffer.
478 @node Buffer Convenience
479 @section Convenience Features and Customization of Buffer Handling
481 This section describes several modes and features that make it more
482 convenient to switch between buffers.
485 * Uniquify:: Buffer names can contain directory parts.
486 * Iswitchb:: Switching between buffers with substrings.
487 * Buffer Menus:: Configurable buffer menu.
491 @subsection Making Buffer Names Unique
493 @cindex unique buffer names
494 @cindex directories in buffer names
495 When several buffers visit identically-named files, Emacs must give
496 the buffers distinct names. The usual method for making buffer names
497 unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer
498 names (all but one of them).
500 @vindex uniquify-buffer-name-style
501 Other methods work by adding parts of each file's directory to the
502 buffer name. To select one, customize the variable
503 @code{uniquify-buffer-name-style} (@pxref{Easy Customization}).
505 For instance, the @code{forward} naming method puts part of the
506 directory name at the beginning of the buffer name; using this method,
507 buffers visiting @file{/u/mernst/tmp/Makefile} and
508 @file{/usr/projects/zaphod/Makefile} would be named
509 @samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead
510 of @samp{Makefile} and @samp{Makefile<2>}).
512 By contrast, the @code{post-forward} naming method would call the
513 buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the
514 @code{reverse} naming method would call them @samp{Makefile\tmp} and
515 @samp{Makefile\zaphod}. The nontrivial difference between
516 @code{post-forward} and @code{reverse} occurs when just one directory
517 name is not enough to distinguish two files; then @code{reverse} puts
518 the directory names in reverse order, so that @file{/top/middle/file}
519 becomes @samp{file\middle\top}, while @code{post-forward} puts them in
520 forward order after the file name, as in @samp{file|top/middle}.
522 Which rule to follow for putting the directory names in the buffer
523 name is not very important if you are going to @emph{look} at the
524 buffer names before you type one. But as an experienced user, if you
525 know the rule, you won't have to look. And then you may find that one
526 rule or another is easier for you to remember and utilize fast.
529 @subsection Switching Between Buffers using Substrings
531 @findex iswitchb-mode
532 @cindex Iswitchb mode
533 @cindex mode, Iswitchb
534 @kindex C-x b @r{(Iswitchb mode)}
535 @kindex C-x 4 b @r{(Iswitchb mode)}
536 @kindex C-x 5 b @r{(Iswitchb mode)}
537 @kindex C-x 4 C-o @r{(Iswitchb mode)}
539 Iswitchb global minor mode provides convenient switching between
540 buffers using substrings of their names. It replaces the normal
541 definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x
542 4 C-o} with alternative commands that are somewhat ``smarter.''
544 When one of these commands prompts you for a buffer name, you can
545 type in just a substring of the name you want to choose. As you enter
546 the substring, Iswitchb mode continuously displays a list of buffers
547 that match the substring you have typed.
549 At any time, you can type @key{RET} to select the first buffer in
550 the list. So the way to select a particular buffer is to make it the
551 first in the list. There are two ways to do this. You can type more
552 of the buffer name and thus narrow down the list, excluding unwanted
553 buffers above the desired one. Alternatively, you can use @kbd{C-s}
554 and @kbd{C-r} to rotate the list until the desired buffer is first.
556 @key{TAB} while entering the buffer name performs completion on the
557 string you have entered, based on the displayed list of buffers.
559 To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize
560 the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy
564 @subsection Customizing Buffer Menus
567 @cindex buffer list, customizable
570 Make a list of buffers similarly to @kbd{M-x list-buffers} but
574 @kbd{M-x bs-show} pops up a buffer list similar to the one normally
575 displayed by @kbd{C-x C-b} but which you can customize. If you prefer
576 this to the usual buffer list, you can bind this command to @kbd{C-x
577 C-b}. To customize this buffer list, use the @code{bs} Custom group
578 (@pxref{Easy Customization}).
584 @findex mouse-buffer-menu
585 @kindex C-Down-Mouse-1
586 MSB global minor mode (``MSB'' stands for ``mouse select buffer'')
587 provides a different and customizable mouse buffer menu which you may
588 prefer. It replaces the bindings of @code{mouse-buffer-menu},
589 normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You
590 can customize the menu in the @code{msb} Custom group.