1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software
4 @c See file emacs.texi for copying conditions.
9 Emacs @dfn{registers} are compartments where you can save text,
10 rectangles, positions, and other things for later use. Once you save
11 text or a rectangle in a register, you can copy it into the buffer
12 once, or many times; once you save a position in a register, you can
13 jump back to that position once, or many times.
15 Each register has a name that consists of a single character, which
16 we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
17 or a number (such as @samp{1}); case matters, so register @samp{a} is
18 not the same as register @samp{A}.
21 A register can store a position, a piece of text, a rectangle, a
22 number, a window configuration, or a file name, but only one thing at
23 any given time. Whatever you store in a register remains there until
24 you store something else in that register. To see what register
25 @var{r} contains, use @kbd{M-x view-register}:
28 @item M-x view-register @key{RET} @var{r}
29 Display a description of what register @var{r} contains.
32 @dfn{Bookmarks} record files and positions in them, so you can
33 return to those positions when you look at the file again. Bookmarks
34 are similar in spirit to registers, so they are also documented in
38 * Position Registers:: Saving positions in registers.
39 * Text Registers:: Saving text in registers.
40 * Rectangle Registers:: Saving rectangles in registers.
41 * Configuration Registers:: Saving window configurations in registers.
42 * Number Registers:: Numbers in registers.
43 * File Registers:: File names in registers.
44 * Keyboard Macro Registers:: Keyboard macros in registers.
45 * Bookmarks:: Bookmarks are like registers, but persistent.
48 @node Position Registers
49 @section Saving Positions in Registers
50 @cindex saving position in a register
53 @item C-x r @key{SPC} @var{r}
54 Record the position of point and the current buffer in register
55 @var{r} (@code{point-to-register}).
57 Jump to the position and buffer saved in register @var{r}
58 (@code{jump-to-register}).
62 @findex point-to-register
63 Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by
64 a character @kbd{@var{r}}, saves both the position of point and the
65 current buffer in register @var{r}. The register retains this
66 information until you store something else in it.
69 @findex jump-to-register
70 The command @kbd{C-x r j @var{r}} switches to the buffer recorded in
71 register @var{r}, and moves point to the recorded position. The
72 contents of the register are not changed, so you can jump to the saved
73 position any number of times.
75 If you use @kbd{C-x r j} to go to a saved position, but the buffer it
76 was saved from has been killed, @kbd{C-x r j} tries to create the buffer
77 again by visiting the same file. Of course, this works only for buffers
78 that were visiting files.
81 @section Saving Text in Registers
82 @cindex saving text in a register
84 When you want to insert a copy of the same piece of text several
85 times, it may be inconvenient to yank it from the kill ring, since each
86 subsequent kill moves that entry further down the ring. An alternative
87 is to store the text in a register and later retrieve it.
91 Copy region into register @var{r} (@code{copy-to-register}).
93 Insert text from register @var{r} (@code{insert-register}).
94 @item M-x append-to-register @key{RET} @var{r}
95 Append region to text in register @var{r}.
98 When register @var{r} contains text, you can use @kbd{C-x r +}
99 (@code{increment-register}) to append to that register. Note that
100 command @kbd{C-x r +} behaves differently if @var{r} contains a
101 number. @xref{Number Registers}.
103 @item M-x prepend-to-register @key{RET} @var{r}
104 Prepend region to text in register @var{r}.
108 @findex copy-to-register
109 @kbd{C-x r s @var{r}} stores a copy of the text of the region into
110 the register named @var{r}. If the mark is inactive, Emacs first
111 reactivates the mark where it was last set. The mark is deactivated
112 at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}},
113 the same command with a prefix argument, copies the text into register
114 @var{r} and deletes the text from the buffer as well; you can think of
115 this as ``moving'' the region text into the register.
117 @findex append-to-register
118 @findex prepend-to-register
119 @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
120 the text in the region to the text already stored in the register
121 named @var{r}. If invoked with a prefix argument, it deletes the
122 region after appending it to the register. The command
123 @code{prepend-to-register} is similar, except that it @emph{prepends}
124 the region text to the text in the register instead of
127 @vindex register-separator
128 When you are collecting text using @code{append-to-register} and
129 @code{prepend-to-register}, you may want to separate individual
130 collected pieces using a separator. In that case, configure a
131 @code{register-separator} and store the separator text in to that
132 register. For example, to get double newlines as text separator
133 during the collection process, you can use the following setting.
136 (setq register-separator ?+)
137 (set-register register-separator "\n\n")
141 @findex insert-register
142 @kbd{C-x r i @var{r}} inserts in the buffer the text from register
143 @var{r}. Normally it leaves point before the text and sets the mark
144 after, without activating it. With a numeric argument, it instead
145 puts point after the text and the mark before.
147 @node Rectangle Registers
148 @section Saving Rectangles in Registers
149 @cindex saving rectangle in a register
151 A register can contain a rectangle instead of linear text.
152 @xref{Rectangles}, for basic information on how to specify a rectangle
156 @findex copy-rectangle-to-register
158 @item C-x r r @var{r}
159 Copy the region-rectangle into register @var{r}
160 (@code{copy-rectangle-to-register}). With numeric argument, delete it as
162 @item C-x r i @var{r}
163 Insert the rectangle stored in register @var{r} (if it contains a
164 rectangle) (@code{insert-register}).
167 The @kbd{C-x r i @var{r}} (@code{insert-register}) command,
168 previously documented in @ref{Text Registers}, inserts a rectangle
169 rather than a text string, if the register contains a rectangle.
171 @node Configuration Registers
172 @section Saving Window Configurations in Registers
173 @cindex saving window configuration in a register
175 @findex window-configuration-to-register
176 @findex frame-configuration-to-register
179 You can save the window configuration of the selected frame in a
180 register, or even the configuration of all windows in all frames, and
181 restore the configuration later. @xref{Windows}, for information
182 about window configurations.
185 @item C-x r w @var{r}
186 Save the state of the selected frame's windows in register @var{r}
187 (@code{window-configuration-to-register}).
188 @item C-x r f @var{r}
189 Save the state of all frames, including all their windows, in register
190 @var{r} (@code{frame-configuration-to-register}).
193 Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
194 This is the same command used to restore a cursor position. When you
195 restore a frame configuration, any existing frames not included in the
196 configuration become invisible. If you wish to delete these frames
197 instead, use @kbd{C-u C-x r j @var{r}}.
199 @node Number Registers
200 @section Keeping Numbers in Registers
201 @cindex saving number in a register
203 There are commands to store a number in a register, to insert
204 the number in the buffer in decimal, and to increment it. These commands
205 can be useful in keyboard macros (@pxref{Keyboard Macros}).
208 @item C-u @var{number} C-x r n @var{r}
210 @findex number-to-register
211 Store @var{number} into register @var{r} (@code{number-to-register}).
212 @item C-u @var{number} C-x r + @var{r}
214 @findex increment-register
215 If @var{r} contains a number, increment the number in that register by
216 @var{number}. Note that command @kbd{C-x r +}
217 (@code{increment-register}) behaves differently if @var{r} contains
218 text. @xref{Text Registers}.
219 @item C-x r i @var{r}
220 Insert the number from register @var{r} into the buffer.
223 @kbd{C-x r i} is the same command used to insert any other sort of
224 register contents into the buffer. @kbd{C-x r +} with no numeric
225 argument increments the register value by 1; @kbd{C-x r n} with no
226 numeric argument stores zero in the register.
229 @section Keeping File Names in Registers
230 @cindex saving file name in a register
232 If you visit certain file names frequently, you can visit them more
233 conveniently if you put their names in registers. Here's the Lisp code
234 used to put a file name in a register:
237 (set-register ?@var{r} '(file . @var{name}))
245 (set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
249 puts the file name shown in register @samp{z}.
251 To visit the file whose name is in register @var{r}, type @kbd{C-x r j
252 @var{r}}. (This is the same command used to jump to a position or
253 restore a frame configuration.)
255 @node Keyboard Macro Registers
256 @section Keyboard Macro Registers
257 @cindex saving keyboard macro in a register
258 @cindex keyboard macros, in registers
261 @findex kmacro-to-register
262 If you need to execute a keyboard macro (@pxref{Keyboard Macros})
263 frequently, it is more convenient to put it in a register or save it
264 (@pxref{Save Keyboard Macro}). @kbd{C-x C-k x @var{r}}
265 (@code{kmacro-to-register}) stores the last keyboard macro in register
268 To execute the keyboard macro in register @var{r}, type @kbd{C-x r j
269 @var{r}}. (This is the same command used to jump to a position or
276 @dfn{Bookmarks} are somewhat like registers in that they record
277 positions you can jump to. Unlike registers, they have long names, and
278 they persist automatically from one Emacs session to the next. The
279 prototypical use of bookmarks is to record ``where you were reading'' in
283 @item C-x r m @key{RET}
284 Set the bookmark for the visited file, at point.
286 @item C-x r m @var{bookmark} @key{RET}
288 Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
290 @item C-x r b @var{bookmark} @key{RET}
291 @findex bookmark-jump
292 Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
295 @findex list-bookmarks
296 List all bookmarks (@code{list-bookmarks}).
298 @item M-x bookmark-save
299 @findex bookmark-save
300 Save all the current bookmark values in the default bookmark file.
306 @findex bookmark-jump
307 The prototypical use for bookmarks is to record one current position
308 in each of several files. So the command @kbd{C-x r m}, which sets a
309 bookmark, uses the visited file name as the default for the bookmark
310 name. If you name each bookmark after the file it points to, then you
311 can conveniently revisit any of those files with @kbd{C-x r b}, and move
312 to the position of the bookmark at the same time.
315 To display a list of all your bookmarks in a separate buffer, type
316 @kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer,
317 you can use it to edit your bookmark definitions or annotate the
318 bookmarks. Type @kbd{C-h m} in the bookmark buffer for more
319 information about its special editing commands.
321 When you kill Emacs, Emacs saves your bookmarks, if
322 you have changed any bookmark values. You can also save the bookmarks
323 at any time with the @kbd{M-x bookmark-save} command. Bookmarks are
324 saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with
325 older versions of Emacs, if you have a file named @file{~/.emacs.bmk},
326 that is used instead). The bookmark commands load your default
327 bookmark file automatically. This saving and loading is how bookmarks
328 persist from one Emacs session to the next.
330 @vindex bookmark-save-flag
331 If you set the variable @code{bookmark-save-flag} to 1, each command
332 that sets a bookmark will also save your bookmarks; this way, you
333 don't lose any bookmark values even if Emacs crashes. The value, if
334 a number, says how many bookmark modifications should go by between
335 saving. If you set this variable to @code{nil}, Emacs only
336 saves bookmarks if you explicitly use @kbd{M-x bookmark-save}.
338 @vindex bookmark-default-file
339 The variable @code{bookmark-default-file} specifies the file in
340 which to save bookmarks by default.
342 @vindex bookmark-search-size
343 Bookmark position values are saved with surrounding context, so that
344 @code{bookmark-jump} can find the proper position even if the file is
345 modified slightly. The variable @code{bookmark-search-size} says how
346 many characters of context to record on each side of the bookmark's
349 Here are some additional commands for working with bookmarks:
352 @item M-x bookmark-load @key{RET} @var{filename} @key{RET}
353 @findex bookmark-load
354 Load a file named @var{filename} that contains a list of bookmark
355 values. You can use this command, as well as @code{bookmark-write}, to
356 work with other files of bookmark values in addition to your default
359 @item M-x bookmark-write @key{RET} @var{filename} @key{RET}
360 @findex bookmark-write
361 Save all the current bookmark values in the file @var{filename}.
363 @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
364 @findex bookmark-delete
365 Delete the bookmark named @var{bookmark}.
367 @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
368 @findex bookmark-insert-location
369 Insert in the buffer the name of the file that bookmark @var{bookmark}
372 @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
373 @findex bookmark-insert
374 Insert in the buffer the @emph{contents} of the file that bookmark
375 @var{bookmark} points to.