1136644Sache@ignore 2136644SacheThis file documents the user interface to the GNU History library. 3136644Sache 4165670SacheCopyright (C) 1988-2006 Free Software Foundation, Inc. 5136644SacheAuthored by Brian Fox and Chet Ramey. 6136644Sache 7136644SachePermission is granted to make and distribute verbatim copies of this manual 8136644Sacheprovided the copyright notice and this permission notice are preserved on 9136644Sacheall copies. 10136644Sache 11136644SachePermission is granted to process this file through Tex and print the 12136644Sacheresults, provided the printed document carries copying permission notice 13136644Sacheidentical to this one except for the removal of this paragraph (this 14136644Sacheparagraph not being relevant to the printed manual). 15136644Sache 16136644SachePermission is granted to copy and distribute modified versions of this 17136644Sachemanual under the conditions for verbatim copying, provided also that the 18136644SacheGNU Copyright statement is available to the distributee, and provided that 19136644Sachethe entire resulting derived work is distributed under the terms of a 20136644Sachepermission notice identical to this one. 21136644Sache 22136644SachePermission is granted to copy and distribute translations of this manual 23136644Sacheinto another language, under the above conditions for modified versions. 24136644Sache@end ignore 25136644Sache 26136644Sache@node Using History Interactively 27136644Sache@chapter Using History Interactively 28136644Sache 29136644Sache@ifclear BashFeatures 30136644Sache@defcodeindex bt 31136644Sache@end ifclear 32136644Sache 33136644Sache@ifset BashFeatures 34136644SacheThis chapter describes how to use the @sc{gnu} History Library 35136644Sacheinteractively, from a user's standpoint. 36136644SacheIt should be considered a user's guide. 37136644SacheFor information on using the @sc{gnu} History Library in other programs, 38136644Sachesee the @sc{gnu} Readline Library Manual. 39136644Sache@end ifset 40136644Sache@ifclear BashFeatures 41136644SacheThis chapter describes how to use the @sc{gnu} History Library interactively, 42136644Sachefrom a user's standpoint. It should be considered a user's guide. For 43136644Sacheinformation on using the @sc{gnu} History Library in your own programs, 44136644Sache@pxref{Programming with GNU History}. 45136644Sache@end ifclear 46136644Sache 47136644Sache@ifset BashFeatures 48136644Sache@menu 49136644Sache* Bash History Facilities:: How Bash lets you manipulate your command 50136644Sache history. 51136644Sache* Bash History Builtins:: The Bash builtin commands that manipulate 52136644Sache the command history. 53136644Sache* History Interaction:: What it feels like using History as a user. 54136644Sache@end menu 55136644Sache@end ifset 56136644Sache@ifclear BashFeatures 57136644Sache@menu 58136644Sache* History Interaction:: What it feels like using History as a user. 59136644Sache@end menu 60136644Sache@end ifclear 61136644Sache 62136644Sache@ifset BashFeatures 63136644Sache@node Bash History Facilities 64136644Sache@section Bash History Facilities 65136644Sache@cindex command history 66136644Sache@cindex history list 67136644Sache 68136644SacheWhen the @option{-o history} option to the @code{set} builtin 69136644Sacheis enabled (@pxref{The Set Builtin}), 70136644Sachethe shell provides access to the @dfn{command history}, 71136644Sachethe list of commands previously typed. 72136644SacheThe value of the @env{HISTSIZE} shell variable is used as the 73136644Sachenumber of commands to save in a history list. 74136644SacheThe text of the last @env{$HISTSIZE} 75136644Sachecommands (default 500) is saved. 76136644SacheThe shell stores each command in the history list prior to 77136644Sacheparameter and variable expansion 78136644Sachebut after history expansion is performed, subject to the 79136644Sachevalues of the shell variables 80136644Sache@env{HISTIGNORE} and @env{HISTCONTROL}. 81136644Sache 82136644SacheWhen the shell starts up, the history is initialized from the 83136644Sachefile named by the @env{HISTFILE} variable (default @file{~/.bash_history}). 84136644SacheThe file named by the value of @env{HISTFILE} is truncated, if 85136644Sachenecessary, to contain no more than the number of lines specified by 86136644Sachethe value of the @env{HISTFILESIZE} variable. 87136644SacheWhen an interactive shell exits, the last 88136644Sache@env{$HISTSIZE} lines are copied from the history list to the file 89136644Sachenamed by @env{$HISTFILE}. 90136644SacheIf the @code{histappend} shell option is set (@pxref{Bash Builtins}), 91136644Sachethe lines are appended to the history file, 92136644Sacheotherwise the history file is overwritten. 93136644SacheIf @env{HISTFILE} 94136644Sacheis unset, or if the history file is unwritable, the history is 95136644Sachenot saved. After saving the history, the history file is truncated 96136644Sacheto contain no more than @env{$HISTFILESIZE} 97136644Sachelines. If @env{HISTFILESIZE} is not set, no truncation is performed. 98136644Sache 99136644SacheIf the @env{HISTTIMEFORMAT} is set, the time stamp information 100136644Sacheassociated with each history entry is written to the history file. 101136644Sache 102136644SacheThe builtin command @code{fc} may be used to list or edit and re-execute 103136644Sachea portion of the history list. 104136644SacheThe @code{history} builtin may be used to display or modify the history 105136644Sachelist and manipulate the history file. 106136644SacheWhen using command-line editing, search commands 107136644Sacheare available in each editing mode that provide access to the 108136644Sachehistory list (@pxref{Commands For History}). 109136644Sache 110136644SacheThe shell allows control over which commands are saved on the history 111136644Sachelist. The @env{HISTCONTROL} and @env{HISTIGNORE} 112136644Sachevariables may be set to cause the shell to save only a subset of the 113136644Sachecommands entered. 114136644SacheThe @code{cmdhist} 115136644Sacheshell option, if enabled, causes the shell to attempt to save each 116136644Sacheline of a multi-line command in the same history entry, adding 117136644Sachesemicolons where necessary to preserve syntactic correctness. 118136644SacheThe @code{lithist} 119136644Sacheshell option causes the shell to save the command with embedded newlines 120136644Sacheinstead of semicolons. 121136644SacheThe @code{shopt} builtin is used to set these options. 122136644Sache@xref{Bash Builtins}, for a description of @code{shopt}. 123136644Sache 124136644Sache@node Bash History Builtins 125136644Sache@section Bash History Builtins 126136644Sache@cindex history builtins 127136644Sache 128136644SacheBash provides two builtin commands which manipulate the 129136644Sachehistory list and history file. 130136644Sache 131136644Sache@table @code 132136644Sache 133136644Sache@item fc 134136644Sache@btindex fc 135136644Sache@example 136136644Sache@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]} 137136644Sache@code{fc -s [@var{pat}=@var{rep}] [@var{command}]} 138136644Sache@end example 139136644Sache 140136644SacheFix Command. In the first form, a range of commands from @var{first} to 141136644Sache@var{last} is selected from the history list. Both @var{first} and 142136644Sache@var{last} may be specified as a string (to locate the most recent 143136644Sachecommand beginning with that string) or as a number (an index into the 144136644Sachehistory list, where a negative number is used as an offset from the 145136644Sachecurrent command number). If @var{last} is not specified it is set to 146136644Sache@var{first}. If @var{first} is not specified it is set to the previous 147136644Sachecommand for editing and @minus{}16 for listing. If the @option{-l} flag is 148136644Sachegiven, the commands are listed on standard output. The @option{-n} flag 149136644Sachesuppresses the command numbers when listing. The @option{-r} flag 150136644Sachereverses the order of the listing. Otherwise, the editor given by 151136644Sache@var{ename} is invoked on a file containing those commands. If 152136644Sache@var{ename} is not given, the value of the following variable expansion 153136644Sacheis used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the 154136644Sachevalue of the @env{FCEDIT} variable if set, or the value of the 155136644Sache@env{EDITOR} variable if that is set, or @code{vi} if neither is set. 156136644SacheWhen editing is complete, the edited commands are echoed and executed. 157136644Sache 158136644SacheIn the second form, @var{command} is re-executed after each instance 159136644Sacheof @var{pat} in the selected command is replaced by @var{rep}. 160136644Sache 161136644SacheA useful alias to use with the @code{fc} command is @code{r='fc -s'}, so 162136644Sachethat typing @samp{r cc} runs the last command beginning with @code{cc} 163136644Sacheand typing @samp{r} re-executes the last command (@pxref{Aliases}). 164136644Sache 165136644Sache@item history 166136644Sache@btindex history 167136644Sache@example 168136644Sachehistory [@var{n}] 169136644Sachehistory -c 170136644Sachehistory -d @var{offset} 171136644Sachehistory [-anrw] [@var{filename}] 172136644Sachehistory -ps @var{arg} 173136644Sache@end example 174136644Sache 175136644SacheWith no options, display the history list with line numbers. 176136644SacheLines prefixed with a @samp{*} have been modified. 177136644SacheAn argument of @var{n} lists only the last @var{n} lines. 178136644SacheIf the shell variable @env{HISTTIMEFORMAT} is set and not null, 179136644Sacheit is used as a format string for @var{strftime} to display 180136644Sachethe time stamp associated with each displayed history entry. 181136644SacheNo intervening blank is printed between the formatted time stamp 182136644Sacheand the history line. 183136644Sache 184136644SacheOptions, if supplied, have the following meanings: 185136644Sache 186136644Sache@table @code 187136644Sache@item -c 188136644SacheClear the history list. This may be combined 189136644Sachewith the other options to replace the history list completely. 190136644Sache 191136644Sache@item -d @var{offset} 192136644SacheDelete the history entry at position @var{offset}. 193136644Sache@var{offset} should be specified as it appears when the history is 194136644Sachedisplayed. 195136644Sache 196136644Sache@item -a 197136644SacheAppend the new 198136644Sachehistory lines (history lines entered since the beginning of the 199136644Sachecurrent Bash session) to the history file. 200136644Sache 201136644Sache@item -n 202136644SacheAppend the history lines not already read from the history file 203136644Sacheto the current history list. These are lines appended to the history 204136644Sachefile since the beginning of the current Bash session. 205136644Sache 206136644Sache@item -r 207136644SacheRead the current history file and append its contents to 208136644Sachethe history list. 209136644Sache 210136644Sache@item -w 211136644SacheWrite out the current history to the history file. 212136644Sache 213136644Sache@item -p 214136644SachePerform history substitution on the @var{arg}s and display the result 215136644Sacheon the standard output, without storing the results in the history list. 216136644Sache 217136644Sache@item -s 218136644SacheThe @var{arg}s are added to the end of 219136644Sachethe history list as a single entry. 220136644Sache 221136644Sache@end table 222136644Sache 223136644SacheWhen any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options is 224136644Sacheused, if @var{filename} 225136644Sacheis given, then it is used as the history file. If not, then 226136644Sachethe value of the @env{HISTFILE} variable is used. 227136644Sache 228136644Sache@end table 229136644Sache@end ifset 230136644Sache 231136644Sache@node History Interaction 232136644Sache@section History Expansion 233136644Sache@cindex history expansion 234136644Sache 235136644SacheThe History library provides a history expansion feature that is similar 236136644Sacheto the history expansion provided by @code{csh}. This section 237136644Sachedescribes the syntax used to manipulate the history information. 238136644Sache 239136644SacheHistory expansions introduce words from the history list into 240136644Sachethe input stream, making it easy to repeat commands, insert the 241136644Sachearguments to a previous command into the current input line, or 242136644Sachefix errors in previous commands quickly. 243136644Sache 244136644SacheHistory expansion takes place in two parts. The first is to determine 245136644Sachewhich line from the history list should be used during substitution. 246136644SacheThe second is to select portions of that line for inclusion into the 247136644Sachecurrent one. The line selected from the history is called the 248136644Sache@dfn{event}, and the portions of that line that are acted upon are 249136644Sachecalled @dfn{words}. Various @dfn{modifiers} are available to manipulate 250136644Sachethe selected words. The line is broken into words in the same fashion 251136644Sachethat Bash does, so that several words 252136644Sachesurrounded by quotes are considered one word. 253136644SacheHistory expansions are introduced by the appearance of the 254136644Sachehistory expansion character, which is @samp{!} by default. 255136644Sache@ifset BashFeatures 256136644SacheOnly @samp{\} and @samp{'} may be used to escape the history expansion 257136644Sachecharacter. 258136644Sache@end ifset 259136644Sache 260136644Sache@ifset BashFeatures 261136644SacheSeveral shell options settable with the @code{shopt} 262136644Sachebuiltin (@pxref{Bash Builtins}) may be used to tailor 263136644Sachethe behavior of history expansion. If the 264136644Sache@code{histverify} shell option is enabled, and Readline 265136644Sacheis being used, history substitutions are not immediately passed to 266136644Sachethe shell parser. 267136644SacheInstead, the expanded line is reloaded into the Readline 268136644Sacheediting buffer for further modification. 269136644SacheIf Readline is being used, and the @code{histreedit} 270136644Sacheshell option is enabled, a failed history expansion will be 271136644Sachereloaded into the Readline editing buffer for correction. 272136644SacheThe @option{-p} option to the @code{history} builtin command 273136644Sachemay be used to see what a history expansion will do before using it. 274136644SacheThe @option{-s} option to the @code{history} builtin may be used to 275136644Sacheadd commands to the end of the history list without actually executing 276136644Sachethem, so that they are available for subsequent recall. 277136644SacheThis is most useful in conjunction with Readline. 278136644Sache 279136644SacheThe shell allows control of the various characters used by the 280136644Sachehistory expansion mechanism with the @code{histchars} variable. 281136644Sache@end ifset 282136644Sache 283136644Sache@menu 284136644Sache* Event Designators:: How to specify which history line to use. 285136644Sache* Word Designators:: Specifying which words are of interest. 286136644Sache* Modifiers:: Modifying the results of substitution. 287136644Sache@end menu 288136644Sache 289136644Sache@node Event Designators 290136644Sache@subsection Event Designators 291136644Sache@cindex event designators 292136644Sache 293136644SacheAn event designator is a reference to a command line entry in the 294136644Sachehistory list. 295136644Sache@cindex history events 296136644Sache 297136644Sache@table @asis 298136644Sache 299136644Sache@item @code{!} 300136644Sache@ifset BashFeatures 301136644SacheStart a history substitution, except when followed by a space, tab, 302136644Sachethe end of the line, @samp{=} or @samp{(} (when the 303136644Sache@code{extglob} shell option is enabled using the @code{shopt} builtin). 304136644Sache@end ifset 305136644Sache@ifclear BashFeatures 306136644SacheStart a history substitution, except when followed by a space, tab, 307136644Sachethe end of the line, or @samp{=}. 308136644Sache@end ifclear 309136644Sache 310136644Sache@item @code{!@var{n}} 311136644SacheRefer to command line @var{n}. 312136644Sache 313136644Sache@item @code{!-@var{n}} 314136644SacheRefer to the command @var{n} lines back. 315136644Sache 316136644Sache@item @code{!!} 317136644SacheRefer to the previous command. This is a synonym for @samp{!-1}. 318136644Sache 319136644Sache@item @code{!@var{string}} 320136644SacheRefer to the most recent command starting with @var{string}. 321136644Sache 322136644Sache@item @code{!?@var{string}[?]} 323136644SacheRefer to the most recent command containing @var{string}. The trailing 324136644Sache@samp{?} may be omitted if the @var{string} is followed immediately by 325136644Sachea newline. 326136644Sache 327136644Sache@item @code{^@var{string1}^@var{string2}^} 328136644SacheQuick Substitution. Repeat the last command, replacing @var{string1} 329136644Sachewith @var{string2}. Equivalent to 330136644Sache@code{!!:s/@var{string1}/@var{string2}/}. 331136644Sache 332136644Sache@item @code{!#} 333136644SacheThe entire command line typed so far. 334136644Sache 335136644Sache@end table 336136644Sache 337136644Sache@node Word Designators 338136644Sache@subsection Word Designators 339136644Sache 340136644SacheWord designators are used to select desired words from the event. 341136644SacheA @samp{:} separates the event specification from the word designator. It 342136644Sachemay be omitted if the word designator begins with a @samp{^}, @samp{$}, 343136644Sache@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning 344136644Sacheof the line, with the first word being denoted by 0 (zero). Words are 345136644Sacheinserted into the current line separated by single spaces. 346136644Sache 347136644Sache@need 0.75 348136644SacheFor example, 349136644Sache 350136644Sache@table @code 351136644Sache@item !! 352136644Sachedesignates the preceding command. When you type this, the preceding 353136644Sachecommand is repeated in toto. 354136644Sache 355136644Sache@item !!:$ 356136644Sachedesignates the last argument of the preceding command. This may be 357136644Sacheshortened to @code{!$}. 358136644Sache 359136644Sache@item !fi:2 360136644Sachedesignates the second argument of the most recent command starting with 361136644Sachethe letters @code{fi}. 362136644Sache@end table 363136644Sache 364136644Sache@need 0.75 365136644SacheHere are the word designators: 366136644Sache 367136644Sache@table @code 368136644Sache 369136644Sache@item 0 (zero) 370136644SacheThe @code{0}th word. For many applications, this is the command word. 371136644Sache 372136644Sache@item @var{n} 373136644SacheThe @var{n}th word. 374136644Sache 375136644Sache@item ^ 376136644SacheThe first argument; that is, word 1. 377136644Sache 378136644Sache@item $ 379136644SacheThe last argument. 380136644Sache 381136644Sache@item % 382136644SacheThe word matched by the most recent @samp{?@var{string}?} search. 383136644Sache 384136644Sache@item @var{x}-@var{y} 385136644SacheA range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}. 386136644Sache 387136644Sache@item * 388136644SacheAll of the words, except the @code{0}th. This is a synonym for @samp{1-$}. 389136644SacheIt is not an error to use @samp{*} if there is just one word in the event; 390136644Sachethe empty string is returned in that case. 391136644Sache 392136644Sache@item @var{x}* 393136644SacheAbbreviates @samp{@var{x}-$} 394136644Sache 395136644Sache@item @var{x}- 396136644SacheAbbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word. 397136644Sache 398136644Sache@end table 399136644Sache 400136644SacheIf a word designator is supplied without an event specification, the 401136644Sacheprevious command is used as the event. 402136644Sache 403136644Sache@node Modifiers 404136644Sache@subsection Modifiers 405136644Sache 406136644SacheAfter the optional word designator, you can add a sequence of one or more 407136644Sacheof the following modifiers, each preceded by a @samp{:}. 408136644Sache 409136644Sache@table @code 410136644Sache 411136644Sache@item h 412136644SacheRemove a trailing pathname component, leaving only the head. 413136644Sache 414136644Sache@item t 415136644SacheRemove all leading pathname components, leaving the tail. 416136644Sache 417136644Sache@item r 418136644SacheRemove a trailing suffix of the form @samp{.@var{suffix}}, leaving 419136644Sachethe basename. 420136644Sache 421136644Sache@item e 422136644SacheRemove all but the trailing suffix. 423136644Sache 424136644Sache@item p 425136644SachePrint the new command but do not execute it. 426136644Sache 427136644Sache@ifset BashFeatures 428136644Sache@item q 429136644SacheQuote the substituted words, escaping further substitutions. 430136644Sache 431136644Sache@item x 432136644SacheQuote the substituted words as with @samp{q}, 433136644Sachebut break into words at spaces, tabs, and newlines. 434136644Sache@end ifset 435136644Sache 436136644Sache@item s/@var{old}/@var{new}/ 437136644SacheSubstitute @var{new} for the first occurrence of @var{old} in the 438136644Sacheevent line. Any delimiter may be used in place of @samp{/}. 439136644SacheThe delimiter may be quoted in @var{old} and @var{new} 440136644Sachewith a single backslash. If @samp{&} appears in @var{new}, 441136644Sacheit is replaced by @var{old}. A single backslash will quote 442136644Sachethe @samp{&}. The final delimiter is optional if it is the last 443136644Sachecharacter on the input line. 444136644Sache 445136644Sache@item & 446136644SacheRepeat the previous substitution. 447136644Sache 448136644Sache@item g 449136644Sache@itemx a 450136644SacheCause changes to be applied over the entire event line. Used in 451136644Sacheconjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/}, 452136644Sacheor with @samp{&}. 453136644Sache 454136644Sache@item G 455136644SacheApply the following @samp{s} modifier once to each word in the event. 456136644Sache 457136644Sache@end table 458