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