1: @ignore
2: This file documents the user interface to the GNU History library.
3:
4: Copyright (C) 1988--2014 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 previous history line.
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{Bash Builtins}, 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). If @var{last} is not specified it is set to
153: @var{first}. If @var{first} is not specified it is set to the previous
154: command for editing and @minus{}16 for listing. If the @option{-l} flag is
155: given, the commands are listed on standard output. The @option{-n} flag
156: suppresses the command numbers when listing. The @option{-r} flag
157: reverses the order of the listing. Otherwise, the editor given by
158: @var{ename} is invoked on a file containing those commands. If
159: @var{ename} is not given, the value of the following variable expansion
160: is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
161: value of the @env{FCEDIT} variable if set, or the value of the
162: @env{EDITOR} variable if that is set, or @code{vi} if neither is set.
163: When editing is complete, the edited commands are echoed and executed.
164:
165: In the second form, @var{command} is re-executed after each instance
166: of @var{pat} in the selected command is replaced by @var{rep}.
167: @var{command} is intepreted the same as @var{first} above.
168:
169: A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
170: that typing @samp{r cc} runs the last command beginning with @code{cc}
171: and typing @samp{r} re-executes the last command (@pxref{Aliases}).
172:
173: @item history
174: @btindex history
175: @example
176: history [@var{n}]
177: history -c
178: history -d @var{offset}
179: history [-anrw] [@var{filename}]
180: history -ps @var{arg}
181: @end example
182:
183: With no options, display the history list with line numbers.
184: Lines prefixed with a @samp{*} have been modified.
185: An argument of @var{n} lists only the last @var{n} lines.
186: If the shell variable @env{HISTTIMEFORMAT} is set and not null,
187: it is used as a format string for @var{strftime} to display
188: the time stamp associated with each displayed history entry.
189: No intervening blank is printed between the formatted time stamp
190: and the history line.
191:
192: Options, if supplied, have the following meanings:
193:
194: @table @code
195: @item -c
196: Clear the history list. This may be combined
197: with the other options to replace the history list completely.
198:
199: @item -d @var{offset}
200: Delete the history entry at position @var{offset}.
201: @var{offset} should be specified as it appears when the history is
202: displayed.
203:
204: @item -a
205: Append the new
206: history lines (history lines entered since the beginning of the
207: current Bash session) to the history file.
208:
209: @item -n
210: Append the history lines not already read from the history file
211: to the current history list. These are lines appended to the history
212: file since the beginning of the current Bash session.
213:
214: @item -r
215: Read the history file and append its contents to
216: the history list.
217:
218: @item -w
219: Write out the current history list to the history file.
220:
221: @item -p
222: Perform history substitution on the @var{arg}s and display the result
223: on the standard output, without storing the results in the history list.
224:
225: @item -s
226: The @var{arg}s are added to the end of
227: the history list as a single entry.
228:
229: @end table
230:
231: When any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options is
232: used, if @var{filename}
233: is given, then it is used as the history file. If not, then
234: the value of the @env{HISTFILE} variable is used.
235:
236: @end table
237: @end ifset
238:
239: @node History Interaction
240: @section History Expansion
241: @cindex history expansion
242:
243: The History library provides a history expansion feature that is similar
244: to the history expansion provided by @code{csh}. This section
245: describes the syntax used to manipulate the history information.
246:
247: History expansions introduce words from the history list into
248: the input stream, making it easy to repeat commands, insert the
249: arguments to a previous command into the current input line, or
250: fix errors in previous commands quickly.
251:
252: History expansion takes place in two parts. The first is to determine
253: which line from the history list should be used during substitution.
254: The second is to select portions of that line for inclusion into the
255: current one. The line selected from the history is called the
256: @dfn{event}, and the portions of that line that are acted upon are
257: called @dfn{words}. Various @dfn{modifiers} are available to manipulate
258: the selected words. The line is broken into words in the same fashion
259: that Bash does, so that several words
260: surrounded by quotes are considered one word.
261: History expansions are introduced by the appearance of the
262: history expansion character, which is @samp{!} by default.
263: @ifset BashFeatures
264: Only @samp{\} and @samp{'} may be used to escape the history expansion
265: character.
266: @end ifset
267:
268: @ifset BashFeatures
269: Several shell options settable with the @code{shopt}
270: builtin (@pxref{Bash Builtins}) may be used to tailor
271: the behavior of history expansion. If the
272: @code{histverify} shell option is enabled, and Readline
273: is being used, history substitutions are not immediately passed to
274: the shell parser.
275: Instead, the expanded line is reloaded into the Readline
276: editing buffer for further modification.
277: If Readline is being used, and the @code{histreedit}
278: shell option is enabled, a failed history expansion will be
279: reloaded into the Readline editing buffer for correction.
280: The @option{-p} option to the @code{history} builtin command
281: may be used to see what a history expansion will do before using it.
282: The @option{-s} option to the @code{history} builtin may be used to
283: add commands to the end of the history list without actually executing
284: them, so that they are available for subsequent recall.
285: This is most useful in conjunction with Readline.
286:
287: The shell allows control of the various characters used by the
288: history expansion mechanism with the @code{histchars} variable,
289: as explained above (@pxref{Bash Variables}). The shell uses
290: the history comment character to mark history timestamps when
291: writing the history file.
292: @end ifset
293:
294: @menu
295: * Event Designators:: How to specify which history line to use.
296: * Word Designators:: Specifying which words are of interest.
297: * Modifiers:: Modifying the results of substitution.
298: @end menu
299:
300: @node Event Designators
301: @subsection Event Designators
302: @cindex event designators
303:
304: An event designator is a reference to a command line entry in the
305: history list.
306: Unless the reference is absolute, events are relative to the current
307: position in the history list.
308: @cindex history events
309:
310: @table @asis
311:
312: @item @code{!}
313: @ifset BashFeatures
314: Start a history substitution, except when followed by a space, tab,
315: the end of the line, @samp{=} or @samp{(} (when the
316: @code{extglob} shell option is enabled using the @code{shopt} builtin).
317: @end ifset
318: @ifclear BashFeatures
319: Start a history substitution, except when followed by a space, tab,
320: the end of the line, or @samp{=}.
321: @end ifclear
322:
323: @item @code{!@var{n}}
324: Refer to command line @var{n}.
325:
326: @item @code{!-@var{n}}
327: Refer to the command @var{n} lines back.
328:
329: @item @code{!!}
330: Refer to the previous command. This is a synonym for @samp{!-1}.
331:
332: @item @code{!@var{string}}
333: Refer to the most recent command
334: preceding the current position in the history list
335: starting with @var{string}.
336:
337: @item @code{!?@var{string}[?]}
338: Refer to the most recent command
339: preceding the current position in the history list
340: containing @var{string}.
341: The trailing
342: @samp{?} may be omitted if the @var{string} is followed immediately by
343: a newline.
344:
345: @item @code{^@var{string1}^@var{string2}^}
346: Quick Substitution. Repeat the last command, replacing @var{string1}
347: with @var{string2}. Equivalent to
348: @code{!!:s/@var{string1}/@var{string2}/}.
349:
350: @item @code{!#}
351: The entire command line typed so far.
352:
353: @end table
354:
355: @node Word Designators
356: @subsection Word Designators
357:
358: Word designators are used to select desired words from the event.
359: A @samp{:} separates the event specification from the word designator. It
360: may be omitted if the word designator begins with a @samp{^}, @samp{$},
361: @samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning
362: of the line, with the first word being denoted by 0 (zero). Words are
363: inserted into the current line separated by single spaces.
364:
365: @need 0.75
366: For example,
367:
368: @table @code
369: @item !!
370: designates the preceding command. When you type this, the preceding
371: command is repeated in toto.
372:
373: @item !!:$
374: designates the last argument of the preceding command. This may be
375: shortened to @code{!$}.
376:
377: @item !fi:2
378: designates the second argument of the most recent command starting with
379: the letters @code{fi}.
380: @end table
381:
382: @need 0.75
383: Here are the word designators:
384:
385: @table @code
386:
387: @item 0 (zero)
388: The @code{0}th word. For many applications, this is the command word.
389:
390: @item @var{n}
391: The @var{n}th word.
392:
393: @item ^
394: The first argument; that is, word 1.
395:
396: @item $
397: The last argument.
398:
399: @item %
400: The word matched by the most recent @samp{?@var{string}?} search.
401:
402: @item @var{x}-@var{y}
403: A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
404:
405: @item *
406: All of the words, except the @code{0}th. This is a synonym for @samp{1-$}.
407: It is not an error to use @samp{*} if there is just one word in the event;
408: the empty string is returned in that case.
409:
410: @item @var{x}*
411: Abbreviates @samp{@var{x}-$}
412:
413: @item @var{x}-
414: Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
415:
416: @end table
417:
418: If a word designator is supplied without an event specification, the
419: previous command is used as the event.
420:
421: @node Modifiers
422: @subsection Modifiers
423:
424: After the optional word designator, you can add a sequence of one or more
425: of the following modifiers, each preceded by a @samp{:}.
426:
427: @table @code
428:
429: @item h
430: Remove a trailing pathname component, leaving only the head.
431:
432: @item t
433: Remove all leading pathname components, leaving the tail.
434:
435: @item r
436: Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
437: the basename.
438:
439: @item e
440: Remove all but the trailing suffix.
441:
442: @item p
443: Print the new command but do not execute it.
444:
445: @ifset BashFeatures
446: @item q
447: Quote the substituted words, escaping further substitutions.
448:
449: @item x
450: Quote the substituted words as with @samp{q},
451: but break into words at spaces, tabs, and newlines.
452: @end ifset
453:
454: @item s/@var{old}/@var{new}/
455: Substitute @var{new} for the first occurrence of @var{old} in the
456: event line. Any delimiter may be used in place of @samp{/}.
457: The delimiter may be quoted in @var{old} and @var{new}
458: with a single backslash. If @samp{&} appears in @var{new},
459: it is replaced by @var{old}. A single backslash will quote
460: the @samp{&}. The final delimiter is optional if it is the last
461: character on the input line.
462:
463: @item &
464: Repeat the previous substitution.
465:
466: @item g
467: @itemx a
468: Cause changes to be applied over the entire event line. Used in
469: conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
470: or with @samp{&}.
471:
472: @item G
473: Apply the following @samp{s} modifier once to each word in the event.
474:
475: @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