lib/readline/doc/hsuser.texinfo

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