Using History Interactively
***************************

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 Programming with GNU History.

History Expansion
=================

The History library provides a history expansion feature that is similar to the history expansion provided by csh (also referred to as history substitution where appropriate). 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 entry from the history list should be used during substitution. The second is to select portions of that entry to include into the current one.

The entry selected from the history is called the event, and the portions of that entry that are acted upon are words. Various modifiers are available to manipulate the selected words. The entry is split into words in the same fashion that Bash does when reading input, so that several words surrounded by quotes are considered one word. The event designator selects the event, the optional word designator selects words from the event, and various optional modifiers are available to manipulate the selected words.

History expansions are introduced by the appearance of the history expansion character, which is ! by default. History expansions may appear anywhere in the input, but do not nest.

History expansion implements shell-like quoting conventions: a backslash can be used to remove the special handling for the next character; single quotes enclose verbatim sequences of characters, and can be used to inhibit history expansion; and characters enclosed within double quotes may be subject to history expansion, since backslash can escape the history expansion character, but single quotes may not, since they are not treated specially within double quotes.

There is a special abbreviation for substitution, active when the QUICK SUBSTITUTION character (default ^) is the first character on the line. It selects the previous history list entry, using an event designator equivalent to !!, and substitutes one string for another in that entry. It is described below (see Event Designators). This is the only history expansion that does not begin with the history expansion character.

Event Designators
-----------------

An event designator is a reference to an entry in the history list. The event designator consists of the portion of the word beginning with the history expansion character, and ending with the word designator if one is present, or the end of the word. Unless the reference is absolute, events are relative to the current position in the history list.

!
     Start a history substitution, except when followed by a space, tab, the end of the line, or =.

!N
     Refer to history list entry N.

!-N
     Refer to the history entry minus N.

!!
     Refer to the previous entry. This is a synonym for !-1.

!STRING
     Refer to the most recent command preceding the current position in the history list starting with STRING.

!?STRING[?]
     Refer to the most recent command preceding the current position in the history list containing STRING. The trailing ? may be omitted if the STRING is followed immediately by a newline. If STRING is missing, this uses the string from the most recent search; it is an error if there is no previous search string.

^STRING1^STRING2^
     Quick Substitution. Repeat the last command, replacing STRING1 with STRING2. Equivalent to !!:s^STRING1^STRING2^.

!#
     The entire command line typed so far.

Word Designators
----------------

Word designators are used to select desired words from the event. They are optional; if the word designator isn't supplied, the history expansion uses the entire event. A : separates the event specification from the word designator. It may be omitted if the word designator begins with a ^, $, *, -, or %. Words are numbered from the beginning of the line, with the first word being denoted by 0 (zero). That first word is usually the command word, and the arguments begin with the second word. Words are inserted into the current line separated by single spaces.

For example,

!!
     designates the preceding command. When you type this, the preceding command is repeated in toto.

!!:$
     designates the last word of the preceding command. This may be shortened to !$.

!fi:2
     designates the second argument of the most recent command starting with the letters fi.

Here are the word designators:

0 (zero)
     The 0th word. For the shell, and many other, applications, this is the command word.

N
     The Nth word.

^
     The first argument: word 1.

$
     The last word. This is usually the last argument, but expands to the zeroth word if there is only one word in the line.

%
     The first word matched by the most recent ?STRING? search, if the search string begins with a character that is part of a word. By default, searches begin at the end of each line and proceed to the beginning, so the first word matched is the one closest to the end of the line.

X-Y
     A range of words; -Y abbreviates 0-Y.

*
     All of the words, except the 0th. This is a synonym for 1-$. It is not an error to use * if there is just one word in the event; it expands to the empty string in that case.

X*
     Abbreviates X-$.

X-
     Abbreviates X-$ like X*, but omits the last word. If x is missing, it defaults to 0.

If a word designator is supplied without an event specification, the previous command is used as the event, equivalent to !!.

Modifiers
---------

After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a :. These modify, or edit, the word or words selected from the history event.

h
     Remove a trailing filename component, leaving only the head.

t
     Remove all leading filename components, leaving the tail.

r
     Remove a trailing suffix of the form .SUFFIX, leaving the basename.

e
     Remove all but the trailing suffix.

p
     Print the new command but do not execute it.

s/OLD/NEW/
     Substitute NEW for the first occurrence of OLD in the event line. Any character may be used as the delimiter in place of /. The delimiter may be quoted in OLD and NEW with a single backslash. If & appears in NEW, it is replaced with OLD. A single backslash quotes the & in OLD and NEW. If OLD is null, it is set to the last OLD substituted, or, if no previous history substitutions took place, the last STRING in a !?STRING[?] search. If NEW is null, each matching OLD is deleted. The final delimiter is optional if it is the last character on the input line.

&
     Repeat the previous substitution.

g
a
     Cause changes to be applied over the entire event line. This is used in conjunction with s, as in gs/OLD/NEW/, or with &.

G
     Apply the following s or & modifier once to each word in the event.