@ignore
This file documents the user interface to the GNU History library.
-Copyright (C) 1988, 1991 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 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 your own 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,
+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 GNU History Library in your own programs,
+information on using the @sc{gnu} History Library in your own programs,
@pxref{Programming with GNU History}.
@end ifclear
+@ifset BashFeatures
@menu
+* Bash History Facilities:: How Bash lets you manipulate your command
+ history.
+* Bash History Builtins:: The Bash builtin commands that manipulate
+ the command history.
* History Interaction:: What it feels like using History as a user.
@end menu
+@end ifset
+@ifclear BashFeatures
+@menu
+* History Interaction:: What it feels like using History as a user.
+@end menu
+@end ifclear
+
+@ifset BashFeatures
+@node Bash History Facilities
+@section Bash History Facilities
+@cindex command history
+@cindex history list
+
+When the @option{-o history} option to the @code{set} builtin
+is enabled (@pxref{The Set Builtin}),
+the shell provides access to the @dfn{command history},
+the list of commands previously typed.
+The value of the @env{HISTSIZE} shell variable is used as the
+number of commands to save in a history list.
+The text of the last @env{$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
+@env{HISTIGNORE} and @env{HISTCONTROL}.
+
+When the shell starts up, the history is initialized from the
+file named by the @env{HISTFILE} variable (default @file{~/.bash_history}).
+The file named by the value of @env{HISTFILE} is truncated, if
+necessary, to contain no more than the number of lines specified by
+the value of the @env{HISTFILESIZE} variable.
+When an interactive shell exits, the last
+@env{$HISTSIZE} lines are copied from the history list to the file
+named by @env{$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.
+If @env{HISTFILE}
+is unset, or if the history file is unwritable, the history is
+not saved. After saving the history, the history file is truncated
+to contain no more than @env{$HISTFILESIZE}
+lines. If @env{HISTFILESIZE} is not set, no truncation is performed.
+
+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 may be used to display or modify the history
+list and manipulate the history file.
+When using command-line editing, search commands
+are available in each editing mode that provide access to the
+history list (@pxref{Commands For History}).
+
+The shell allows control over which commands are saved on the history
+list. The @env{HISTCONTROL} and @env{HISTIGNORE}
+variables may be set to cause the shell to save only a subset of the
+commands entered.
+The @code{cmdhist}
+shell option, if enabled, causes the shell to attempt to save each
+line of a multi-line command in the same history entry, adding
+semicolons where necessary to preserve syntactic correctness.
+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 which manipulate the
+history list and history file.
+
+@table @code
+
+@item fc
+@btindex fc
+@example
+@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]}
+@code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
+@end example
+
+Fix Command. In the first form, a range of commands from @var{first} to
+@var{last} is selected from the history list. Both @var{first} and
+@var{last} may be specified as a string (to locate the most recent
+command beginning with that string) or as a number (an index into the
+history list, where a negative number is used as an offset from the
+current command number). If @var{last} is not specified it is set to
+@var{first}. If @var{first} is not specified it is set to the previous
+command for editing and @minus{}16 for listing. If the @option{-l} flag is
+given, the commands are listed on standard output. The @option{-n} flag
+suppresses the command numbers when listing. The @option{-r} flag
+reverses the order of the listing. Otherwise, the editor given by
+@var{ename} is invoked on a file containing those commands. If
+@var{ename} is not given, the value of the following variable expansion
+is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
+value of the @env{FCEDIT} variable if set, or the value of the
+@env{EDITOR} variable if that is set, or @code{vi} if neither is set.
+When editing is complete, the edited commands are echoed and executed.
+
+In the second form, @var{command} is re-executed after each instance
+of @var{pat} in the selected command is replaced by @var{rep}.
+
+A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
+that typing @samp{r cc} runs the last command beginning with @code{cc}
+and typing @samp{r} re-executes the last command (@pxref{Aliases}).
+
+@item history
+@btindex history
+@example
+history [@var{n}]
+history -c
+history -d @var{offset}
+history [-anrw] [@var{filename}]
+history -ps @var{arg}
+@end example
+
+With no options, display the history list with line numbers.
+Lines prefixed 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 -c
+Clear the history list. This may be combined
+with the other options to replace the history list completely.
+
+@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
+history lines (history lines entered since the beginning of the
+current Bash session) to the history file.
+
+@item -n
+Append the history lines not already read from the history file
+to the current history list. These are lines appended to the history
+file since the beginning of the current Bash session.
+
+@item -r
+Read the current history file and append its contents to
+the history list.
+
+@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 any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options is
+used, if @var{filename}
+is given, then it is used as the history file. If not, then
+the value of the @env{HISTFILE} variable is used.
+
+@end table
+@end ifset
@node History Interaction
-@section History Interaction
-@cindex expansion
+@section History Expansion
+@cindex history expansion
The History library provides a history expansion feature that is similar
-to the history expansion provided by @code{csh}. The following text
+to the history expansion provided by @code{csh}. This section
describes the syntax used to manipulate the history information.
+History expansions introduce words from the history list into
+the input stream, making it easy to repeat commands, insert the
+arguments to a previous command into the current input line, or
+fix errors in previous commands quickly.
+
History expansion takes place in two parts. The first is to determine
-which line from the previous history should be used during substitution.
+which line from the history list should be used during substitution.
The second is to select portions of that line for inclusion into the
-current one. The line selected from the previous history is called the
+current one. The line selected from the history is called the
@dfn{event}, and the portions of that line that are acted upon are
-called @dfn{words}. The line is broken into words in the same fashion
-that Bash does, so that several English (or Unix) words
-surrounded by quotes are considered as one word.
+called @dfn{words}. Various @dfn{modifiers} are available to manipulate
+the selected words. The line is broken into words in the same fashion
+that Bash does, so that several words
+surrounded by quotes are considered one word.
+History expansions are introduced by the appearance of the
+history expansion character, which is @samp{!} by default.
+@ifset BashFeatures
+Only @samp{\} and @samp{'} may be used to escape the history expansion
+character.
+@end ifset
+
+@ifset BashFeatures
+Several shell options settable with the @code{shopt}
+builtin (@pxref{Bash Builtins}) may be used to tailor
+the behavior of history expansion. If the
+@code{histverify} shell option is enabled, and Readline
+is being used, history substitutions are not immediately passed to
+the shell parser.
+Instead, the expanded line is reloaded into the Readline
+editing buffer for further modification.
+If Readline is being used, and the @code{histreedit}
+shell option is enabled, a failed history expansion will be
+reloaded into the Readline editing buffer for correction.
+The @option{-p} option to the @code{history} builtin command
+may be used to see what a history expansion will do before using it.
+The @option{-s} option to the @code{history} builtin may be used to
+add commands to the end of the history list without actually executing
+them, so that they are available for subsequent recall.
+This is most useful in conjunction with Readline.
+
+The shell allows control of the various characters used by the
+history expansion mechanism with the @code{histchars} variable.
+@end ifset
@menu
* Event Designators:: How to specify which history line to use.
@item @code{!}
Start a history substitution, except when followed by a space, tab,
-the end of the line, @key{=} or @key{(}.
+the end of the line, @samp{=} or @samp{(}.
-@item @code{!!}
-Refer to the previous command. This is a synonym for @code{!-1}.
-
-@item @code{!n}
+@item @code{!@var{n}}
Refer to command line @var{n}.
-@item @code{!-n}
+@item @code{!-@var{n}}
Refer to the command @var{n} lines back.
-@item @code{!string}
+@item @code{!!}
+Refer to the previous command. This is a synonym for @samp{!-1}.
+
+@item @code{!@var{string}}
Refer to the most recent command starting with @var{string}.
-@item @code{!?string}[@code{?}]
-Refer to the most recent command containing @var{string}.
+@item @code{!?@var{string}[?]}
+Refer to the most recent command containing @var{string}. The trailing
+@samp{?} may be omitted if the @var{string} is followed immediately by
+a newline.
-@item @code{!#}
-The entire command line typed so far.
-
-@item @code{^string1^string2^}
+@item @code{^@var{string1}^@var{string2}^}
Quick Substitution. Repeat the last command, replacing @var{string1}
with @var{string2}. Equivalent to
-@code{!!:s/string1/string2/}.
+@code{!!:s/@var{string1}/@var{string2}/}.
+
+@item @code{!#}
+The entire command line typed so far.
@end table
@node Word Designators
@subsection Word Designators
-A @key{:} separates the event specification from the word designator. It
-can be omitted if the word designator begins with a @key{^}, @key{$},
-@key{*} or @key{%}. Words are numbered from the beginning of the line,
-with the first word being denoted by a 0 (zero).
+Word designators are used to select desired words from the event.
+A @samp{:} separates the event specification from the word designator. It
+may be omitted if the word designator begins with a @samp{^}, @samp{$},
+@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning
+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)
The @code{0}th word. For many applications, this is the command word.
-@item n
+@item @var{n}
The @var{n}th word.
@item ^
-The first argument; that is, word 1.
+The first argument; that is, word 1.
@item $
The last argument.
@item %
-The word matched by the most recent @code{?string?} search.
+The word matched by the most recent @samp{?@var{string}?} search.
-@item x-y
-A range of words; @code{-@var{y}} abbreviates @code{0-@var{y}}.
+@item @var{x}-@var{y}
+A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
@item *
-All of the words, except the @code{0}th. This is a synonym for @code{1-$}.
-It is not an error to use @key{*} if there is just one word in the event;
+All of the words, except the @code{0}th. This is a synonym for @samp{1-$}.
+It is not an error to use @samp{*} if there is just one word in the event;
the empty string is returned in that case.
-@item x*
-Abbreviates @code{x-$}
+@item @var{x}*
+Abbreviates @samp{@var{x}-$}
-@item x-
-Abbreviates @code{x-$} like @code{x*}, but omits the last word.
+@item @var{x}-
+Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
@end table
+If a word designator is supplied without an event specification, the
+previous command is used as the event.
+
@node Modifiers
@subsection Modifiers
After the optional word designator, you can add a sequence of one or more
-of the following modifiers, each preceded by a @key{:}.
+of the following modifiers, each preceded by a @samp{:}.
@table @code
@item h
Remove a trailing pathname component, leaving only the head.
+@item t
+Remove all leading pathname components, leaving the tail.
+
@item r
-Remove a trailing suffix of the form @samp{.}@var{suffix}, leaving the basename.
+Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
+the basename.
@item e
Remove all but the trailing suffix.
-@item t
-Remove all leading pathname components, leaving the tail.
-
@item p
Print the new command but do not execute it.
Quote the substituted words, escaping further substitutions.
@item x
-Quote the substituted words as with @code{q},
+Quote the substituted words as with @samp{q},
but break into words at spaces, tabs, and newlines.
@end ifset
-@item s/old/new/
+@item s/@var{old}/@var{new}/
Substitute @var{new} for the first occurrence of @var{old} in the
-event line. Any delimiter may be used in place of @key{/}.
+event line. Any delimiter may be used in place of @samp{/}.
The delimiter may be quoted in @var{old} and @var{new}
-with a single backslash. If @key{&} appears in @var{new},
+with a single backslash. If @samp{&} appears in @var{new},
it is replaced by @var{old}. A single backslash will quote
-the @key{&}. The final delimiter is optional if it is the last
+the @samp{&}. The final delimiter is optional if it is the last
character on the input line.
@item &
@item g
Cause changes to be applied over the entire event line. Used in
-conjunction with @code{s}, as in @code{gs/old/new/}, or with
-@code{&}.
+conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
+or with @samp{&}.
@end table
projects / platform / upstream / bash.git / blobdiff