Window-related updates to NEWS and Emacs manual.
[bpt/emacs.git] / doc / emacs / buffers.texi
CommitLineData
6bf7aab6 1@c This is part of the Emacs manual.
73b0cd50 2@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
8838673e 3@c Free Software Foundation, Inc.
6bf7aab6
DL
4@c See file emacs.texi for copying conditions.
5@node Buffers, Windows, Files, Top
6@chapter Using Multiple Buffers
7
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
11file's text. Each time you invoke Dired, a buffer is created to hold the
12directory 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
14command's documentation, that appears in a buffer called @samp{*Help*}.
15
ea146ed8
CY
16 Each buffer has a unique name, which can be of any length. When a
17buffer is displayed in a window, its name is shown in the mode line
18(@pxref{Mode Line}). The distinction between upper and lower case
19matters in buffer names. Most buffers are made by visiting files, and
20their names are derived from the files' names; however, you can also
21create an empty buffer with any name you want. A newly started Emacs
22has a buffer named @samp{*scratch*}, which is not associated with any
23file and can be used for evaluating Lisp expressions in Emacs
24(@pxref{Lisp Interaction}).
25
6bf7aab6
DL
26@cindex selected buffer
27@cindex current buffer
ea146ed8
CY
28 At any time, one and only one buffer is @dfn{current}. This is also
29called the @dfn{selected buffer}. We often say that a command
30operates on ``the buffer''; this really means that the command
31operates on the current buffer (most commands do). When there is only
32one Emacs window, the buffer displayed in that window is current.
33When there are multiple windows present, the buffer displayed in the
34@dfn{selected window} is current. @xref{Windows}.
35
36 Each buffer records individually what file it is visiting (if any),
37whether it is modified, and what major mode and minor modes are in
38effect (@pxref{Major Modes}). Any Emacs variable can be made
39@dfn{local to} a particular buffer, meaning its value in that buffer
40can be different from the value in other buffers. @xref{Locals}.
6bf7aab6 41
dc53c88b
EZ
42@cindex buffer size, maximum
43 A buffer's size cannot be larger than some maximum, which is defined
91ed7ea8
CY
44by the largest buffer position representable by the @dfn{Emacs
45integer} data type. This is because Emacs tracks buffer positions
001903b5 46using that data type. For typical 64-bit machines, the maximum buffer size
b047e7ac 47enforced by the data types is @math{2^61 - 2} bytes, or about 2 EiB.
001903b5 48For typical 32-bit machines, the maximum is @math{2^29 - 2} bytes, or
b047e7ac
PE
49about 512 MiB. Buffer sizes are also limited by the size of Emacs's
50virtual memory.
dc53c88b 51
6bf7aab6
DL
52@menu
53* Select Buffer:: Creating a new buffer or reselecting an old one.
54* List Buffers:: Getting a list of buffers that exist.
8838673e
GM
55* Misc Buffer:: Renaming; changing read-onlyness; copying text.
56* Kill Buffer:: Killing buffers you no longer need.
6bf7aab6 57* Several Buffers:: How to go through the list of all buffers
8838673e 58 and operate variously on several of them.
177c0ea7 59* Indirect Buffers:: An indirect buffer shares the text of another buffer.
b54346bc
DL
60* Buffer Convenience:: Convenience and customization features for
61 buffer handling.
6bf7aab6
DL
62@end menu
63
64@node Select Buffer
65@section Creating and Selecting Buffers
66@cindex change buffers
67@cindex switch buffers
68
69@table @kbd
70@item C-x b @var{buffer} @key{RET}
71Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
72@item C-x 4 b @var{buffer} @key{RET}
73Similar, but select @var{buffer} in another window
74(@code{switch-to-buffer-other-window}).
75@item C-x 5 b @var{buffer} @key{RET}
76Similar, but select @var{buffer} in a separate frame
77(@code{switch-to-buffer-other-frame}).
160bde9c
LT
78@item C-x @key{LEFT}
79Select the previous buffer in the list of existing buffers.
80@item C-x @key{RIGHT}
81Select the next buffer in the list of existing buffers.
ac2c0786
LT
82@item C-u M-g M-g
83@itemx C-u M-g g
84Read a number @var{n} and move to line @var{n} in the most recently
85selected buffer other than the current buffer.
6bf7aab6
DL
86@end table
87
6bf7aab6
DL
88@kindex C-x b
89@findex switch-to-buffer
ea146ed8
CY
90 To select the buffer named @var{bufname}, type @kbd{C-x b
91@var{bufname} @key{RET}}. This runs the command
92@code{switch-to-buffer} with argument @var{bufname}. While entering
93the buffer name, you can use the usual minibuffer completion and
0a2132ba
CY
94history commands (@pxref{Minibuffer}). An empty input specifies the
95buffer that was current most recently among those not now displayed in
96any window.
6bf7aab6 97
2f4f09a9
CY
98@cindex minibuffer confirmation
99@cindex confirming in the minibuffer
ea146ed8
CY
100 If you specify a buffer that does not exist, @kbd{C-x b} creates a
101new, empty buffer that is not visiting any file, and selects it for
2f4f09a9
CY
102editing. First, however, Emacs might prompt you for confirmation, in
103case you entered the wrong buffer name. Emacs asks for confirmation
104only if the last key you typed, before submitting the minibuffer input
105with @key{RET}, was @key{TAB} (@code{minibuffer-complete}). This
106catches a common mistake, in which one types @key{RET} before
107realizing that @key{TAB} did not complete far enough to yield the
108desired buffer name (@pxref{Completion}). Emacs asks for confirmation
109by putting the message @samp{[Confirm]} in the minibuffer; type
0a2132ba
CY
110@key{RET} again to confirm and visit the buffer. @xref{Visiting}, for
111information about modifying this behavior.
2f4f09a9 112
b01731eb
CY
113 One reason to create a new buffer is to use it for making temporary
114notes. If you try to save it, Emacs asks for the file name to use.
4e3b4528
SM
115The default value of the variable @code{major-mode} determines the new
116buffer's major mode; the default value is Fundamental mode. @xref{Major
b01731eb 117Modes}.
ea146ed8 118
7354ca01
RS
119@kindex C-x @key{LEFT}
120@kindex C-x @key{RIGHT}
121@findex next-buffer
a3700ef7 122@findex previous-buffer
7354ca01
RS
123 For conveniently switching between a few buffers, use the commands
124@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{RIGHT}}
a3700ef7
KL
125(@code{previous-buffer}) selects the previous buffer (following the order
126of most recent selection in the current frame), while @kbd{C-x @key{LEFT}}
7354ca01
RS
127(@code{next-buffer}) moves through buffers in the reverse direction.
128
8f7cad1f
EZ
129@kindex C-x 4 b
130@findex switch-to-buffer-other-window
8f7cad1f 131 To select a buffer in a window other than the current one, type
ea146ed8
CY
132@kbd{C-x 4 b} (@code{switch-to-buffer-other-window}). This prompts
133for a buffer name using the minibuffer, displays that buffer in
0a2132ba 134another window, and selects that window.
8f7cad1f
EZ
135
136@kindex C-x 5 b
137@findex switch-to-buffer-other-frame
ea146ed8
CY
138 Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame})
139prompts for a buffer name, displays that buffer in another frame, and
0a2132ba
CY
140selects that frame. If the buffer is already being shown in a window
141on another frame, Emacs selects that window and frame instead of
142creating a new frame.
143
144 @xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5
145b} commands get the window and/or frame to display in.
ea146ed8
CY
146
147 In addition, @kbd{C-x C-f}, and any other command for visiting a
148file, can also be used to switch to an existing file-visiting buffer.
149@xref{Visiting}.
8f7cad1f 150
dd186936 151@findex goto-line
ea146ed8
CY
152 @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix
153argument, reads a number @var{n} using the minibuffer, selects the
154most recently selected buffer other than the current buffer in another
155window, and then moves point to the beginning of line number @var{n}
156in that buffer. This is mainly useful in a buffer that refers to line
157numbers in another buffer: if point is on or just after a number,
158@code{goto-line} uses that number as the default for @var{n}. Note
159that prefix arguments other than just @kbd{C-u} behave differently.
160@kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current} buffer,
161without reading a number from the minibuffer. (Remember that @kbd{M-g
162M-g} without prefix argument reads a number @var{n} and then moves to
163line number @var{n} in the current buffer. @xref{Moving Point}.)
ac2c0786 164
6bf7aab6
DL
165 Emacs uses buffer names that start with a space for internal purposes.
166It treats these buffers specially in minor ways---for example, by
167default they do not record undo information. It is best to avoid using
168such buffer names yourself.
169
170@node List Buffers
171@section Listing Existing Buffers
172
173@table @kbd
174@item C-x C-b
175List the existing buffers (@code{list-buffers}).
176@end table
177
178@cindex listing current buffers
179@kindex C-x C-b
180@findex list-buffers
7354ca01
RS
181 To display a list of existing buffers, type @kbd{C-x C-b}. Each
182line in the list shows one buffer's name, major mode and visited file.
183The buffers are listed in the order that they were current; the
6bf7aab6
DL
184buffers that were current most recently come first.
185
ea146ed8
CY
186 @samp{.} in the first field of a line indicates that the buffer is
187current. @samp{%} indicates a read-only buffer. @samp{*} indicates
188that the buffer is ``modified.'' If several buffers are modified, it
189may be time to save some with @kbd{C-x s} (@pxref{Save Commands}).
190Here is an example of a buffer list:
6bf7aab6
DL
191
192@smallexample
b1a25f96 193CRM Buffer Size Mode File
6105130d
MR
194. * .emacs 3294 Emacs-Lisp ~/.emacs
195 % *Help* 101 Help
517b2c37
JB
196 search.c 86055 C ~/cvs/emacs/src/search.c
197 % src 20959 Dired by name ~/cvs/emacs/src/
6105130d 198 * *mail* 42 Mail
517b2c37
JB
199 % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO
200 % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS
201 *scratch* 191 Lisp Interaction
517b2c37 202 * *Messages* 1554 Fundamental
6bf7aab6
DL
203@end smallexample
204
205@noindent
ea146ed8
CY
206The buffer @samp{*Help*} was made by a help request (@pxref{Help}); it
207is not visiting any file. The buffer @code{src} was made by Dired on
208the directory @file{~/cvs/emacs/src/}. You can list only buffers that
209are visiting files by giving the command a prefix argument, as in
564ee37b 210@kbd{C-u C-x C-b}.
6bf7aab6 211
7354ca01 212 @code{list-buffers} omits buffers whose names begin with a space,
4081af2f
EZ
213unless they visit files: such buffers are used internally by Emacs.
214
6bf7aab6
DL
215@node Misc Buffer
216@section Miscellaneous Buffer Operations
217
218@table @kbd
219@item C-x C-q
8f980b27 220Toggle read-only status of buffer (@code{toggle-read-only}).
6bf7aab6
DL
221@item M-x rename-buffer @key{RET} @var{name} @key{RET}
222Change the name of the current buffer.
223@item M-x rename-uniquely
224Rename the current buffer by adding @samp{<@var{number}>} to the end.
225@item M-x view-buffer @key{RET} @var{buffer} @key{RET}
226Scroll through buffer @var{buffer}.
227@end table
228
229@kindex C-x C-q
6bf7aab6
DL
230@vindex buffer-read-only
231@cindex read-only buffer
232 A buffer can be @dfn{read-only}, which means that commands to change
564ee37b
RS
233its contents are not allowed. The mode line indicates read-only
234buffers with @samp{%%} or @samp{%*} near the left margin. Read-only
235buffers are usually made by subsystems such as Dired and Rmail that
236have special commands to operate on the text; also by visiting a file
237whose access control says you cannot write it.
6bf7aab6 238
8f980b27 239@findex toggle-read-only
6bf7aab6 240 If you wish to make changes in a read-only buffer, use the command
8f980b27
AS
241@kbd{C-x C-q} (@code{toggle-read-only}). It makes a read-only buffer
242writable, and makes a writable buffer read-only. This
6bf7aab6
DL
243works by setting the variable @code{buffer-read-only}, which has a local
244value in each buffer and makes the buffer read-only if its value is
8f980b27
AS
245non-@code{nil}. If you have files under version control, you may find
246it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only}
a31b405e
ER
247instead. This will guard you against an operation that will confuse
248most modern version-conmtrol systems. @xref{Version Control}.
6bf7aab6
DL
249
250@findex rename-buffer
a3053e27
RS
251 @kbd{M-x rename-buffer} changes the name of the current buffer. You
252specify the new name as a minibuffer argument; there is no default.
253If you specify a name that is in use for some other buffer, an error
254happens and no renaming is done.
6bf7aab6 255
0e04ec0b 256@findex rename-uniquely
eddcfd0e
RS
257 @kbd{M-x rename-uniquely} renames the current buffer to a similar
258name with a numeric suffix added to make it both different and unique.
259This command does not need an argument. It is useful for creating
158a07a8 260multiple shell buffers: if you rename the @samp{*shell*} buffer, then
eddcfd0e 261do @kbd{M-x shell} again, it makes a new shell buffer named
158a07a8 262@samp{*shell*}; meanwhile, the old shell buffer continues to exist
eddcfd0e
RS
263under its new name. This method is also good for mail buffers,
264compilation buffers, and most Emacs features that create special
265buffers with particular names. (With some of these features, such as
266@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to
267switch to some other buffer before using the command, in order for it
268to make a different buffer.)
6bf7aab6 269
6bf7aab6
DL
270 The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
271can be used to copy text from one buffer to another. @xref{Accumulating
a3053e27 272Text}.
6bf7aab6
DL
273
274@node Kill Buffer
275@section Killing Buffers
276
277@cindex killing buffers
278 If you continue an Emacs session for a while, you may accumulate a
279large number of buffers. You may then find it convenient to @dfn{kill}
280the buffers you no longer need. On most operating systems, killing a
281buffer releases its space back to the operating system so that other
282programs can use it. Here are some commands for killing buffers:
283
6bf7aab6
DL
284@table @kbd
285@item C-x k @var{bufname} @key{RET}
286Kill buffer @var{bufname} (@code{kill-buffer}).
287@item M-x kill-some-buffers
288Offer to kill each buffer, one by one.
ea146ed8
CY
289@item M-x kill-matching-buffers
290Offer to kill all buffers matching a regular expression.
6bf7aab6
DL
291@end table
292
293@findex kill-buffer
6bf7aab6 294@kindex C-x k
6bf7aab6 295 @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
ab25a0c7
RS
296specify in the minibuffer. The default, used if you type just
297@key{RET} in the minibuffer, is to kill the current buffer. If you
298kill the current buffer, another buffer becomes current: one that was
299current in the recent past but is not displayed in any window now. If
ea146ed8
CY
300you ask to kill a file-visiting buffer that is modified, then you must
301confirm with @kbd{yes} before the buffer is killed.
6bf7aab6 302
ea146ed8
CY
303@findex kill-some-buffers
304 The command @kbd{M-x kill-some-buffers} asks about each buffer, one
305by one. An answer of @kbd{y} means to kill the buffer, just like
306@code{kill-buffer}. This command ignores buffers whose names begin
307with a space, which are used internally by Emacs.
308
309@findex kill-matching-buffers
310 The command @kbd{M-x kill-matching-buffers} prompts for a regular
311expression and kills all buffers whose names match that expression.
312@xref{Regexps}. Like @code{kill-some-buffers}, it asks for
313confirmation before each kill. This command normally ignores buffers
314whose names begin with a space, which are used internally by Emacs.
315To kill internal buffers as well, call @code{kill-matching-buffers}
316with a prefix argument.
317
318 The buffer menu feature is also convenient for killing various
319buffers. @xref{Several Buffers}.
6bf7aab6
DL
320
321@vindex kill-buffer-hook
322 If you want to do something special every time a buffer is killed, you
323can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}).
324
325@findex clean-buffer-list
326 If you run one Emacs session for a period of days, as many people do,
327it can fill up with buffers that you used several days ago. The command
328@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills
329all the unmodified buffers that you have not used for a long time. An
330ordinary buffer is killed if it has not been displayed for three days;
331however, you can specify certain buffers that should never be killed
332automatically, and others that should be killed if they have been unused
333for a mere hour.
334
335@cindex Midnight mode
336@vindex midnight-mode
337@vindex midnight-hook
338 You can also have this buffer purging done for you, every day at
ea146ed8
CY
339midnight, by enabling Midnight mode. Midnight mode operates each day
340at midnight; at that time, it runs @code{clean-buffer-list}, or
341whichever functions you have placed in the normal hook
342@code{midnight-hook} (@pxref{Hooks}). To enable Midnight mode, use
343the Customization buffer to set the variable @code{midnight-mode} to
344@code{t}. @xref{Easy Customization}.
6bf7aab6
DL
345
346@node Several Buffers
347@section Operating on Several Buffers
348@cindex buffer menu
349
6bf7aab6
DL
350@table @kbd
351@item M-x buffer-menu
352Begin editing a buffer listing all Emacs buffers.
4081af2f
EZ
353@item M-x buffer-menu-other-window.
354Similar, but do it in another window.
6bf7aab6
DL
355@end table
356
ea146ed8
CY
357 The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
358does not merely list buffers. It also allows you to perform various
359operations on buffers, through an interface similar to Dired
360(@pxref{Dired}). You can save buffers, kill them (here called
361@dfn{deleting} them, for consistency with Dired), or display them.
362
6bf7aab6 363@findex buffer-menu
4081af2f 364@findex buffer-menu-other-window
ea146ed8
CY
365 To use the buffer menu, type @kbd{C-x C-b} and switch to the window
366displaying the @samp{*Buffer List*} buffer. You can also type
367@kbd{M-x buffer-menu} to open the buffer menu in the selected window.
368Alternatively, the command @kbd{M-x buffer-menu-other-window} opens
369the buffer menu in another window, and selects that window.
370
371 The buffer menu is a read-only buffer, and can be changed only
372through the special commands described in this section. The usual
373Emacs cursor motion commands can be used in this buffer. The
374following commands apply to the buffer described on the current line:
6bf7aab6
DL
375
376@table @kbd
377@item d
378Request to delete (kill) the buffer, then move down. The request
379shows as a @samp{D} on the line, before the buffer name. Requested
380deletions take place when you type the @kbd{x} command.
381@item C-d
382Like @kbd{d} but move up afterwards instead of down.
383@item s
384Request to save the buffer. The request shows as an @samp{S} on the
385line. Requested saves take place when you type the @kbd{x} command.
386You may request both saving and deletion for the same buffer.
387@item x
388Perform previously requested deletions and saves.
389@item u
390Remove any request made for the current line, and move down.
391@item @key{DEL}
392Move to previous line and remove any request made for that line.
393@end table
394
395 The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
396flags also move down (or up) one line. They accept a numeric argument
397as a repeat count.
398
399 These commands operate immediately on the buffer listed on the current
400line:
401
402@table @kbd
403@item ~
404Mark the buffer ``unmodified.'' The command @kbd{~} does this
405immediately when you type it.
406@item %
407Toggle the buffer's read-only flag. The command @kbd{%} does
408this immediately when you type it.
409@item t
410Visit the buffer as a tags table. @xref{Select Tags Table}.
411@end table
412
413 There are also commands to select another buffer or buffers:
414
415@table @kbd
416@item q
417Quit the buffer menu---immediately display the most recent formerly
418visible buffer in its place.
419@item @key{RET}
420@itemx f
421Immediately select this line's buffer in place of the @samp{*Buffer
422List*} buffer.
423@item o
424Immediately select this line's buffer in another window as if by
425@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
426@item C-o
427Immediately display this line's buffer in another window, but don't
428select the window.
429@item 1
430Immediately select this line's buffer in a full-screen window.
431@item 2
041aabd8
LT
432Immediately set up two windows, with this line's buffer selected in
433one, and the previously current buffer (aside from the buffer
434@samp{*Buffer List*}) displayed in the other.
6bf7aab6
DL
435@item b
436Bury the buffer listed on this line.
437@item m
438Mark this line's buffer to be displayed in another window if you exit
439with the @kbd{v} command. The request shows as a @samp{>} at the
440beginning of the line. (A single buffer may not have both a delete
441request and a display request.)
442@item v
443Immediately select this line's buffer, and also display in other windows
444any buffers previously marked with the @kbd{m} command. If you have not
445marked any buffers, this command is equivalent to @kbd{1}.
446@end table
447
7354ca01
RS
448 There is also a command that affects the entire buffer list:
449
450@table @kbd
451@item T
452Delete, or reinsert, lines for non-file buffers. This command toggles
453the inclusion of such buffers in the buffer list.
454@end table
455
456 What @code{buffer-menu} actually does is create and switch to a
457suitable buffer, and turn on Buffer Menu mode in it. Everything else
6bf7aab6
DL
458described above is implemented by the special commands provided in
459Buffer Menu mode. One consequence of this is that you can switch from
7354ca01
RS
460the @samp{*Buffer List*} buffer to another Emacs buffer, and edit
461there. You can reselect the @samp{*Buffer List*} buffer later, to
462perform the operations already requested, or you can kill it, or pay
463no further attention to it.
464
a3053e27
RS
465 Normally, the buffer @samp{*Buffer List*} is not updated
466automatically when buffers are created and killed; its contents are
467just text. If you have created, deleted or renamed buffers, the way
468to update @samp{*Buffer List*} to show what you have done is to type
469@kbd{g} (@code{revert-buffer}). You can make this happen regularly
470every @code{auto-revert-interval} seconds if you enable Auto Revert
471mode in this buffer, as long as it is not marked modified. Global
472Auto Revert mode applies to the @samp{*Buffer List*} buffer only if
473@code{global-auto-revert-non-file-buffers} is non-@code{nil}.
bbe9cbb8 474@iftex
eca2d6cd 475@inforef{Autorevert,, emacs-xtra}, for details.
bbe9cbb8
EZ
476@end iftex
477@ifnottex
478@xref{Autorevert, global-auto-revert-non-file-buffers}, for details.
479@end ifnottex
480
6bf7aab6
DL
481@node Indirect Buffers
482@section Indirect Buffers
483@cindex indirect buffer
484@cindex base buffer
485
486 An @dfn{indirect buffer} shares the text of some other buffer, which
487is called the @dfn{base buffer} of the indirect buffer. In some ways it
488is the analogue, for buffers, of a symbolic link between files.
489
490@table @kbd
491@findex make-indirect-buffer
52ec6cdc 492@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
6bf7aab6
DL
493Create an indirect buffer named @var{indirect-name} whose base buffer
494is @var{base-buffer}.
f16874ce
EZ
495@findex clone-indirect-buffer
496@item M-x clone-indirect-buffer @key{RET}
497Create an indirect buffer that is a twin copy of the current buffer.
112c140f 498@item C-x 4 c
f16874ce
EZ
499@kindex C-x 4 c
500@findex clone-indirect-buffer-other-window
501Create an indirect buffer that is a twin copy of the current buffer, and
502select it in another window (@code{clone-indirect-buffer-other-window}).
6bf7aab6
DL
503@end table
504
505 The text of the indirect buffer is always identical to the text of its
506base buffer; changes made by editing either one are visible immediately
507in the other. But in all other respects, the indirect buffer and its
ea146ed8 508base buffer are completely separate. They can have different names,
6bf7aab6
DL
509different values of point, different narrowing, different markers,
510different major modes, and different local variables.
511
512 An indirect buffer cannot visit a file, but its base buffer can. If
513you try to save the indirect buffer, that actually works by saving the
514base buffer. Killing the base buffer effectively kills the indirect
515buffer, but killing an indirect buffer has no effect on its base buffer.
516
517 One way to use indirect buffers is to display multiple views of an
518outline. @xref{Outline Views}.
b54346bc 519
ea146ed8 520@vindex clone-indirect-buffer-hook
564ee37b
RS
521 A quick and handy way to make an indirect buffer is with the command
522@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect
523buffer whose base buffer is the current buffer. With a numeric
524argument, it prompts for the name of the indirect buffer; otherwise it
160bde9c
LT
525uses the name of the current buffer, with a @samp{<@var{n}>} suffix
526added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window})
527works like @kbd{M-x clone-indirect-buffer}, but it selects the new
ea146ed8
CY
528buffer in another window. These functions run the hook
529@code{clone-indirect-buffer-hook} after creating the indirect buffer.
eddcfd0e
RS
530
531 The more general way to make an indirect buffer is with the command
532@kbd{M-x make-indirect-buffer}. It creates an indirect buffer from
533buffer @var{base-buffer}, under the name @var{indirect-name}. It
534prompts for both @var{base-buffer} and @var{indirect-name} using the
535minibuffer.
f16874ce 536
b54346bc
DL
537@node Buffer Convenience
538@section Convenience Features and Customization of Buffer Handling
539
85d6c6e7
RS
540 This section describes several modes and features that make it more
541convenient to switch between buffers.
542
b54346bc 543@menu
7354ca01 544* Uniquify:: Making buffer names unique with directory parts.
d04efc64 545* Iswitchb:: Switching between buffers with substrings.
177c0ea7 546* Buffer Menus:: Configurable buffer menu.
b54346bc
DL
547@end menu
548
549@node Uniquify
564ee37b 550@subsection Making Buffer Names Unique
b54346bc 551
b54346bc
DL
552@cindex unique buffer names
553@cindex directories in buffer names
564ee37b
RS
554 When several buffers visit identically-named files, Emacs must give
555the buffers distinct names. The usual method for making buffer names
556unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer
557names (all but one of them).
558
559@vindex uniquify-buffer-name-style
560 Other methods work by adding parts of each file's directory to the
5dbbdd33 561buffer name. To select one, load the library @file{uniquify} (e.g.
64f3bde2 562using @code{(require 'uniquify)}), and customize the variable
564ee37b
RS
563@code{uniquify-buffer-name-style} (@pxref{Easy Customization}).
564
df7593dd
KB
565 To begin with, the @code{forward} naming method includes part of the
566file's directory name at the beginning of the buffer name; using this
567method, buffers visiting the files @file{/u/rms/tmp/Makefile} and
564ee37b
RS
568@file{/usr/projects/zaphod/Makefile} would be named
569@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead
570of @samp{Makefile} and @samp{Makefile<2>}).
571
df7593dd 572 In contrast, the @code{post-forward} naming method would call the
564ee37b
RS
573buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the
574@code{reverse} naming method would call them @samp{Makefile\tmp} and
575@samp{Makefile\zaphod}. The nontrivial difference between
576@code{post-forward} and @code{reverse} occurs when just one directory
577name is not enough to distinguish two files; then @code{reverse} puts
578the directory names in reverse order, so that @file{/top/middle/file}
579becomes @samp{file\middle\top}, while @code{post-forward} puts them in
580forward order after the file name, as in @samp{file|top/middle}.
581
582 Which rule to follow for putting the directory names in the buffer
583name is not very important if you are going to @emph{look} at the
584buffer names before you type one. But as an experienced user, if you
585know the rule, you won't have to look. And then you may find that one
a3053e27 586rule or another is easier for you to remember and apply quickly.
b54346bc 587
1ea14188
DL
588@node Iswitchb
589@subsection Switching Between Buffers using Substrings
590
591@findex iswitchb-mode
592@cindex Iswitchb mode
593@cindex mode, Iswitchb
594@kindex C-x b @r{(Iswitchb mode)}
595@kindex C-x 4 b @r{(Iswitchb mode)}
596@kindex C-x 5 b @r{(Iswitchb mode)}
597@kindex C-x 4 C-o @r{(Iswitchb mode)}
598
564ee37b
RS
599 Iswitchb global minor mode provides convenient switching between
600buffers using substrings of their names. It replaces the normal
601definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x
6024 C-o} with alternative commands that are somewhat ``smarter.''
1ea14188 603
564ee37b
RS
604 When one of these commands prompts you for a buffer name, you can
605type in just a substring of the name you want to choose. As you enter
606the substring, Iswitchb mode continuously displays a list of buffers
607that match the substring you have typed.
1ea14188 608
564ee37b
RS
609 At any time, you can type @key{RET} to select the first buffer in
610the list. So the way to select a particular buffer is to make it the
611first in the list. There are two ways to do this. You can type more
612of the buffer name and thus narrow down the list, excluding unwanted
613buffers above the desired one. Alternatively, you can use @kbd{C-s}
614and @kbd{C-r} to rotate the list until the desired buffer is first.
615
616 @key{TAB} while entering the buffer name performs completion on the
617string you have entered, based on the displayed list of buffers.
618
85d6c6e7
RS
619 To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize
620the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy
621Customization}).
622
564ee37b
RS
623@node Buffer Menus
624@subsection Customizing Buffer Menus
b54346bc 625
d04efc64 626@findex bs-show
d04efc64
DL
627@cindex buffer list, customizable
628@table @kbd
629@item M-x bs-show
630Make a list of buffers similarly to @kbd{M-x list-buffers} but
631customizable.
d04efc64
DL
632@end table
633
564ee37b
RS
634 @kbd{M-x bs-show} pops up a buffer list similar to the one normally
635displayed by @kbd{C-x C-b} but which you can customize. If you prefer
636this to the usual buffer list, you can bind this command to @kbd{C-x
637C-b}. To customize this buffer list, use the @code{bs} Custom group
638(@pxref{Easy Customization}).
1ea14188
DL
639
640@findex msb-mode
641@cindex mode, MSB
642@cindex MSB mode
643@cindex buffer menu
644@findex mouse-buffer-menu
564ee37b
RS
645@kindex C-Down-Mouse-1
646 MSB global minor mode (``MSB'' stands for ``mouse select buffer'')
647provides a different and customizable mouse buffer menu which you may
648prefer. It replaces the bindings of @code{mouse-buffer-menu},
649normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You
650can customize the menu in the @code{msb} Custom group.