\HeaderA{savehistory}{Load or Save or Display the Commands History}{savehistory}
\aliasA{history}{savehistory}{history}
\aliasA{loadhistory}{savehistory}{loadhistory}
\aliasA{timestamp}{savehistory}{timestamp}
\keyword{utilities}{savehistory}
\begin{Description}\relax
Load or save or display the commands history.
\end{Description}
\begin{Usage}
\begin{verbatim}
loadhistory(file = ".Rhistory")
savehistory(file = ".Rhistory")

history(max.show = 25, reverse = FALSE, pattern, ...)

timestamp(stamp = date(),
          prefix = "##------ ", suffix = " ------##",
          quiet = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] The name of the file in which to save the history, or
from which to load it. The path is relative to the current
working directory.
\item[\code{max.show}] The maximum number of lines to show. \code{Inf} will
give all of the currently available history.
\item[\code{reverse}] logical. If true, the lines are shown in reverse
order. Note: this is not useful when there are continuation lines.
\item[\code{pattern}] A character string to be matched against the lines of
the history
\item[\code{...}] Arguments to be passed to \code{\LinkA{grep}{grep}} when doing
the matching.
\item[\code{stamp}] A value or vector of values to be written into the history.
\item[\code{prefix}] A prefix to apply to each line.
\item[\code{suffix}] A suffix to apply to each line.
\item[\code{quiet}] If \code{TRUE}, suppress printing timestamp to the console.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
There are several history mechanisms available for the different \R{}
consoles, which work in similar but not identical ways.  Other uses of
\R, in particular embedded uses, may have no history.
This works under the \code{readline} command-line interface and the
\code{R.app} Mac OS X console, but not otherwise (for example, in
batch use or in an embedded application).

The \code{readline} history mechanism is controlled by two environment
variables: \code{R\_HISTSIZE} controls the number of lines that are
saved (default 512), and \code{R\_HISTFILE} sets the filename used for
the loading/saving of history if requested at the beginning/end of a
session (but not the default for these functions).  There is no limit
on the number of lines of history retained during a session, so
setting \code{R\_HISTSIZE} to a large value has no penalty unless a
large file is actually generated.

These variables are read at the time of saving, so can be altered
within a session by the use of \code{\LinkA{Sys.setenv}{Sys.setenv}}.

Note that \code{readline} history library save files with permission
\code{0600}, that is with read/write permission for the user and not
even read permission for any other account.

\code{history} shows only unique matching lines if \code{pattern} is
supplied.

The \code{timestamp} function writes a timestamp (or other message)
into the history and echos it to the console.  On platforms that do not
support a history mechanism (where the mechanism does not support
timestamps) only the console message is printed.
\end{Details}
\begin{Note}\relax
If you want to save the history at the end of (almost) every
interactive session (even those in which you do not save the
workspace), you can put a call to \code{savehistory()} in
\code{\LinkA{.Last}{.Last}}.  See the examples.
\end{Note}
\begin{Examples}
\begin{ExampleCode}## Not run: 
.Last <- function()
    if(interactive()) try(savehistory("~/.Rhistory"))
## End(Not run)\end{ExampleCode}
\end{Examples}

