Doc fixes.
[emacs.git] / man / buffers.texi
blob71dcde881dd5a661c6f8a48d1801cffea9d838f8
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
8 @cindex 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 a chosen buffer which
24 is displayed there, but at any time only one of the windows is selected and
25 its chosen buffer is the selected buffer.  Each window's mode line displays
26 the name of the buffer that the window is displaying (@pxref{Windows}).
28   Each buffer has a name, which can be of any length, and you can select
29 any buffer by giving its name.  Most buffers are made by visiting files,
30 and their names are derived from the files' names.  But you can also create
31 an empty buffer with any name you want.  A newly started Emacs has a buffer
32 named @samp{*scratch*} which can be used for evaluating Lisp expressions in
33 Emacs.  The distinction between upper and lower case matters in buffer
34 names.
36   Each buffer records individually what file it is visiting, whether it is
37 modified, and what major mode and minor modes are in effect in it
38 (@pxref{Major Modes}).  Any Emacs variable can be made @dfn{local to} a
39 particular buffer, meaning its value in that buffer can be different from
40 the value in other buffers.  @xref{Locals}.
42 @menu
43 * Select Buffer::       Creating a new buffer or reselecting an old one.
44 * List Buffers::        Getting a list of buffers that exist.
45 * Misc Buffer::         Renaming; changing read-onlyness; copying text.
46 * Kill Buffer::         Killing buffers you no longer need.
47 * Several Buffers::     How to go through the list of all buffers
48                           and operate variously on several of them.
49 * Indirect Buffers::    An indirect buffer shares the text of another buffer. 
50 * Buffer Convenience::  Convenience and customization features for
51                           buffer handling.
52 @end menu
54 @node Select Buffer
55 @section Creating and Selecting Buffers
56 @cindex change buffers
57 @cindex switch buffers
59 @table @kbd
60 @item C-x b @var{buffer} @key{RET}
61 Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
62 @item C-x 4 b @var{buffer} @key{RET}
63 Similar, but select @var{buffer} in another window
64 (@code{switch-to-buffer-other-window}).
65 @item C-x 5 b @var{buffer} @key{RET}
66 Similar, but select @var{buffer} in a separate frame
67 (@code{switch-to-buffer-other-frame}).
68 @end table
70 @kindex C-x 4 b
71 @findex switch-to-buffer-other-window
72 @kindex C-x 5 b
73 @findex switch-to-buffer-other-frame
74 @kindex C-x b
75 @findex switch-to-buffer
76   To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
77 @key{RET}}.  This runs the command @code{switch-to-buffer} with argument
78 @var{bufname}.  You can use completion on an abbreviation for the buffer
79 name you want (@pxref{Completion}).  An empty argument to @kbd{C-x b}
80 specifies the most recently selected buffer that is not displayed in any
81 window.@refill
83   Most buffers are created by visiting files, or by Emacs commands that
84 want to display some text, but you can also create a buffer explicitly
85 by typing @kbd{C-x b @var{bufname} @key{RET}}.  This makes a new, empty
86 buffer that is not visiting any file, and selects it for editing.  Such
87 buffers are used for making notes to yourself.  If you try to save one,
88 you are asked for the file name to use.  The new buffer's major mode is
89 determined by the value of @code{default-major-mode} (@pxref{Major
90 Modes}).
92   Note that @kbd{C-x C-f}, and any other command for visiting a file,
93 can also be used to switch to an existing file-visiting buffer.
94 @xref{Visiting}.
96   Emacs uses buffer names that start with a space for internal purposes.
97 It treats these buffers specially in minor ways---for example, by
98 default they do not record undo information.  It is best to avoid using
99 such buffer names yourself.
101 @node List Buffers
102 @section Listing Existing Buffers
104 @table @kbd
105 @item C-x C-b
106 List the existing buffers (@code{list-buffers}).
107 @end table
109 @cindex listing current buffers
110 @kindex C-x C-b
111 @findex list-buffers
112   To display a list of all the buffers that exist, type @kbd{C-x C-b}.
113 Each line in the list shows one buffer's name, major mode and visited
114 file.  The buffers are listed in the order that they were current; the
115 buffers that were current most recently come first.
117   @samp{*} at the beginning of a line indicates the buffer is ``modified.''
118 If several buffers are modified, it may be time to save some with @kbd{C-x s}
119 (@pxref{Saving}).  @samp{%} indicates a read-only buffer.  @samp{.} marks the
120 selected buffer.  Here is an example of a buffer list:@refill
122 @smallexample
123  MR Buffer         Size  Mode           File
124  -- ------         ----  ----           ----
125 .*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
126     *Help*         1287  Fundamental    
127     files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
128   % RMAIL          64042 RMAIL          /u/rms/RMAIL
129  *% man            747   Dired          /u2/emacs/man/          
130     net.emacs      343885 Fundamental   /u/rms/net.emacs
131     fileio.c       27691 C              /u2/emacs/src/fileio.c
132     NEWS           67340 Text           /u2/emacs/etc/NEWS
133     *scratch*      0     Lisp Interaction
134 @end smallexample
136 @noindent
137 Note that the buffer @samp{*Help*} was made by a help request; it is not
138 visiting any file.  The buffer @code{man} was made by Dired on the
139 directory @file{/u2/emacs/man/}.  You can list buffers visiting files
140 only by giving the command a prefix, i.e. type @kbd{C-u C-x C-b}.
142 @need 2000
143 @node Misc Buffer
144 @section Miscellaneous Buffer Operations
146 @table @kbd
147 @item C-x C-q
148 Toggle read-only status of buffer (@code{vc-toggle-read-only}).
149 @item M-x rename-buffer @key{RET} @var{name} @key{RET}
150 Change the name of the current buffer.
151 @item M-x rename-uniquely
152 Rename the current buffer by adding @samp{<@var{number}>} to the end.
153 @item M-x view-buffer @key{RET} @var{buffer} @key{RET}
154 Scroll through buffer @var{buffer}.
155 @end table
157 @kindex C-x C-q
158 @findex vc-toggle-read-only
159 @vindex buffer-read-only
160 @cindex read-only buffer
161   A buffer can be @dfn{read-only}, which means that commands to change
162 its contents are not allowed.  The mode line indicates read-only buffers
163 with @samp{%%} or @samp{%*} near the left margin.  Read-only buffers are
164 usually made by subsystems such as Dired and Rmail that have special
165 commands to operate on the text; also by visiting a file whose access
166 control says you cannot write it.  However, if the variable
167 @code{kill-read-only-ok} is set to a non-@code{nil} value, you can kill
168 (a.k.a.@: cut) read-only text, see @ref{Killing}.
170   If you wish to make changes in a read-only buffer, use the command
171 @kbd{C-x C-q} (@code{vc-toggle-read-only}).  It makes a read-only buffer
172 writable, and makes a writable buffer read-only.  In most cases, this
173 works by setting the variable @code{buffer-read-only}, which has a local
174 value in each buffer and makes the buffer read-only if its value is
175 non-@code{nil}.  If the file is maintained with version control,
176 @kbd{C-x C-q} works through the version control system to change the
177 read-only status of the file as well as the buffer.  @xref{Version
178 Control}.
180 @findex rename-buffer
181   @kbd{M-x rename-buffer} changes the name of the current buffer.  Specify
182 the new name as a minibuffer argument.  There is no default.  If you
183 specify a name that is in use for some other buffer, an error happens and
184 no renaming is done.
186   @kbd{M-x rename-uniquely} renames the current buffer to a similar name
187 with a numeric suffix added to make it both different and unique.  This
188 command does not need an argument.  It is useful for creating multiple
189 shell buffers: if you rename the @samp{*Shell*} buffer, then do @kbd{M-x
190 shell} again, it makes a new shell buffer named @samp{*Shell*};
191 meanwhile, the old shell buffer continues to exist under its new name.
192 This method is also good for mail buffers, compilation buffers, and most
193 Emacs features that create special buffers with particular names.
195 @findex view-buffer
196   @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
197 File Ops}) except that it examines an already existing Emacs buffer.
198 View mode provides commands for scrolling through the buffer
199 conveniently but not for changing it.  When you exit View mode with
200 @kbd{q}, that switches back to the buffer (and the position) which was
201 previously displayed in the window.  Alternatively, if you exit View
202 mode with @kbd{e}, the buffer and the value of point that resulted from
203 your perusal remain in effect.
205   The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
206 can be used to copy text from one buffer to another.  @xref{Accumulating
207 Text}.@refill
209 @node Kill Buffer
210 @section Killing Buffers
212 @cindex killing buffers
213   If you continue an Emacs session for a while, you may accumulate a
214 large number of buffers.  You may then find it convenient to @dfn{kill}
215 the buffers you no longer need.  On most operating systems, killing a
216 buffer releases its space back to the operating system so that other
217 programs can use it.  Here are some commands for killing buffers:
219 @c WideCommands
220 @table @kbd
221 @item C-x k @var{bufname} @key{RET}
222 Kill buffer @var{bufname} (@code{kill-buffer}).
223 @item M-x kill-some-buffers
224 Offer to kill each buffer, one by one.
225 @end table
227 @findex kill-buffer
228 @findex kill-some-buffers
229 @kindex C-x k
231   @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
232 specify in the minibuffer.  The default, used if you type just @key{RET}
233 in the minibuffer, is to kill the current buffer.  If you kill the
234 current buffer, another buffer is selected; one that has been selected
235 recently but does not appear in any window now.  If you ask to kill a
236 file-visiting buffer that is modified (has unsaved editing), then you
237 must confirm with @kbd{yes} before the buffer is killed.
239   The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
240 one.  An answer of @kbd{y} means to kill the buffer.  Killing the current
241 buffer or a buffer containing unsaved changes selects a new buffer or asks
242 for confirmation just like @code{kill-buffer}.
244   The buffer menu feature (@pxref{Several Buffers}) is also convenient
245 for killing various buffers.
247 @vindex kill-buffer-hook
248   If you want to do something special every time a buffer is killed, you
249 can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}).
251 @findex clean-buffer-list
252   If you run one Emacs session for a period of days, as many people do,
253 it can fill up with buffers that you used several days ago.  The command
254 @kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills
255 all the unmodified buffers that you have not used for a long time.  An
256 ordinary buffer is killed if it has not been displayed for three days;
257 however, you can specify certain buffers that should never be killed
258 automatically, and others that should be killed if they have been unused
259 for a mere hour.
261 @cindex Midnight mode
262 @vindex midnight-mode
263 @vindex midnight-hook
264   You can also have this buffer purging done for you, every day at
265 midnight, by enabling Midnight mode.  Midnight mode operates each day at
266 midnight; at that time, it runs @code{clean-buffer-list}, or whichever
267 functions you have placed in the normal hook @code{midnight-hook}
268 (@pxref{Hooks}).
270   To enable Midnight mode, use the Customization buffer to set the
271 variable @code{midnight-mode} to @code{t}.  @xref{Easy Customization}.
273 @node Several Buffers
274 @section Operating on Several Buffers
275 @cindex buffer menu
277   The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
278 you to request operations on various Emacs buffers by editing an Emacs
279 buffer containing a list of them.  You can save buffers, kill them
280 (here called @dfn{deleting} them, for consistency with Dired), or display
281 them.
283 @table @kbd
284 @item M-x buffer-menu
285 Begin editing a buffer listing all Emacs buffers.
286 @end table
288 @findex buffer-menu
289   The command @code{buffer-menu} writes a list of all Emacs buffers into
290 the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
291 mode.  The buffer is read-only, and can be changed only through the
292 special commands described in this section.  The usual Emacs cursor
293 motion commands can be used in the @samp{*Buffer List*} buffer.  The
294 following commands apply to the buffer described on the current line.
296 @table @kbd
297 @item d
298 Request to delete (kill) the buffer, then move down.  The request
299 shows as a @samp{D} on the line, before the buffer name.  Requested
300 deletions take place when you type the @kbd{x} command.
301 @item C-d
302 Like @kbd{d} but move up afterwards instead of down.
303 @item s
304 Request to save the buffer.  The request shows as an @samp{S} on the
305 line.  Requested saves take place when you type the @kbd{x} command.
306 You may request both saving and deletion for the same buffer.
307 @item x
308 Perform previously requested deletions and saves.
309 @item u
310 Remove any request made for the current line, and move down.
311 @item @key{DEL}
312 Move to previous line and remove any request made for that line.
313 @end table
315   The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
316 flags also move down (or up) one line.  They accept a numeric argument
317 as a repeat count.
319   These commands operate immediately on the buffer listed on the current
320 line:
322 @table @kbd
323 @item ~
324 Mark the buffer ``unmodified.''  The command @kbd{~} does this
325 immediately when you type it.
326 @item %
327 Toggle the buffer's read-only flag.  The command @kbd{%} does
328 this immediately when you type it.
329 @item t
330 Visit the buffer as a tags table.  @xref{Select Tags Table}.
331 @end table
333   There are also commands to select another buffer or buffers:
335 @table @kbd
336 @item q
337 Quit the buffer menu---immediately display the most recent formerly
338 visible buffer in its place.
339 @item @key{RET}
340 @itemx f
341 Immediately select this line's buffer in place of the @samp{*Buffer
342 List*} buffer.
343 @item o
344 Immediately select this line's buffer in another window as if by
345 @kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
346 @item C-o
347 Immediately display this line's buffer in another window, but don't
348 select the window.
349 @item 1
350 Immediately select this line's buffer in a full-screen window.
351 @item 2
352 Immediately set up two windows, with this line's buffer in one, and the
353 previously selected buffer (aside from the buffer @samp{*Buffer List*})
354 in the other.
355 @item b
356 Bury the buffer listed on this line.
357 @item m
358 Mark this line's buffer to be displayed in another window if you exit
359 with the @kbd{v} command.  The request shows as a @samp{>} at the
360 beginning of the line.  (A single buffer may not have both a delete
361 request and a display request.)
362 @item v
363 Immediately select this line's buffer, and also display in other windows
364 any buffers previously marked with the @kbd{m} command.  If you have not
365 marked any buffers, this command is equivalent to @kbd{1}.
366 @end table
368   All that @code{buffer-menu} does directly is create and switch to a
369 suitable buffer, and turn on Buffer Menu mode.  Everything else
370 described above is implemented by the special commands provided in
371 Buffer Menu mode.  One consequence of this is that you can switch from
372 the @samp{*Buffer List*} buffer to another Emacs buffer, and edit there.
373 You can reselect the @samp{*Buffer List*} buffer later, to perform the
374 operations already requested, or you can kill it, or pay no further
375 attention to it.
377   The only difference between @code{buffer-menu} and @code{list-buffers}
378 is that @code{buffer-menu} switches to the @samp{*Buffer List*} buffer
379 in the selected window; @code{list-buffers} displays it in another
380 window.  If you run @code{list-buffers} (that is, type @kbd{C-x C-b})
381 and select the buffer list manually, you can use all of the commands
382 described here.
384   The buffer @samp{*Buffer List*} is not updated automatically when
385 buffers are created and killed; its contents are just text.  If you have
386 created, deleted or renamed buffers, the way to update @samp{*Buffer
387 List*} to show what you have done is to type @kbd{g}
388 (@code{revert-buffer}) or repeat the @code{buffer-menu} command.
390 @node Indirect Buffers
391 @section Indirect Buffers
392 @cindex indirect buffer
393 @cindex base buffer
395   An @dfn{indirect buffer} shares the text of some other buffer, which
396 is called the @dfn{base buffer} of the indirect buffer.  In some ways it
397 is the analogue, for buffers, of a symbolic link between files.
399 @table @kbd
400 @findex make-indirect-buffer
401 @item M-x make-indirect-buffer @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
402 Create an indirect buffer named @var{indirect-name} whose base buffer
403 is @var{base-buffer}.
404 @findex clone-indirect-buffer
405 @item M-x clone-indirect-buffer @key{RET}
406 Create an indirect buffer that is a twin copy of the current buffer.
407 @kindex C-x 4 c
408 @findex clone-indirect-buffer-other-window
409 Create an indirect buffer that is a twin copy of the current buffer, and
410 select it in another window (@code{clone-indirect-buffer-other-window}).
411 @end table
413   The text of the indirect buffer is always identical to the text of its
414 base buffer; changes made by editing either one are visible immediately
415 in the other.  But in all other respects, the indirect buffer and its
416 base buffer are completely separate.  They have different names,
417 different values of point, different narrowing, different markers,
418 different major modes, and different local variables.
420   An indirect buffer cannot visit a file, but its base buffer can.  If
421 you try to save the indirect buffer, that actually works by saving the
422 base buffer.  Killing the base buffer effectively kills the indirect
423 buffer, but killing an indirect buffer has no effect on its base buffer.
425   One way to use indirect buffers is to display multiple views of an
426 outline.  @xref{Outline Views}.
428   The command @kbd{M-x make-indirect-buffer} creates an indirect buffer
429 whose name is @var{indirect-name} and whose text is identical to that of
430 the buffer @var{base-buffer}.  It prompts for both @var{base-buffer} and
431 @var{indirect-name}.
433 @cindex multiple @samp{*info*} and @samp{*Help*} buffers
434   The command @kbd{M-x clone-indirect-buffer} creates an indirect buffer
435 whose base buffer is the current buffer, and also selects the
436 newly-created indirect buffer.  With a numeric argument, it prompts for
437 the name of the indirect buffer; otherwise it defaults to the name of
438 the current buffer, modifying it by adding a @samp{<@var{n}>} prefix if
439 required.  @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window})
440 works like @kbd{M-x clone-indirect-buffer}, but it selects the cloned
441 buffer in another window.  These commands come in handy if you want to
442 create new @samp{*info*} or @samp{*Help*} buffers, for example.
444 @node Buffer Convenience
445 @section Convenience Features and Customization of Buffer Handling
447 @menu
448 * Uniquify::               Buffer names can contain directory parts.
449 * Iswitchb::               Switching between buffers with substrings.
450 * BS::                     Configurable buffer menu.     
451 * MSB::                    Customizing the Mouse Buffer Selection Menus.
452 @end menu
454 @node Uniquify
455 @subsection Directory Names in Buffer Names
457 @findex toggle-uniquify-buffer-names
458 @vindex uniquify-buffer-name-style
459 @cindex unique buffer names
460 @cindex directories in buffer names
461 Emacs's standard method for making buffer names unique adds @samp{<2>},
462 @samp{<3>}, etc. to the end of (all but one of) the buffers.  The
463 Uniquify package replaces that behavior, for buffers visiting files and
464 dired buffers.  It implements a uniquification that adds parts of the
465 file name until the buffer names are unique.  For instance, buffers
466 visiting @file{/u/mernst/tmp/Makefile} and
467 @file{/usr/projects/zaphod/Makefile} would be named @samp{tmp/Makefile}
468 and @samp{zaphod/Makefile}, respectively (instead of @samp{Makefile}
469 and @samp{Makefile<2>}).  You can turn on this mode and select other
470 buffer name styles by customizing the user option
471 @code{uniquify-buffer-name-style}.  The command @kbd{M-x
472 toggle-uniquify-buffer-names} can also be used to toggle the mode.  
474 @node Iswitchb
475 @subsection Switching Between Buffers using Substrings
477 @findex iswitchb-mode
478 @cindex Iswitchb mode
479 @cindex mode, Iswitchb
480 @kindex C-x b @r{(Iswitchb mode)}
481 @kindex C-x 4 b @r{(Iswitchb mode)}
482 @kindex C-x 5 b @r{(Iswitchb mode)}
483 @kindex C-x 4 C-o @r{(Iswitchb mode)}
485 Iswitchb global minor mode provides convenient switching between buffers
486 using substrings of their names by replacing the normal keybindings
487 @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b} and @kbd{C-x 4 C-o}.
489 When you are prompted for a buffer name, as you type in a substring the
490 list of buffers currently matching it is displayed as you type, with the
491 most recent buffers visited towards the start of the list.  The buffer
492 at the start will be the one visited when you press @key{RET}.  By
493 typing more of the substring, the list is narrowed down so that
494 gradually the buffer you want will be at the top of the list.
495 Alternatively, you can use @kbd{C-s} and @kbd{C-r} to rotate buffer
496 names in the list until the one you want is at the top of the list.
497 Completion is available so that you can see what is common to all of the
498 matching buffers as you type.
500 @node BS
501 @subsection Configurable Buffer Menus
503 @findex bs-show
504 @findex bs-cycle-next
505 @findex bs-cycle-previous
506 @cindex buffer list, customizable
507 @table @kbd
508 @item M-x bs-show
509 Make a list of buffers similarly to @kbd{M-x list-buffers} but
510 customizable.
511 @item M-x bs-cycle-next
512 Cycle to the next buffer in the configuration.
513 @item M-x bs-cycle-previous
514 Cycle to the previous buffer in the configuration.
515 @end table
517 @kbd{M-x bs-show} pops up a buffer list similar to the one normally
518 displayed by @kbd{C-x C-b} but which can be customized.  You might like
519 to bind it to @kbd{C-x C-b}.  You can customize the display, for
520 instance to display a subset of buffers, in the @code{bs} Custom group.
521 A special subset of all buffers is available---for instance avoiding
522 ones like @samp{*Messages*}---through which you can cycle with @kbd{M-x
523 bs-cycle-next} and @kbd{M-x bs-cycle-previous}.  Those commands could be
524 bound to convenient keys.
526 @node MSB
527 @subsection Customizing the Mouse Buffer Selection Menus
529 @findex msb-mode
530 @cindex mode, MSB
531 @cindex MSB mode
532 @cindex buffer menu
533 @findex mouse-buffer-menu
534 @kindex C-down-mouse-1
536 MSB global minor mode provides a different and customizable mouse buffer
537 menu which you may prefer.  It replaces the bindings of
538 @code{mouse-buffer-menu}, normally on @kbd{C-down-mouse-1}, and the menu
539 bar buffer menu.  You can customize the menu in the @code{msb} Custom
540 group.