1: @ignore
2: This file documents the user interface to the GNU History library.
3:
4: Copyright (C) 1988--2020 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 a shell with history enabled 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 not saved.
95: After saving the history, the history file is truncated
96: to contain no more than @env{$HISTFILESIZE} lines.
97: If @env{HISTFILESIZE} is unset, or set to null, a non-numeric value, or
98: a numeric value less than zero, the history file is not truncated.
99:
100: If the @env{HISTTIMEFORMAT} is set, the time stamp information
101: associated with each history entry is written to the history file,
102: marked with the history comment character.
103: When the history file is read, lines beginning with the history
104: comment character followed immediately by a digit are interpreted
105: as timestamps for the following history entry.
106:
107: The builtin command @code{fc} may be used to list or edit and re-execute
108: a portion of the history list.
109: The @code{history} builtin may be used to display or modify the history
110: list and manipulate the history file.
111: When using command-line editing, search commands
112: are available in each editing mode that provide access to the
113: history list (@pxref{Commands For History}).
114:
115: The shell allows control over which commands are saved on the history
116: list. The @env{HISTCONTROL} and @env{HISTIGNORE}
117: variables may be set to cause the shell to save only a subset of the
118: commands entered.
119: The @code{cmdhist}
120: shell option, if enabled, causes the shell to attempt to save each
121: line of a multi-line command in the same history entry, adding
122: semicolons where necessary to preserve syntactic correctness.
123: The @code{lithist}
124: shell option causes the shell to save the command with embedded newlines
125: instead of semicolons.
126: The @code{shopt} builtin is used to set these options.
127: @xref{The Shopt Builtin}, for a description of @code{shopt}.
128:
129: @node Bash History Builtins
130: @section Bash History Builtins
131: @cindex history builtins
132:
133: Bash provides two builtin commands which manipulate the
134: history list and history file.
135:
136: @table @code
137:
138: @item fc
139: @btindex fc
140: @example
141: @code{fc [-e @var{ename}] [-lnr] [@var{first}] [@var{last}]}
142: @code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
143: @end example
144:
145: The first form selects a range of commands from @var{first} to
146: @var{last} from the history list and displays or edits and re-executes
147: them.
148: Both @var{first} and
149: @var{last} may be specified as a string (to locate the most recent
150: command beginning with that string) or as a number (an index into the
151: history list, where a negative number is used as an offset from the
152: current command number).
153:
154: When listing, a @var{first} or @var{last} of 0 is equivalent to -1
155: and -0 is equivalent to the current command (usually the @code{fc}
156: command);
157: otherwise 0 is equivalent to -1 and -0 is invalid.
158:
159: If @var{last} is not specified, it is set to
160: @var{first}. If @var{first} is not specified, it is set to the previous
161: command for editing and @minus{}16 for listing. If the @option{-l} flag is
162: given, the commands are listed on standard output. The @option{-n} flag
163: suppresses the command numbers when listing. The @option{-r} flag
164: reverses the order of the listing. Otherwise, the editor given by
165: @var{ename} is invoked on a file containing those commands. If
166: @var{ename} is not given, the value of the following variable expansion
167: is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
168: value of the @env{FCEDIT} variable if set, or the value of the
169: @env{EDITOR} variable if that is set, or @code{vi} if neither is set.
170: When editing is complete, the edited commands are echoed and executed.
171:
172: In the second form, @var{command} is re-executed after each instance
173: of @var{pat} in the selected command is replaced by @var{rep}.
174: @var{command} is interpreted the same as @var{first} above.
175:
176: A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
177: that typing @samp{r cc} runs the last command beginning with @code{cc}
178: and typing @samp{r} re-executes the last command (@pxref{Aliases}).
179:
180: @item history
181: @btindex history
182: @example
183: history [@var{n}]
184: history -c
185: history -d @var{offset}
186: history -d @var{start}-@var{end}
187: history [-anrw] [@var{filename}]
188: history -ps @var{arg}
189: @end example
190:
191: With no options, display the history list with line numbers.
192: Lines prefixed with a @samp{*} have been modified.
193: An argument of @var{n} lists only the last @var{n} lines.
194: If the shell variable @env{HISTTIMEFORMAT} is set and not null,
195: it is used as a format string for @var{strftime} to display
196: the time stamp associated with each displayed history entry.
197: No intervening blank is printed between the formatted time stamp
198: and the history line.
199:
200: Options, if supplied, have the following meanings:
201:
202: @table @code
203: @item -c
204: Clear the history list. This may be combined
205: with the other options to replace the history list completely.
206:
207: @item -d @var{offset}
208: Delete the history entry at position @var{offset}.
209: If @var{offset} is positive, it should be specified as it appears when
210: the history is displayed.
211: If @var{offset} is negative, it is interpreted as relative to one greater
212: than the last history position, so negative indices count back from the
213: end of the history, and an index of @samp{-1} refers to the current
214: @code{history -d} command.
215:
216: @item -d @var{start}-@var{end}
217: Delete the history entries between positions @var{start} and @var{end},
218: inclusive. Positive and negative values for @var{start} and @var{end}
219: are interpreted as described above.
220:
221: @item -a
222: Append the new history lines to the history file.
223: These are history lines entered since the beginning of the current
224: Bash session, but not already appended to the history file.
225:
226: @item -n
227: Append the history lines not already read from the history file
228: to the current history list. These are lines appended to the history
229: file since the beginning of the current Bash session.
230:
231: @item -r
232: Read the history file and append its contents to
233: the history list.
234:
235: @item -w
236: Write out the current history list to the history file.
237:
238: @item -p
239: Perform history substitution on the @var{arg}s and display the result
240: on the standard output, without storing the results in the history list.
241:
242: @item -s
243: The @var{arg}s are added to the end of
244: the history list as a single entry.
245:
246: @end table
247:
248: When any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options is
249: used, if @var{filename}
250: is given, then it is used as the history file. If not, then
251: the value of the @env{HISTFILE} variable is used.
252:
253: @end table
254: @end ifset
255:
256: @node History Interaction
257: @section History Expansion
258: @cindex history expansion
259:
260: The History library provides a history expansion feature that is similar
261: to the history expansion provided by @code{csh}. This section
262: describes the syntax used to manipulate the history information.
263:
264: History expansions introduce words from the history list into
265: the input stream, making it easy to repeat commands, insert the
266: arguments to a previous command into the current input line, or
267: fix errors in previous commands quickly.
268:
269: @ifset BashFeatures
270: History expansion is performed immediately after a complete line
271: is read, before the shell breaks it into words, and is performed
272: on each line individually. Bash attempts to inform the history
273: expansion functions about quoting still in effect from previous lines.
274: @end ifset
275:
276: History expansion takes place in two parts. The first is to determine
277: which line from the history list should be used during substitution.
278: The second is to select portions of that line for inclusion into the
279: current one. The line selected from the history is called the
280: @dfn{event}, and the portions of that line that are acted upon are
281: called @dfn{words}. Various @dfn{modifiers} are available to manipulate
282: the selected words. The line is broken into words in the same fashion
283: that Bash does, so that several words
284: surrounded by quotes are considered one word.
285: History expansions are introduced by the appearance of the
286: history expansion character, which is @samp{!} by default.
287:
288: History expansion implements shell-like quoting conventions:
289: a backslash can be used to remove the special handling for the next character;
290: single quotes enclose verbatim sequences of characters, and can be used to
291: inhibit history expansion;
292: and characters enclosed within double quotes may be subject to history
293: expansion, since backslash can escape the history expansion character,
294: but single quotes may not, since they are not treated specially within
295: double quotes.
296:
297: @ifset BashFeatures
298: When using the shell, only @samp{\} and @samp{'} may be used to escape the
299: history expansion character, but the history expansion character is
300: also treated as quoted if it immediately precedes the closing double quote
301: in a double-quoted string.
302: @end ifset
303:
304: @ifset BashFeatures
305: Several shell options settable with the @code{shopt}
306: builtin (@pxref{The Shopt Builtin}) may be used to tailor
307: the behavior of history expansion. If the
308: @code{histverify} shell option is enabled, and Readline
309: is being used, history substitutions are not immediately passed to
310: the shell parser.
311: Instead, the expanded line is reloaded into the Readline
312: editing buffer for further modification.
313: If Readline is being used, and the @code{histreedit}
314: shell option is enabled, a failed history expansion will be
315: reloaded into the Readline editing buffer for correction.
316: The @option{-p} option to the @code{history} builtin command
317: may be used to see what a history expansion will do before using it.
318: The @option{-s} option to the @code{history} builtin may be used to
319: add commands to the end of the history list without actually executing
320: them, so that they are available for subsequent recall.
321: This is most useful in conjunction with Readline.
322:
323: The shell allows control of the various characters used by the
324: history expansion mechanism with the @code{histchars} variable,
325: as explained above (@pxref{Bash Variables}). The shell uses
326: the history comment character to mark history timestamps when
327: writing the history file.
328: @end ifset
329:
330: @menu
331: * Event Designators:: How to specify which history line to use.
332: * Word Designators:: Specifying which words are of interest.
333: * Modifiers:: Modifying the results of substitution.
334: @end menu
335:
336: @node Event Designators
337: @subsection Event Designators
338: @cindex event designators
339:
340: An event designator is a reference to a command line entry in the
341: history list.
342: Unless the reference is absolute, events are relative to the current
343: position in the history list.
344: @cindex history events
345:
346: @table @asis
347:
348: @item @code{!}
349: @ifset BashFeatures
350: Start a history substitution, except when followed by a space, tab,
351: the end of the line, @samp{=} or @samp{(} (when the
352: @code{extglob} shell option is enabled using the @code{shopt} builtin).
353: @end ifset
354: @ifclear BashFeatures
355: Start a history substitution, except when followed by a space, tab,
356: the end of the line, or @samp{=}.
357: @end ifclear
358:
359: @item @code{!@var{n}}
360: Refer to command line @var{n}.
361:
362: @item @code{!-@var{n}}
363: Refer to the command @var{n} lines back.
364:
365: @item @code{!!}
366: Refer to the previous command. This is a synonym for @samp{!-1}.
367:
368: @item @code{!@var{string}}
369: Refer to the most recent command
370: preceding the current position in the history list
371: starting with @var{string}.
372:
373: @item @code{!?@var{string}[?]}
374: Refer to the most recent command
375: preceding the current position in the history list
376: containing @var{string}.
377: The trailing
378: @samp{?} may be omitted if the @var{string} is followed immediately by
379: a newline.
380: If @var{string} is missing, the string from the most recent search is used;
381: it is an error if there is no previous search string.
382:
383: @item @code{^@var{string1}^@var{string2}^}
384: Quick Substitution. Repeat the last command, replacing @var{string1}
385: with @var{string2}. Equivalent to
386: @code{!!:s^@var{string1}^@var{string2}^}.
387:
388: @item @code{!#}
389: The entire command line typed so far.
390:
391: @end table
392:
393: @node Word Designators
394: @subsection Word Designators
395:
396: Word designators are used to select desired words from the event.
397: A @samp{:} separates the event specification from the word designator. It
398: may be omitted if the word designator begins with a @samp{^}, @samp{$},
399: @samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning
400: of the line, with the first word being denoted by 0 (zero). Words are
401: inserted into the current line separated by single spaces.
402:
403: @need 0.75
404: For example,
405:
406: @table @code
407: @item !!
408: designates the preceding command. When you type this, the preceding
409: command is repeated in toto.
410:
411: @item !!:$
412: designates the last argument of the preceding command. This may be
413: shortened to @code{!$}.
414:
415: @item !fi:2
416: designates the second argument of the most recent command starting with
417: the letters @code{fi}.
418: @end table
419:
420: @need 0.75
421: Here are the word designators:
422:
423: @table @code
424:
425: @item 0 (zero)
426: The @code{0}th word. For many applications, this is the command word.
427:
428: @item @var{n}
429: The @var{n}th word.
430:
431: @item ^
432: The first argument; that is, word 1.
433:
434: @item $
435: The last argument.
436:
437: @item %
438: The first word matched by the most recent @samp{?@var{string}?} search,
439: if the search string begins with a character that is part of a word.
440:
441: @item @var{x}-@var{y}
442: A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
443:
444: @item *
445: All of the words, except the @code{0}th. This is a synonym for @samp{1-$}.
446: It is not an error to use @samp{*} if there is just one word in the event;
447: the empty string is returned in that case.
448:
449: @item @var{x}*
450: Abbreviates @samp{@var{x}-$}
451:
452: @item @var{x}-
453: Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
454: If @samp{x} is missing, it defaults to 0.
455:
456: @end table
457:
458: If a word designator is supplied without an event specification, the
459: previous command is used as the event.
460:
461: @node Modifiers
462: @subsection Modifiers
463:
464: After the optional word designator, you can add a sequence of one or more
465: of the following modifiers, each preceded by a @samp{:}.
466: These modify, or edit, the word or words selected from the history event.
467:
468: @table @code
469:
470: @item h
471: Remove a trailing pathname component, leaving only the head.
472:
473: @item t
474: Remove all leading pathname components, leaving the tail.
475:
476: @item r
477: Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
478: the basename.
479:
480: @item e
481: Remove all but the trailing suffix.
482:
483: @item p
484: Print the new command but do not execute it.
485:
486: @ifset BashFeatures
487: @item q
488: Quote the substituted words, escaping further substitutions.
489:
490: @item x
491: Quote the substituted words as with @samp{q},
492: but break into words at spaces, tabs, and newlines.
493: The @samp{q} and @samp{x} modifiers are mutually exclusive; the last one
494: supplied is used.
495: @end ifset
496:
497: @item s/@var{old}/@var{new}/
498: Substitute @var{new} for the first occurrence of @var{old} in the
499: event line.
500: Any character may be used as the delimiter in place of @samp{/}.
501: The delimiter may be quoted in @var{old} and @var{new}
502: with a single backslash. If @samp{&} appears in @var{new},
503: it is replaced by @var{old}. A single backslash will quote
504: the @samp{&}.
505: If @var{old} is null, it is set to the last @var{old}
506: substituted, or, if no previous history substitutions took place,
507: the last @var{string}
508: in a !?@var{string}@code{[?]}
509: search.
510: If @var{new} is is null, each matching @var{old} is deleted.
511: The final delimiter is optional if it is the last
512: character on the input line.
513:
514: @item &
515: Repeat the previous substitution.
516:
517: @item g
518: @itemx a
519: Cause changes to be applied over the entire event line. Used in
520: conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
521: or with @samp{&}.
522:
523: @item G
524: Apply the following @samp{s} or @samp{&} modifier once to each word
525: in the event.
526:
527: @end table
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to hsuser.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc