1@ignore 2This file documents the user interface to the GNU History library. 3 4Copyright (C) 1988-1999 Free Software Foundation, Inc. 5Authored by Brian Fox and Chet Ramey. 6 7Permission is granted to make and distribute verbatim copies of this manual 8provided the copyright notice and this permission notice are preserved on 9all copies. 10 11Permission is granted to process this file through Tex and print the 12results, provided the printed document carries copying permission notice 13identical to this one except for the removal of this paragraph (this 14paragraph not being relevant to the printed manual). 15 16Permission is granted to copy and distribute modified versions of this 17manual under the conditions for verbatim copying, provided also that the 18GNU Copyright statement is available to the distributee, and provided that 19the entire resulting derived work is distributed under the terms of a 20permission notice identical to this one. 21 22Permission is granted to copy and distribute translations of this manual 23into another language, under the above conditions for modified versions. 24@end ignore 25 26@node Using History Interactively 27@chapter Using History Interactively 28 29@c @ifclear BashFeatures 30@c @defcodeindex bt 31@c @end ifclear 32 33@ifset BashFeatures 34This chapter describes how to use the @sc{gnu} History Library 35interactively, from a user's standpoint. 36It should be considered a user's guide. 37For information on using the @sc{gnu} History Library in other programs, 38see the @sc{gnu} Readline Library Manual. 39@end ifset 40@ifclear BashFeatures 41This chapter describes how to use the GNU History Library interactively, 42from a user's standpoint. It should be considered a user's guide. 43@c For 44@c information on using the GNU History Library in your own programs, 45@c @pxref{Programming with GNU History}. 46@end ifclear 47 48@ifset BashFeatures 49@menu 50* Bash History Facilities:: How Bash lets you manipulate your command 51 history. 52* Bash History Builtins:: The Bash builtin commands that manipulate 53 the command history. 54* History Interaction:: What it feels like using History as a user. 55@end menu 56@end ifset 57@ifclear BashFeatures 58@menu 59* History Interaction:: What it feels like using History as a user. 60@end menu 61@end ifclear 62 63@ifset BashFeatures 64@node Bash History Facilities 65@section Bash History Facilities 66@cindex command history 67@cindex history list 68 69When the @samp{-o history} option to the @code{set} builtin 70is enabled (@pxref{The Set Builtin}), 71the shell provides access to the @var{command history}, 72the list of commands previously typed. 73The value of the @code{HISTSIZE} shell variable is used as the 74number of commands to save in a history list. 75The text of the last @code{$HISTSIZE} 76commands (default 500) is saved. 77The shell stores each command in the history list prior to 78parameter and variable expansion 79but after history expansion is performed, subject to the 80values of the shell variables 81@code{HISTIGNORE} and @code{HISTCONTROL}. 82 83When the shell starts up, the history is initialized from the 84file named by the @code{HISTFILE} variable (default @file{~/.bash_history}). 85The file named by the value of @code{HISTFILE} is truncated, if 86necessary, to contain no more than the number of lines specified by 87the value of the @code{HISTFILESIZE} variable. 88When an interactive shell exits, the last 89@code{$HISTSIZE} lines are copied from the history list to the file 90named by @code{$HISTFILE}. 91If the @code{histappend} shell option is set (@pxref{Bash Builtins}), 92the lines are appended to the history file, 93otherwise the history file is overwritten. 94If @code{HISTFILE} 95is unset, or if the history file is unwritable, the history is 96not saved. After saving the history, the history file is truncated 97to contain no more than @code{$HISTFILESIZE} 98lines. If @code{HISTFILESIZE} is not set, no truncation is performed. 99 100The builtin command @code{fc} may be used to list or edit and re-execute 101a portion of the history list. 102The @code{history} builtin may be used to display or modify the history 103list and manipulate the history file. 104When using command-line editing, search commands 105are available in each editing mode that provide access to the 106history list (@pxref{Commands For History}). 107 108The shell allows control over which commands are saved on the history 109list. The @code{HISTCONTROL} and @code{HISTIGNORE} 110variables may be set to cause the shell to save only a subset of the 111commands entered. 112The @code{cmdhist} 113shell option, if enabled, causes the shell to attempt to save each 114line of a multi-line command in the same history entry, adding 115semicolons where necessary to preserve syntactic correctness. 116The @code{lithist} 117shell option causes the shell to save the command with embedded newlines 118instead of semicolons. 119The @code{shopt} builtin is used to set these options. 120@xref{Bash Builtins}, for a description of @code{shopt}. 121 122@node Bash History Builtins 123@section Bash History Builtins 124@cindex history builtins 125 126Bash provides two builtin commands which manipulate the 127history list and history file. 128 129@table @code 130 131@item fc 132@btindex fc 133@example 134@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]} 135@code{fc -s [@var{pat}=@var{rep}] [@var{command}]} 136@end example 137 138Fix Command. In the first form, a range of commands from @var{first} to 139@var{last} is selected from the history list. Both @var{first} and 140@var{last} may be specified as a string (to locate the most recent 141command beginning with that string) or as a number (an index into the 142history list, where a negative number is used as an offset from the 143current command number). If @var{last} is not specified it is set to 144@var{first}. If @var{first} is not specified it is set to the previous 145command for editing and @minus{}16 for listing. If the @samp{-l} flag is 146given, the commands are listed on standard output. The @samp{-n} flag 147suppresses the command numbers when listing. The @samp{-r} flag 148reverses the order of the listing. Otherwise, the editor given by 149@var{ename} is invoked on a file containing those commands. If 150@var{ename} is not given, the value of the following variable expansion 151is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the 152value of the @code{FCEDIT} variable if set, or the value of the 153@code{EDITOR} variable if that is set, or @code{vi} if neither is set. 154When editing is complete, the edited commands are echoed and executed. 155 156In the second form, @var{command} is re-executed after each instance 157of @var{pat} in the selected command is replaced by @var{rep}. 158 159A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so 160that typing @samp{r cc} runs the last command beginning with @code{cc} 161and typing @samp{r} re-executes the last command (@pxref{Aliases}). 162 163@item history 164@btindex history 165@example 166history [@var{n}] 167history -c 168history -d @var{offset} 169history [-anrw] [@var{filename}] 170history -ps @var{arg} 171@end example 172 173With no options, display the history list with line numbers. 174Lines prefixed with with a @samp{*} have been modified. 175An argument of @var{n} lists only the last @var{n} lines. 176Options, if supplied, have the following meanings: 177 178@table @code 179@item -c 180Clear the history list. This may be combined 181with the other options to replace the history list completely. 182 183@item -d @var{offset} 184Delete the history entry at position @var{offset}. 185@var{offset} should be specified as it appears when the history is 186displayed. 187 188@item -a 189Append the new 190history lines (history lines entered since the beginning of the 191current Bash session) to the history file. 192 193@item -n 194Append the history lines not already read from the history file 195to the current history list. These are lines appended to the history 196file since the beginning of the current Bash session. 197 198@item -r 199Read the current history file and append its contents to 200the history list. 201 202@item -w 203Write out the current history to the history file. 204 205@item -p 206Perform history substitution on the @var{arg}s and display the result 207on the standard output, without storing the results in the history list. 208 209@item -s 210The @var{arg}s are added to the end of 211the history list as a single entry. 212 213@end table 214 215When any of the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} options is 216used, if @var{filename} 217is given, then it is used as the history file. If not, then 218the value of the @code{HISTFILE} variable is used. 219 220@end table 221@end ifset 222 223@node History Interaction 224@section History Expansion 225@cindex history expansion 226 227The History library provides a history expansion feature that is similar 228to the history expansion provided by @code{csh}. This section 229describes the syntax used to manipulate the history information. 230 231History expansions introduce words from the history list into 232the input stream, making it easy to repeat commands, insert the 233arguments to a previous command into the current input line, or 234fix errors in previous commands quickly. 235 236History expansion takes place in two parts. The first is to determine 237which line from the history list should be used during substitution. 238The second is to select portions of that line for inclusion into the 239current one. The line selected from the history is called the 240@dfn{event}, and the portions of that line that are acted upon are 241called @dfn{words}. Various @dfn{modifiers} are available to manipulate 242the selected words. The line is broken into words in the same fashion 243that Bash does, so that several words 244surrounded by quotes are considered one word. 245History expansions are introduced by the appearance of the 246history expansion character, which is @samp{!} by default. 247@ifset BashFeatures 248Only @samp{\} and @samp{'} may be used to escape the history expansion 249character. 250@end ifset 251 252@ifset BashFeatures 253Several shell options settable with the @code{shopt} 254builtin (@pxref{Bash Builtins}) may be used to tailor 255the behavior of history expansion. If the 256@code{histverify} shell option is enabled, and Readline 257is being used, history substitutions are not immediately passed to 258the shell parser. 259Instead, the expanded line is reloaded into the Readline 260editing buffer for further modification. 261If Readline is being used, and the @code{histreedit} 262shell option is enabled, a failed history expansion will be 263reloaded into the Readline editing buffer for correction. 264The @samp{-p} option to the @code{history} builtin command 265may be used to see what a history expansion will do before using it. 266The @samp{-s} option to the @code{history} builtin may be used to 267add commands to the end of the history list without actually executing 268them, so that they are available for subsequent recall. 269This is most useful in conjunction with Readline. 270 271The shell allows control of the various characters used by the 272history expansion mechanism with the @code{histchars} variable. 273@end ifset 274 275@menu 276* Event Designators:: How to specify which history line to use. 277* Word Designators:: Specifying which words are of interest. 278* Modifiers:: Modifying the results of substitution. 279@end menu 280 281@node Event Designators 282@subsection Event Designators 283@cindex event designators 284 285An event designator is a reference to a command line entry in the 286history list. 287@cindex history events 288 289@table @asis 290 291@item @code{!} 292Start a history substitution, except when followed by a space, tab, 293the end of the line, @samp{=} or @samp{(}. 294 295@item @code{!@var{n}} 296Refer to command line @var{n}. 297 298@item @code{!-@var{n}} 299Refer to the command @var{n} lines back. 300 301@item @code{!!} 302Refer to the previous command. This is a synonym for @samp{!-1}. 303 304@item @code{!@var{string}} 305Refer to the most recent command starting with @var{string}. 306 307@item @code{!?@var{string}[?]} 308Refer to the most recent command containing @var{string}. The trailing 309@samp{?} may be omitted if the @var{string} is followed immediately by 310a newline. 311 312@item @code{^@var{string1}^@var{string2}^} 313Quick Substitution. Repeat the last command, replacing @var{string1} 314with @var{string2}. Equivalent to 315@code{!!:s/@var{string1}/@var{string2}/}. 316 317@item @code{!#} 318The entire command line typed so far. 319 320@end table 321 322@node Word Designators 323@subsection Word Designators 324 325Word designators are used to select desired words from the event. 326A @samp{:} separates the event specification from the word designator. It 327may be omitted if the word designator begins with a @samp{^}, @samp{$}, 328@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning 329of the line, with the first word being denoted by 0 (zero). Words are 330inserted into the current line separated by single spaces. 331 332@need 0.75 333For example, 334 335@table @code 336@item !! 337designates the preceding command. When you type this, the preceding 338command is repeated in toto. 339 340@item !!:$ 341designates the last argument of the preceding command. This may be 342shortened to @code{!$}. 343 344@item !fi:2 345designates the second argument of the most recent command starting with 346the letters @code{fi}. 347@end table 348 349@need 0.75 350Here are the word designators: 351 352@table @code 353 354@item 0 (zero) 355The @code{0}th word. For many applications, this is the command word. 356 357@item @var{n} 358The @var{n}th word. 359 360@item ^ 361The first argument; that is, word 1. 362 363@item $ 364The last argument. 365 366@item % 367The word matched by the most recent @samp{?@var{string}?} search. 368 369@item @var{x}-@var{y} 370A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}. 371 372@item * 373All of the words, except the @code{0}th. This is a synonym for @samp{1-$}. 374It is not an error to use @samp{*} if there is just one word in the event; 375the empty string is returned in that case. 376 377@item @var{x}* 378Abbreviates @samp{@var{x}-$} 379 380@item @var{x}- 381Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word. 382 383@end table 384 385If a word designator is supplied without an event specification, the 386previous command is used as the event. 387 388@node Modifiers 389@subsection Modifiers 390 391After the optional word designator, you can add a sequence of one or more 392of the following modifiers, each preceded by a @samp{:}. 393 394@table @code 395 396@item h 397Remove a trailing pathname component, leaving only the head. 398 399@item t 400Remove all leading pathname components, leaving the tail. 401 402@item r 403Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving 404the basename. 405 406@item e 407Remove all but the trailing suffix. 408 409@item p 410Print the new command but do not execute it. 411 412@ifset BashFeatures 413@item q 414Quote the substituted words, escaping further substitutions. 415 416@item x 417Quote the substituted words as with @samp{q}, 418but break into words at spaces, tabs, and newlines. 419@end ifset 420 421@item s/@var{old}/@var{new}/ 422Substitute @var{new} for the first occurrence of @var{old} in the 423event line. Any delimiter may be used in place of @samp{/}. 424The delimiter may be quoted in @var{old} and @var{new} 425with a single backslash. If @samp{&} appears in @var{new}, 426it is replaced by @var{old}. A single backslash will quote 427the @samp{&}. The final delimiter is optional if it is the last 428character on the input line. 429 430@item & 431Repeat the previous substitution. 432 433@item g 434Cause changes to be applied over the entire event line. Used in 435conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/}, 436or with @samp{&}. 437 438@end table 439