REPL history browser
You can browse your REPL input history with the command M-x
cider-repl-history. This command is bound to C-c M-p
cider-repl-mode buffers and is also available via the
The history is displayed in reverse order, with the most recent input at the top of the buffer, and the oldest input at the bottom. You can scroll through the history, and when you find the history item you were looking for, you can insert it from the history buffer into your REPL buffer.
The history buffer has its own major mode,
cider-repl-history-mode. This is derived from
clojure-mode, so you
get fontification in the history buffer. This mode supports the
expected defcustom hook variable,
Where you use the history buffer to insert text into the REPL buffer, the exact behavior depends on the location of the cursor in the buffer prior to the insertion.
Typically, when you're actively using the REPL, your cursor will be at
the end of the REPL buffer (
point-max). In this case, the text is
inserted at the end of the buffer and the point advances to the end of
the inserted text (as if point was pushed by along by the text as it
In the unusual case where you invoke the history browser when your
cursor is not at the end of the REPL buffer, the inserted text will
still be inserted at the end of the buffer (
point-max), but the
point is not modified.
CIDER inserts the text without a final newline, allowing you to edit it. When you are ready, hit Return to have it evaluated by the REPL.
If you select an input, the text will be inserted into the REPL buffer
and the history buffer will automatically quit. If you decide you want
to quit without inserting any text at all, you can explicitly quit by
cider-repl-history-quit (see keyboard shortcuts). Because
of the initialization and cleanup that is done when using the history
buffer, it is better to quit properly rather than just switch away
from the history buffer.
When you quit the history buffer, CIDER can restore the buffer and
window configuration in a few different ways. The behavior is
cider-repl-history-quit-action, which can be assigned
one of several values:
quit-windowrestores the window configuration to what it was before. This is the default.
delete-and-restorerestores the window configuration to what it was before, and kills the
*cider-repl-history*buffer, and deletes the window.
bury-buffersimply buries the
*cider-repl-history*buffer, but keeps the window.
bury-and-delete-windowburies the buffer, and deletes the window if there is more than one window.
- any other value is interpreted as the name of a function to call
cider-repl-history-occur from the history buffer, you
will be prompted for a regular expression. The history buffer will be
filtered to only those inputs that match the regexp.
Preview and Highlight
cider-repl-history-show-preview is non-nil, CIDER displays an [
of the currently selected history entry, in the REPL buffer.
If you do not properly quit from browsing the history (i.e., if you
just C-x b away from the buffer), you may be left with an
unwanted overlay in your REPL buffer. If this happens, you can clean
it up with M-x
cider-repl-history-show-preview is nil (disabled).
There is a related feature to highlight the entry once it is actually
inserted into the REPL buffer, controlled by the variable
cider-repl-history-highlight-inserted-item, which can be set to the
solidhighlights the inserted text for a fixed period of time.
pulsecauses the highlighting to fade out gradually.
tselects the default highlighting style, which is currently
nildisables highlighting. This is the default value for
cider-repl-history-highlight-inserted-item is non-nil, you
can customize the face used for the inserted text with the variable
There are quite a few customizations available, in addition to the ones already mentioned.
cider-repl-history-display-duplicates- when set to
nil, will not display any duplicate entries in the history buffer. Default is
cider-repl-history-display-duplicate-highest- when not displaying duplicates, this controls where in the history the one instance of the duplicated text is displayed. When
t, it displays the entry in the highest position applicable; when
nil, it displays it in the lowest position.
cider-repl-history-display-style- the history entries will often be more than one line. The package gives you two options for displaying the entries:
separated- a separator string is inserted between entries; entries may span multiple lines. This is the default.
one-line- any newlines are replaced with literal
\nstrings, and therefore no separator is necessary. Each
\nbecomes a proper newline when the text is inserted into the REPL.
separated, this gives the text to use as the separator. The default is a series of ten semicolons, which is, of course, a comment in Clojure. The separator could be anything, but it may screw up the fontification if you make it something weird.
cider-repl-history-separator-face- specifies the face for the separator.
cider-repl-history-maximum-display-length- when nil (the default), all history items are displayed in full. If you prefer to have long items abbreviated, you can set this variable to an integer, and each item will be limited to that many characters. (This variable does not affect the number of items displayed, only the maximum length of each item.)
cider-repl-history-recenter- when non-nil, always keep the current entry at the top of the history window. Default is nil.
cider-repl-history-resize-window- whether to resize the history window to fit its contents. Value is either t, meaning yes, or a cons pair of integers, (MAXIMUM . MINIMUM) for the size of the window. MAXIMUM defaults to the window size chosen by
pop-to-buffer; MINIMUM defaults to
cider-repl-history-highlight-current-entry- if non-nil, highlight the currently selected entry in the history buffer. Default is nil.
cider-repl-history-current-entry-face- specifies the face for the history-entry highlight.
cider-repl-history-text-properties- when set to
t, maintains Emacs text properties on the entry. Default is
There are a number of important keybindings in history buffers.
|n||Go to next (lower, older) item in the history.|
|p||Go to previous (higher, more recent) item in the history.|
|RET or SPC||Insert history item (at point) at the end of the REPL buffer, and quit.|
|l (lower-case L)||Filter the command history (see Filtering, above).|
|s||Regexp search forward.|
|r||Regexp search backward.|
|q||Quit (and take quit action).|
|U||Undo in the REPL buffer.|