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