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