path: root/doc/emacs/regs.texi

@c This is part of the Emacs manual.
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2001--2024 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Registers
@chapter Registers
@cindex registers

  Emacs @dfn{registers} are compartments where you can save text,
rectangles, positions, and other things for later use.  Once you save
text or a rectangle in a register, you can copy it into the buffer
once or many times; once you save a position in a register, you can
jump back to that position once or many times.

  Each register has a name that consists of a single character, which
we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
or a number (such as @samp{1}); case matters, so register @samp{a} is
not the same as register @samp{A}.  You can also set a register in
non-alphanumeric characters, for instance @samp{C-d} by using for
example @key{C-q} @samp{C-d}.

@findex view-register
  A register can store a position, a piece of text, a rectangle, a
number, a window or frame configuration, a buffer name, or a file
name, but only one thing at any given time.  Whatever you store in a
register remains there until you store something else in that
register.  To see what register @var{r} contains, use @kbd{M-x
view-register}:

@table @kbd
@item M-x view-register @key{RET} @var{r}
Display a description of what register @var{r} contains.
@end table


@cindex preview of registers
@vindex register-use-preview
  All of the commands that prompt for a register will by default
display a preview window that lists the existing registers (if there
are any) and their current values, after a short delay.  This and
other aspects of prompting for a register can be customized by setting
the value of @code{register-use-preview}, which can have the following
values:

@table @code
@vindex register-preview-delay
@item traditional
With this value, which is the default, Emacs behaves like it did in
all the versions before Emacs 29: it shows a preview of existing registers
after a delay, and lets you overwrite the values of existing registers
by typing a single character, the name of the register.  The preview
appears after the delay determined by the customizable variable
@code{register-preview-delay}, which specifies the delay in seconds;
setting it to @code{nil} disables the preview (but you can still
explicitly request a preview window by pressing @kbd{C-h} or
@key{F1} when Emacs prompts for a register).

@item t
This value requests a more flexible preview of existing registers.
The preview appears immediately when Emacs prompts for a register
(thus @code{register-preview-delay} has no effect), and the preview
window provides navigation: by using @kbd{C-n} and @kbd{C-p} (or the
@kbd{@key{UP}} and @kbd{@key{DOWN}} arrow keys), you can move between
the registers in the preview window.  To overwrite the value of an
existing registers in this mode, you need to type @key{RET} after
selecting the register by navigation or typing its name.

In addition, the registers shown by the preview are filtered according
to the command that popped the preview: for example, the preview shown
by @code{insert-register} will only show registers whose values can be
inserted into the buffer, omitting registers which hold window
configurations, positions, and other un-insertable values.

@item insist
This value is like @code{t}, but in addition you can press the same
key as the name of register one more time to exit the minibuffer,
instead of pressing @key{RET}.

@item nil
This value requests behavior similar to @code{traditional}, but the
preview is shown without delay, and is filtered according to the
command.

@item never
This value is like @code{nil}, but it disables the preview.
@end table

  @dfn{Bookmarks} record files and positions in them, so you can
return to those positions when you look at the file again.  Bookmarks
are similar in spirit to registers, so they are also documented in
this chapter.

@menu
* Position Registers::        Saving positions in registers.
* Text Registers::            Saving text in registers.
* Rectangle Registers::       Saving rectangles in registers.
* Configuration Registers::   Saving window/frame configurations in registers.
* Number Registers::          Numbers in registers.
* File and Buffer Registers:: File and buffer names in registers.
* Keyboard Macro Registers::  Keyboard macros in registers.
* Bookmarks::                 Bookmarks are like registers, but persistent.
@end menu

@node Position Registers
@section Saving Positions in Registers
@cindex saving position in a register

@table @kbd
@item C-x r @key{SPC} @var{r}
Record the position of point and the current buffer in register
@var{r} (@code{point-to-register}).
@item C-x r j @var{r}
Jump to the position and buffer saved in register @var{r}
(@code{jump-to-register}).
@end table

@kindex C-x r SPC
@findex point-to-register
  Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by
a character @kbd{@var{r}}, saves both the position of point and the
current buffer in register @var{r}.  The register retains this
information until you store something else in it.

@kindex C-x r j
@findex jump-to-register
  The command @kbd{C-x r j @var{r}} switches to the buffer recorded in
register @var{r}, pushes a mark, and moves point to the recorded
position.  (The mark is not pushed if point was already at the
recorded position, or in successive calls to the command.)  The
contents of the register are not changed, so you can jump to the saved
position any number of times.

  If you use @kbd{C-x r j} to go to a saved position, but the buffer it
was saved from has been killed, @kbd{C-x r j} tries to create the buffer
again by visiting the same file.  Of course, this works only for buffers
that were visiting files.

@node Text Registers
@section Saving Text in Registers
@cindex saving text in a register

  When you want to insert a copy of the same piece of text several
times, it may be inconvenient to yank it from the kill ring, since each
subsequent kill moves that entry further down the ring.  An alternative
is to store the text in a register and later retrieve it.

@table @kbd
@item C-x r s @var{r}
Copy region into register @var{r} (@code{copy-to-register}).
@item C-x r i @var{r}
Insert text from register @var{r} (@code{insert-register}).
@item M-x append-to-register @key{RET} @var{r}
Append region to text in register @var{r}.

When register @var{r} contains text, you can use @kbd{C-x r +}
(@code{increment-register}) to append to that register.  Note that
command @kbd{C-x r +} behaves differently if @var{r} contains a
number.  @xref{Number Registers}.

@item M-x prepend-to-register @key{RET} @var{r}
Prepend region to text in register @var{r}.
@end table

@kindex C-x r s
@findex copy-to-register
  @kbd{C-x r s @var{r}} stores a copy of the text of the region into
the register named @var{r}.  If the mark is inactive, Emacs first
reactivates the mark where it was last set.  The mark is deactivated
at the end of this command.  @xref{Mark}.  @kbd{C-u C-x r s @var{r}},
the same command with a prefix argument, copies the text into register
@var{r} and deletes the text from the buffer as well; you can think of
this as moving the region text into the register.

@findex append-to-register
@findex prepend-to-register
  @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
the text in the region to the text already stored in the register
named @var{r}.  If invoked with a prefix argument, it deletes the
region after appending it to the register.  The command
@code{prepend-to-register} is similar, except that it @emph{prepends}
the region text to the text in the register instead of
@emph{appending} it.

@vindex register-separator
  When you are collecting text using @code{append-to-register} and
@code{prepend-to-register}, you may want to separate individual
collected pieces using a separator.  In that case, configure a
@code{register-separator} and store the separator text in to that
register.  For example, to get double newlines as text separator
during the collection process, you can use the following setting.

@example
(setq register-separator ?+)
(set-register register-separator "\n\n")
@end example

@kindex C-x r i
@findex insert-register
  @kbd{C-x r i @var{r}} inserts in the buffer the text from register
@var{r}.  Normally it leaves point after the text and sets the mark
before, without activating it.  With a prefix argument, it instead
puts point before the text and the mark after.

@node Rectangle Registers
@section Saving Rectangles in Registers
@cindex saving rectangle in a register

  A register can contain a rectangle instead of linear text.
@xref{Rectangles}, for basic information on how to specify a rectangle
in the buffer.

@table @kbd
@findex copy-rectangle-to-register
@kindex C-x r r
@item C-x r r @var{r}
Copy the region-rectangle into register @var{r}
(@code{copy-rectangle-to-register}).  With prefix argument, delete it as
well.
@item C-x r i @var{r}
Insert the rectangle stored in register @var{r} (if it contains a
rectangle) (@code{insert-register}).
@end table

  The @kbd{C-x r i @var{r}} (@code{insert-register}) command,
previously documented in @ref{Text Registers}, inserts a rectangle
rather than a text string, if the register contains a rectangle.

@node Configuration Registers
@section Saving Window and Frame Configurations in Registers
@cindex saving window configuration in a register
@cindex saving frame configuration in a register
@cindex frameset, saving in a register

@findex window-configuration-to-register
@findex frameset-to-register
@kindex C-x r w
@kindex C-x r f
  You can save the window configuration of the selected frame in a
register, or even the configuration of all windows in all frames, and
restore the configuration later.  @xref{Window Convenience}, for
information about window configurations.

@table @kbd
@item C-x r w @var{r}
Save the state of the selected frame's windows in register @var{r}
(@code{window-configuration-to-register}).
@cindex frameset
@item C-x r f @var{r}
Save the state of all frames, including all their windows (a.k.a.@:
@dfn{frameset}), in register @var{r} (@code{frameset-to-register}).
@end table

  Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
This is the same command used to restore a cursor position.  When you
restore a frame configuration, any existing frames not included in the
configuration become invisible.  If you wish to delete these frames
instead, use @kbd{C-u C-x r j @var{r}}.

@node Number Registers
@section Keeping Numbers in Registers
@cindex saving number in a register

  There are commands to store a number in a register, to insert
the number in the buffer in decimal, and to increment it.  These commands
can be useful in keyboard macros (@pxref{Keyboard Macros}).

@table @kbd
@item C-u @var{number} C-x r n @var{r}
@kindex C-x r n
@findex number-to-register
Store @var{number} into register @var{r} (@code{number-to-register}).
@item C-u @var{number} C-x r + @var{r}
@kindex C-x r +
@findex increment-register
If @var{r} contains a number, increment the number in that register by
@var{number}.  Note that command @kbd{C-x r +}
(@code{increment-register}) behaves differently if @var{r} contains
text.  @xref{Text Registers}.
@item C-x r i @var{r}
Insert the number from register @var{r} into the buffer.
@end table

  @kbd{C-x r i} is the same command used to insert any other sort of
register contents into the buffer.  @kbd{C-x r +} with no numeric
argument increments the register value by 1; @kbd{C-x r n} with no
numeric argument stores zero in the register.

@node File and Buffer Registers
@section Keeping File and Buffer Names in Registers
@cindex saving file name in a register
@cindex saving buffer name in a register

  If you visit certain file names frequently, you can visit them more
conveniently if you put their names in registers.  Here's the Lisp code
used to put a file @var{name} into register @var{r}:

@smallexample
(set-register @var{r} '(file . @var{name}))
@end smallexample

@need 3000
@noindent
For example,

@smallexample
(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
@end smallexample

@noindent
puts the file name shown in register @samp{z}.

  To visit the file whose name is in register @var{r}, type @kbd{C-x r j
@var{r}}.  (This is the same command used to jump to a position or
restore a frame configuration.)

  Similarly, if there are certain buffers you visit frequently, you
can put their names in registers.  For instance, if you visit the
@samp{*Messages*} buffer often, you can use the following snippet to
put that buffer into the @samp{m} register:

@smallexample
(set-register ?m '(buffer . "*Messages*"))
@end smallexample

  To switch to the buffer whose name is in register @var{r}, type
@kbd{C-x r j @var{r}}.

@node Keyboard Macro Registers
@section Keyboard Macro Registers
@cindex saving keyboard macro in a register
@cindex keyboard macros, in registers

@kindex C-x C-k x
@findex kmacro-to-register
  If you need to execute a keyboard macro (@pxref{Keyboard Macros})
frequently, it is more convenient to put it in a register or save it
(@pxref{Save Keyboard Macro}).  @kbd{C-x C-k x @var{r}}
(@code{kmacro-to-register}) stores the last keyboard macro in register
@var{r}.

  To execute the keyboard macro in register @var{r}, type @kbd{C-x r j
@var{r}}.  (This is the same command used to jump to a position or
restore a frameset.)

@node Bookmarks
@section Bookmarks
@cindex bookmarks

  @dfn{Bookmarks} are somewhat like registers in that they record
positions you can jump to.  Unlike registers, they have long names, and
they persist automatically from one Emacs session to the next.  The
prototypical use of bookmarks is to record where you were reading in
various files.

@table @kbd
@item C-x r m @key{RET}
Set the bookmark for the visited file, at point.

@item C-x r m @var{bookmark} @key{RET}
Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).

@item C-x r M @var{bookmark} @key{RET}
Like @kbd{C-x r m}, but don't overwrite an existing bookmark.

@item C-x r b @var{bookmark} @key{RET}
Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).

@item C-x r l
List all bookmarks (@code{list-bookmarks}).

@item M-x bookmark-save
Save all the current bookmark values in the default bookmark file.
@end table

@kindex C-x r m
@findex bookmark-set
@kindex C-x r b
@findex bookmark-jump
  To record the current position in the visited file, use the command
@kbd{C-x r m}, which sets a bookmark using the visited file name as
the default for the bookmark name.  If you name each bookmark after
the file it points to, then you can conveniently revisit any of those
files with @kbd{C-x r b}, and move to the position of the bookmark at
the same time.

@kindex C-x r M
@findex bookmark-set-no-overwrite
  The command @kbd{C-x r M} (@code{bookmark-set-no-overwrite}) works
like @w{@kbd{C-x r m}}, but it signals an error if the specified
bookmark already exists, instead of overwriting it.

@kindex C-x r l
@findex list-bookmarks
  To display a list of all your bookmarks in a separate buffer, type
@kbd{C-x r l} (@code{list-bookmarks}).  If you switch to that buffer,
you can use it to edit your bookmark definitions or annotate the
bookmarks.  Type @kbd{C-h m} in the bookmark buffer for more
information about its special editing commands.

@findex bookmark-save
  When you kill Emacs, Emacs saves your bookmarks, if
you have changed any bookmark values.  You can also save the bookmarks
at any time with the @kbd{M-x bookmark-save} command.  Bookmarks are
saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with
older versions of Emacs, if you have a file named @file{~/.emacs.bmk},
that is used instead).  The bookmark commands load your default
bookmark file automatically.  This saving and loading is how bookmarks
persist from one Emacs session to the next.

@vindex bookmark-save-flag
  If you set the variable @code{bookmark-save-flag} to 1, each command
that sets a bookmark will also save your bookmarks; this way, you
don't lose any bookmark values even if Emacs crashes.  The value, if
a number, says how many bookmark modifications should go by between
saving.  If you set this variable to @code{nil}, Emacs only
saves bookmarks if you explicitly use @kbd{M-x bookmark-save}.

@vindex bookmark-default-file
  The variable @code{bookmark-default-file} specifies the file in
which to save bookmarks by default.

@vindex bookmark-use-annotations
@cindex bookmark annotations
  If you set the variable @code{bookmark-use-annotations} to @code{t},
setting a bookmark will query for an annotation.  If a bookmark has an
annotation, it is automatically shown in a separate window when you
jump to the bookmark.

@vindex bookmark-search-size
  Bookmark position values are saved with surrounding context, so that
@code{bookmark-jump} can find the proper position even if the file is
modified slightly.  The variable @code{bookmark-search-size} says how
many characters of context to record on each side of the bookmark's
position.  (In buffers that are visiting encrypted files, no context
is saved in the bookmarks file no matter the value of this variable.)

  Here are some additional commands for working with bookmarks:

@table @kbd
@item M-x bookmark-load @key{RET} @var{filename} @key{RET}
@findex bookmark-load
Load a file named @var{filename} that contains a list of bookmark
values.  You can use this command, as well as @code{bookmark-write}, to
work with other files of bookmark values in addition to your default
bookmark file.

@item M-x bookmark-write @key{RET} @var{filename} @key{RET}
@findex bookmark-write
Save all the current bookmark values in the file @var{filename}.

@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
@findex bookmark-delete
Delete the bookmark named @var{bookmark}.

@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
@findex bookmark-insert-location
Insert in the buffer the name of the file that bookmark @var{bookmark}
points to.

@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
@findex bookmark-insert
Insert in the buffer the @emph{contents} of the file that bookmark
@var{bookmark} points to.
@end table