A minibuffer history list records previous minibuffer inputs so the user can reuse them conveniently. It is a variable whose value is a list of strings (previous inputs), most recent first.
There are many separate minibuffer history lists, used for different kinds of inputs. It’s the Lisp programmer’s job to specify the right history list for each use of the minibuffer.
You specify a minibuffer history list with the optional history
argument to read-from-minibuffer or completing-read.
Here are the possible values for it:
Use variable (a symbol) as the history list.
Use variable (a symbol) as the history list, and assume that the initial history position is startpos (a nonnegative integer).
Specifying 0 for startpos is equivalent to just specifying the
symbol variable. previous-history-element will display
the most recent element of the history list in the minibuffer. If you
specify a positive startpos, the minibuffer history functions
behave as if (elt variable (1- startpos)) were the
history element currently shown in the minibuffer.
For consistency, you should also specify that element of the history as the initial minibuffer contents, using the initial argument to the minibuffer input function (see Initial Input).
If you don’t specify history, then the default history list
minibuffer-history is used. For other standard history lists,
see below. You can also create your own history list variable; just
initialize it to nil before the first use. If the variable is
buffer local, then each buffer will have its own input history list.
Both read-from-minibuffer and completing-read add new
elements to the history list automatically, and provide commands to
allow the user to reuse items on the list (see Minibuffer Commands). The only thing your program needs to do to use a history
list is to initialize it and to pass its name to the input functions
when you wish. But it is safe to modify the list by hand when the
minibuffer input functions are not using it.
By default, when M-n (next-history-element,
see next-history-element) reaches the end of
the list of default values provided by the command which initiated
reading input from the minibuffer, M-n adds all of the
completion candidates, as specified by
minibuffer-completion-table (see Minibuffer Commands that Do Completion), to
the list of defaults, so that all those candidates are available as
“future history”. Your program can control that via the variable
minibuffer-default-add-function: if its value is not a
function, this automatic addition is disabled, and you can also set
this variable to your own function which adds only some candidates, or
some other values, to the “future history”.
Emacs functions that add a new element to a history list can also
delete old elements if the list gets too long. The variable
history-length specifies the maximum length for most history
lists. To specify a different maximum length for a particular history
list, put the length in the history-length property of the
history list symbol. The variable history-delete-duplicates
specifies whether to delete duplicates in history.
This function adds a new element newelt, if it isn’t the empty
string, to the history list stored in the variable history-var,
and returns the updated history list. It limits the list length to
the value of maxelt (if non-nil) or history-length
(described below). The possible values of maxelt have the same
meaning as the values of history-length.
history-var cannot refer to a lexical variable.
Normally, add-to-history removes duplicate members from the
history list if history-delete-duplicates is non-nil.
However, if keep-all is non-nil, that says not to remove
duplicates, and to add newelt to the list even if it is empty.
If the value of this variable is nil, standard functions that
read from the minibuffer don’t add new elements to the history list.
This lets Lisp programs explicitly manage input history by using
add-to-history. The default value is t.
The value of this variable specifies the maximum length for all
history lists that don’t specify their own maximum lengths. If the
value is t, that means there is no maximum (don’t delete old
elements). If a history list variable’s symbol has a non-nil
history-length property, it overrides this variable for that
particular history list.
If the value of this variable is t, that means when adding a
new history element, all previous identical elements are deleted.
Here are some of the standard minibuffer history list variables:
The default history list for minibuffer history input.
A history list for arguments to query-replace (and similar
arguments to other commands).
A history list for file-name arguments.
A history list for buffer-name arguments.
A history list for regular expression arguments.
A history list for arguments that are names of extended commands.
A history list for arguments that are shell commands.
A history list for arguments that are Lisp expressions to evaluate.
A history list for arguments that are faces.
A history list for variable-name arguments read by
read-variable.
A history list for numbers read by read-number.
A history list for arguments to goto-line. This variable can
be made local in every buffer by customizing the user option
goto-line-history-local.