@ignore
This file documents the user interface to the GNU History library.
-Copyright (C) 1988, 1991, 1996 Free Software Foundation, Inc.
+Copyright (C) 1988-1999 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
Permission is granted to make and distribute verbatim copies of this manual
@node Using History Interactively
@chapter Using History Interactively
+@ifclear BashFeatures
+@defcodeindex bt
+@end ifclear
+
@ifset BashFeatures
-This chapter describes how to use the GNU History Library interactively,
-from a user's standpoint. It should be considered a user's guide. For
-information on using the GNU History Library in other programs,
-see the GNU Readline Library Manual.
+This chapter describes how to use the @sc{gnu} History Library
+interactively, from a user's standpoint.
+It should be considered a user's guide.
+For information on using the @sc{gnu} History Library in other programs,
+see the @sc{gnu} Readline Library Manual.
@end ifset
@ifclear BashFeatures
This chapter describes how to use the GNU History Library interactively,
When the @samp{-o history} option to the @code{set} builtin
is enabled (@pxref{The Set Builtin}),
the shell provides access to the @var{command history},
-the list of commands previously typed. The text of the last
-@code{HISTSIZE}
-commands (default 500) is saved in a history list. The shell
-stores each command in the history list prior to parameter and
-variable expansion
+the list of commands previously typed.
+The value of the @code{HISTSIZE} shell variable is used as the
+number of commands to save in a history list.
+The text of the last @code{$HISTSIZE}
+commands (default 500) is saved.
+The shell stores each command in the history list prior to
+parameter and variable expansion
but after history expansion is performed, subject to the
values of the shell variables
@code{HISTIGNORE} and @code{HISTCONTROL}.
+
When the shell starts up, the history is initialized from the
file named by the @code{HISTFILE} variable (default @file{~/.bash_history}).
-@code{HISTFILE} is truncated, if necessary, to contain no more than
-the number of lines specified by the value of the @code{HISTFILESIZE}
-variable. When an interactive shell exits, the last
-@code{HISTSIZE} lines are copied from the history list to @code{HISTFILE}.
+The file named by the value of @code{HISTFILE} is truncated, if
+necessary, to contain no more than the number of lines specified by
+the value of the @code{HISTFILESIZE} variable.
+When an interactive shell exits, the last
+@code{$HISTSIZE} lines are copied from the history list to the file
+named by @code{$HISTFILE}.
If the @code{histappend} shell option is set (@pxref{Bash Builtins}),
the lines are appended to the history file,
otherwise the history file is overwritten.
The builtin command @code{fc} may be used to list or edit and re-execute
a portion of the history list.
-The @code{history} builtin can be used to display or modify the history
+The @code{history} builtin may be used to display or modify the history
list and manipulate the history file.
-When using the command-line editing, search commands
+When using command-line editing, search commands
are available in each editing mode that provide access to the
-history list.
+history list (@pxref{Commands For History}).
The shell allows control over which commands are saved on the history
list. The @code{HISTCONTROL} and @code{HISTIGNORE}
The @code{lithist}
shell option causes the shell to save the command with embedded newlines
instead of semicolons.
+The @code{shopt} builtin is used to set these options.
@xref{Bash Builtins}, for a description of @code{shopt}.
@node Bash History Builtins
@section Bash History Builtins
@cindex history builtins
-Bash provides two builtin commands that allow you to manipulate the
+Bash provides two builtin commands which manipulate the
history list and history file.
@table @code
@item fc
-@comment btindex fc
+@btindex fc
@example
@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]}
@code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
and typing @samp{r} re-executes the last command (@pxref{Aliases}).
@item history
-@comment btindex history
+@btindex history
@example
-history [-c] [@var{n}]
+history [@var{n}]
+history -c
+history -d @var{offset}
history [-anrw] [@var{filename}]
history -ps @var{arg}
@end example
-Display the history list with line numbers. Lines prefixed with
-with a @samp{*} have been modified. An argument of @var{n} says
-to list only the last @var{n} lines. Options, if supplied, have
-the following meanings:
+With no options, display the history list with line numbers.
+Lines prefixed with with a @samp{*} have been modified.
+An argument of @var{n} lists only the last @var{n} lines.
+Options, if supplied, have the following meanings:
@table @code
-@item -w
-Write out the current history to the history file.
+@item -c
+Clear the history list. This may be combined
+with the other options to replace the history list completely.
-@item -r
-Read the current history file and append its contents to
-the history list.
+@item -d @var{offset}
+Delete the history entry at position @var{offset}.
+@var{offset} should be specified as it appears when the history is
+displayed.
@item -a
Append the new
to the current history list. These are lines appended to the history
file since the beginning of the current Bash session.
-@item -c
-Clear the history list. This may be combined
-with the other options to replace the history list completely.
+@item -r
+Read the current history file and append its contents to
+the history list.
-@item -s
-The @var{arg}s are added to the end of
-the history list as a single entry.
+@item -w
+Write out the current history to the history file.
@item -p
Perform history substitution on the @var{arg}s and display the result
on the standard output, without storing the results in the history list.
+
+@item -s
+The @var{arg}s are added to the end of
+the history list as a single entry.
+
@end table
-When the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} option is
+When any of the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} options is
used, if @var{filename}
is given, then it is used as the history file. If not, then
the value of the @code{HISTFILE} variable is used.
of the line, with the first word being denoted by 0 (zero). Words are
inserted into the current line separated by single spaces.
+@need 0.75
+For example,
+
+@table @code
+@item !!
+designates the preceding command. When you type this, the preceding
+command is repeated in toto.
+
+@item !!:$
+designates the last argument of the preceding command. This may be
+shortened to @code{!$}.
+
+@item !fi:2
+designates the second argument of the most recent command starting with
+the letters @code{fi}.
+@end table
+
+@need 0.75
+Here are the word designators:
+
@table @code
@item 0 (zero)