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