github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2024-11-22 12:04:39 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Help cleanup

Browse Source 
Large list of changes, including formatting and typos for most commands.

More substantive changes have been made to alias, bind, block, break,
builtin, case, cd, commandline, count, else, emit, fish_config, funced,
function, functions, history, math, mimedb, nextd, not, popd, prevd,
pushd, pwd, random, read, set, set_color, switch, test, trap, type,
ulimit, umask, and while.
This commit is contained in:
David Adam (zanchey) 2013-05-12 15:56:01 +08:00 committed by ridiculousfish
parent 91aab03b90
commit 1287b9d823
70 changed files with 726 additions and 509 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc_src/alias.txt
View File

@ -6,13 +6,29 @@ alias NAME=DEFINITION</pre>
\subsection alias-description Description
Alias is a shellscript wrapper around the function builtin.
\c alias is a simple wrapper for the \c function builtin.
It exists for backwards compatibility with Posix
shells. For other uses, it is recommended to define a <a
href='#function'>function</a>.
Alias does not keep track of which functions have been defined using
alias, nor does it allow erasing of aliases.
\c fish does not keep track of which functions have been defined using
\c alias. They must be erased using <code>functions -e</code>.
- NAME is the name of the alias
- DEFINITION is the actual command to execute. The string " $argv" will be appended.
You cannot create an alias to a function with the same name.
\subsection alias-example Example
The following code will create \c rmi, which runs \c rm with additional
arguments on every invocation.
<code>alias rmi "rm -i"</code>
This is equivalent to entering the following function:
<pre>function rmi
rm -i $argv
end</pre>
- NAME is the name of the function to define
- DEFINITION is the body of the function. The string " $argv" will be appended to the body.

12
doc_src/and.txt
View File

@ -5,10 +5,10 @@
\subsection and-description Description
The \c and builtin is used to execute a command if the current exit
\c and is used to execute a command if the current exit
status (as set by the last previous command) is 0.
The and command does not change the current exit status.
\c and does not change the current exit status.
The exit status of the last foreground command to exit can always be
accessed using the <a href="index.html#variables-status">$status</a>
@ -16,10 +16,10 @@ variable.
\subsection and-example Example
The following code runs the \c make command to build a program, if the
build succeeds, the program is installed. If either step fails,
<tt>make clean</tt> is run, which removes the files created by the
build process
The following code runs the \c make command to build a program. If the
build succeeds, <code>make</code>'s exit status is 0, and the program is installed. If either step fails,
the exit status is 1, and <tt>make clean</tt> is run, which removes the files created by the.
build process.
<pre>
make; and make install; or make clean

13
doc_src/begin.txt
View File

@ -5,15 +5,18 @@
\subsection begin-description Description
The \c begin builtin is used to create a new block of code. The block
\c begin is used to create a new block of code.
The block
is unconditionally executed. <code>begin; ...; end</tt> is equivalent
to <tt>if true; ...; end</tt>. The begin command is used to group any
number of commands into a block. The reason for doing so is usually
either to introduce a new variable scope, to redirect the input or
to <tt>if true; ...; end</tt>.
\c begin is used to group a number of commands into a block.
This allows the introduction of a new variable scope, redirection of the input or
output of a set of commands as a group, or to specify precedence when
using the conditional commands like \c and.
The \c begin command does not change the current exit status.
\c begin does not change the current exit status.
\subsection begin-example Example

9
doc_src/bg.txt
View File

@ -1,16 +1,17 @@
\section bg bg - send to background
\section bg bg - send jobs to background
\subsection bg-synopsis Synopsis
<tt>bg [PID...]</tt>
\subsection bg-description Description
Sends the specified jobs to the background. A background job is
\c bg sends <a href="index.html#syntax-job-control">jobs</a> to the background, resuming them if they are stopped. A background job is
executed simultaneously with fish, and does not have access to the
keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified group ids are put in the background.
keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background.
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
\subsection bg-example Example
<tt>bg \%0</tt> will put the job with job id 0 in the background.
<tt>bg \%1</tt> will put the job with job ID 1 in the background.

41
doc_src/bind.txt
View File

@ -5,33 +5,34 @@
\subsection bind-description Description
The <tt>bind</tt> builtin causes fish to add a key binding from the specified sequence.
<tt>bind</tt> adds a binding for the specified key sequence to the
specified command.
SEQUENCE is the character sequence to bind to. Usually, one would use
fish escape sequences to express them. For example, because pressing
SEQUENCE is the character sequence to bind to. These should be written as
<a href="index.html#escapes">fish escape sequences</a>. For example, because pressing
the Alt key and another character sends that character prefixed with
an escape character, Alt-based key bindings can be written using the
\c \\e escape. For example, Alt-w can be written as
<tt>\\ew</tt>. Control character can be written in much the same way
using the \c \\c escape, for example Control-x can be written as
<tt>\\ew</tt>. The control character can be written in much the same way
using the \c \\c escape, for example Control-x (^X) can be written as
<tt>\\cx</tt>. Note that Alt-based key bindings are case sensitive and
Control base key bindings are not. This is not a design choice in
fish, it is simply how terminals work.
Control-based key bindings are not. This is a constraint of text-based
termainls, not \c fish.
If SEQUENCE is the empty string, i.e. an empty set of quotes, this is
interpreted as the default keybinding. It will be used whenever no
The default key binding can be set by specifying a SEQUENCE of the empty
string (that is, <code>''</code>). It will be used whenever no
other binding matches. For most key bindings, it makes sense to use
the \c self-insert function (i.e. <tt>bind '' self-insert</tt> as the
default keybinding. This will insert any keystrokes not specifically
bound to into the editor. Non-printable characters are ignored by the
editor, so this will not result in e.g. control sequences being
editor, so this will not result in control sequences being
printable.
If the -k switch is used, the name of the key (such as down, up or
backspace) is used instead of a sequence. The names used are the same
as the corresponding curses variables, but without the 'key_'
prefix. (See man 5 terminfo for more information, or use <tt>bind
--key-names</tt> for a list of all available named keys)
prefix. (See \c terminfo(5) for more information, or use <tt>bind
--key-names</tt> for a list of all available named keys.)
COMMAND can be any fish command, but it can also be one of a set of
special input functions. These include functions for moving the
@ -45,19 +46,19 @@ bind to the function name. This way it becomes significantly easier to
test the function while editing, and the result is usually more
readable as well.
If you want to autoload bindings each time you start shell, you should
define them inside fish_user_key_bindings function.
Key bindings are not saved between sessions by default. To save custom
keybindings, edit the \c fish_user_key_bindings function and insert the
appropirate \c bind statements.
The following parameters are available:
- <tt>-a</tt> or <tt>--all</tt> If --key-names is specified, show all key names, not only the ones that actually are defined for the current terminal. If erase mode is specified, this switch will cause all current bindings to be erased.
- <tt>-e</tt> or <tt>--erase</tt> Erase mode. All non-switch arguments are interpreted as character sequences and any commands associated with those sequences are erased.
- <tt>-h</tt> or <tt>--help</tt> Display help and exit
- <tt>-k</tt> or <tt>--key</tt> Specify a key name, such as 'left' or 'backspace' instead of a character sequence
- <tt>-K</tt> or <tt>--key-names</tt> Display a list of available key names
- <tt>-f</tt> or <tt>--function-names</tt> Display a list of available input functions
\subsection bind-example Example
\subsection bind-example Examples
<tt>bind \\cd 'exit'</tt> causes fish to exit on Control-d
<tt>bind \\cd 'exit'</tt> causes \c fish to exit when Control-d is pressed.
<tt>bind -k ppage history-search-backward</tt> Causes fish to perform a history search when the page up key is pressed
<tt>bind -k ppage history-search-backward</tt> performs a history search when the Page Up key is pressed.

25
doc_src/block.txt
View File

@ -5,15 +5,36 @@
\subsection block-description Description
- <tt>-l</tt> or <tt>--local</tt> Release the block at the end of the currently innermost block scope
\c block prevents events triggered by \c fish or the
<a href="commands.html#emit"><code>emit</code></a> command from
being delivered and acted upon while the block is in place.
In functions, \c block can be useful while performing work that
should not be interrupted by the shell.
The block can be removed. Any events which triggered while the
block was in place will then be delivered.
Event blocks should not be confused with code blocks, which are created
with <code>begin</code>, <code>if</code>, <code>while</code> or
<code>for</code>
The following parameters are available:
- <tt>-l</tt> or <tt>--local</tt> Release the block automatically at the end of the current innermost code block scope
- <tt>-g</tt> or <tt>--global</tt> Never automatically release the lock
- <tt>-e</tt> or <tt>--erase</tt> Release global block
\subsection block-example Example
<pre>
# Create a function that listens for events
function --on-event foo foo; echo 'foo fired'; end
# Block the delivery of events
block -g
\#Do something that should not be interrupted
emit foo
# No output will be produced
block -e
# 'foo fired' will now be printed
</pre>

9
doc_src/break.txt
View File

@ -1,13 +1,16 @@
\section break break - stop the innermost currently evaluated loop
\section break break - stop the current inner loop
\subsection break-synopsis Synopsis
<tt>LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end</tt>
\subsection break-description Description
The \c break builtin is used to halt a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
\c break halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
There are no parameters for <code>break</code>.
\subsection break-example Example
The following code searches all .c files for smurfs, and halts at the first occurrence.
The following code searches all .c files for "smurf", and halts at the first occurrence.
<pre>
for i in *.c

8
doc_src/breakpoint.txt
View File

@ -5,6 +5,10 @@
\subsection breakpoint-description Description
The \c breakpoint builtin is used to halt a running script and launch
an interactive debug prompt.
\c breakpoint is used to halt a running script and launch
an interactive debugging prompt.
For more details, see <a href="index.html#debugging">Debugging fish
scripts</a> in the \c fish manual.
There are no parameters for <code>breakpoint</code>.

10
doc_src/builtin.txt
View File

@ -5,12 +5,12 @@
\subsection builtin-description Description
- <tt>-n</tt> or <tt>--names</tt> List the names of all defined builtins
\c builtin forces the shell to use a builtin command, rather than a function or program.
Prefixing a command with the word 'builtin' forces fish to ignore any functions with the same name.
The following parameters are available:
- <tt>-n</tt> or <tt>--names</tt> List the names of all defined builtins
\subsection builtin-example Example
<tt>builtin jobs</tt>
causes fish to execute the jobs builtin, even if a function named jobs exists.
<tt>builtin jobs</tt> executes the jobs builtin, even if a function named jobs exists.

26
doc_src/case.txt
View File

@ -5,27 +5,24 @@
\subsection case-description Description
The \c switch statement is used to perform one of several blocks of
commands depending on whether a specified value equals one of several
wildcarded values. The \c case statement is used together with the \c
switch statement in order to determine which block should be
performed.
\c switch performs one of several blocks of commands, depending on whether
a specified value equals one of several wildcarded values. \c case is used
together with the \c switch statement in order to determine which block should
be executed.
Each \c case command is given one or more parameter. The first \c case
Each \c case command is given one or more parameters. The first \c case
command with a parameter that matches the string specified in the
switch command will be evaluated. \c case parameters may contain
wildcards. These need to be escaped or quoted in order to avoid
regular wildcard expansion using filenames.
Note that fish does not fall through on case statements. Though the
syntax may look a bit like C switch statements, it behaves more like
the case statements of traditional shells.
Note that fish does not fall through on case statements. Only the
first matching case is executed.
Also note that command substitutions in a case statement will be
evaluated even if it's body is not taken. This may seem
counterintuitive at first, but it is unavoidable, since it would be
impossible to know if a case command will evaluate to true before all
forms of parameter expansion have been performed for the case command.
Note that command substitutions in a case statement will be
evaluated even if its body is not taken. All substitutions, including
command substitutions, must be performed before the value can be compared
against the parameter.
\subsection case-example Example
@ -42,6 +39,7 @@ switch $animal
echo bird
case shark trout stingray
echo fish
# Note that the next case has a wildcard which is quoted
case '*'
echo I have no idea what a $animal is
end

23
doc_src/cd.txt
View File

@ -4,8 +4,21 @@
<tt>cd [DIRECTORY]</tt>
\subsection cd-description Description
Changes the current directory. If <tt>DIRECTORY</tt> is supplied it will become
the new directory. If \c DIRECTORY is a relative path, the paths found in the
CDPATH environment variable array will be tried as prefixes for the specified
path. If CDPATH is not set, it is assumed to be '.'. If \c DIRECTORY is not
specified, \$HOME will be the new directory.
\c cd changes the current working directory.
If \c DIRECTORY is supplied, it will become the new directory. If no parameter
is given, the contents of the \c HOME environment variable will be used.
If \c DIRECTORY is a relative path, the paths found in the
\c CDPATH environment variable array will be tried as prefixes for the specified
path.
Note that the shell will attempt to change directory without requiring \c cd
if the name of a directory is provided (starting with '.', '/' or '~').
\subsection cd-example Examples
\c cd changes the working directory to your home directory.
<code>cd /usr/src/fish-shell</code> changes the working directory to
<code>/usr/src/fish-shell</code>.

8
doc_src/command.txt
View File

@ -4,11 +4,9 @@
<tt>command COMMANDNAME [OPTIONS...]</tt>
\subsection command-description Description
prefixing a command with the word 'command' forces fish to ignore any functions or builtins with the same name.
\c command forces the shell to execute the program \c COMMANDNAME and ignore any functions or builtins with the same name.
\subsection command-example Example
<tt>command ls</tt>
causes fish to execute the ls program, even if there exists a 'ls' function.
<tt>command ls</tt> causes fish to execute the \c ls program, even if an 'ls' function exists.

42
doc_src/commandline.txt
View File

@ -1,32 +1,34 @@
\section commandline commandline - set or get the current commandline buffer
\section commandline commandline - set or get the current command line buffer
\subsection commandline-synopsis Synopsis
<tt>commandline [OPTIONS] [CMD]</tt>
\subsection commandline-description Description
\c commandline can be used to set or get the current contents of the command
line buffer.
- \c CMD is the new value of the commandline. If unspecified, the
current value of the commandline is written to standard output. All
output from the commandline builtin is escaped, i.e. quotes are
removed, backslash escapes are expanded, etc..
With no parameters, \c commandline returns the current value of the command
line.
The following switches change what the commandline builtin does
With \c CMD specified, the command line buffer is erased and replaced with
the contents of \c CMD.
The following options are available:
- \c -C or \c --cursor set or get the current cursor position, not
the contents of the buffer. If no argument is given, the current
cursor position is printed, otherwise the argument is interpreted
as the new cursor position.
- \c -f or \c --function inject readline functions into the
reader. This option can not be combined with any other option. It
reader. This option cannot be combined with any other option. It
will cause any additional arguments to be interpreted as readline
functions, and these functions will be injected into the reader, so
that they will be returned to the reader before any additional
actual key presses are read.
The following switches change the way \c commandline updates the
commandline buffer
The following options change the way \c commandline updates the
command line buffer:
- \c -a or \c --append do not remove the current commandline, append
the specified string at the end of it
@ -35,29 +37,27 @@ commandline buffer
- \c -r or \c --replace remove the current commandline and replace it
with the specified string (default)
The following switches change what part of the commandline is printed
or updated
The following options change what part of the commandline is printed
or updated:
- \c -b or \c --current-buffer select the entire buffer (default)
- \c -j or \c --current-job select the current job
- \c -p or \c --current-process select the current process
- \c -t or \c --current-token select the current token.
The following switch changes the way \c commandline prints the current
commandline buffer
The following options change the way \c commandline prints the current
commandline buffer:
- \c -c or \c --cut-at-cursor only print selection up until the
current cursor position
- \c -o or \c --tokenize tokenize the selection and print one string-type token per line
If commandline is called during a call to complete a given string
using <code>complete -C STRING</code>, commandline will consider the
specified string to be the current contents of the commandline.
If \c commandline is called during a call to complete a given string
using <code>complete -C STRING</code>, \c commandline will consider the
specified string to be the current contents of the command line.
\subsection commandline-example Example
<tt>commandline -j $history[3]</tt>
replaces the job under the cursor with the third item from the
commandline history.
<tt>commandline -j $history[3]</tt> replaces the job under the cursor with the
third item from the command line history.

6
doc_src/complete.txt
View File

@ -1,12 +1,12 @@
\section complete complete - edit command specific tab-completions.
\section complete complete - edit command specific tab-completions
\subsection complete-synopsis Synopsis
<tt>complete (-c|--command|-p|--path) COMMAND [(-s|--short-option) SHORT_OPTION] [(-l|--long-option|-o|--old-option) LONG_OPTION [(-a||--arguments) OPTION_ARGUMENTS] [(-d|--description) DESCRIPTION] </tt>
\subsection complete-description Description
For an introduction to how to specify completions, see the section <a
href='index.html#completion-own'>Writing your own completions</a> of
For an introduction to specifying completions, see <a
href='index.html#completion-own'>Writing your own completions</a> in
the fish manual.
- <tt>COMMAND</tt> is the name of the command for which to add a completion

12
doc_src/contains.txt
View File

@ -5,13 +5,15 @@
\subsection contains-description Description
\c contains tests whether the set \c VALUES contains the string
<code>KEY</code>. If so, \c contains exits with status 0; if not, it exits
with status 1.
The following options are available:
- \c -i or \c --index print the word index
- \c -h or \c --help display this message
Test if the set VALUES contains the string KEY. Return status is 0 if
yes, 1 otherwise
\subsection contains-example Example
<pre>
for i in ~/bin /usr/local/bin
@ -21,4 +23,4 @@ for i in ~/bin /usr/local/bin
end
</pre>
The above code tests if ~/bin and /usr/local/bin are in the path and if they are not, they are added.
The above code tests if \c ~/bin and \c /usr/local/bin are in the path and adds them if not.

6
doc_src/continue.txt
View File

@ -1,13 +1,13 @@
\section continue continue - skip the rest of the current lap of the innermost currently evaluated loop
\section continue continue - skip the remainder of the current iteration of the current inner loop
\subsection continue-synopsis Synopsis
<tt>LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end</tt>
\subsection continue-description Description
The \c continue builtin is used to skip the current lap of the innermost currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
\c continue skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
\subsection continue-example Example
The following code removes all tmp files without smurfs.
The following code removes all tmp files that do not contain the word smurf.
<pre>
for i in *.tmp

15
doc_src/count.txt
View File

@ -5,20 +5,13 @@
\subsection count-description Description
The <tt>count</tt> builtin prints the number of arguments that were
<tt>count</tt> prints the number of arguments that were
passed to it. This is usually used to find out how many elements an
environment variable array contains, but this is not the only
potential usage for the count command.
environment variable array contains.
The count command does not accept any options, not even '-h'. This way
the user does not have to worry about an array containing elements
such as dashes. \c fish performs a special check when invoking the
count command, and if the user uses a help option, this help page is
displayed, but if a help option is contained inside of a variable or
is the result of expansion, it will simply be counted like any other
argument.
\c count does not accept any options, including '-h'.
Count exits with a non-zero exit status if no arguments were passed
\c count exits with a non-zero exit status if no arguments were passed
to it, and with zero if at least one argument was passed.
\subsection count-example Example

6
doc_src/dirh.txt
View File

@ -4,5 +4,9 @@
<tt>dirh</tt>
\subsection dirh-description Description
<tt>dirh</tt> prints the current directory history. The current position in the
history is highlighted using <tt>$fish_color_history_current</tt>.
history is highlighted using the color defined in the
<tt>fish_color_history_current</tt> environment variable.
\c dirh does not accept any parameters.

5
doc_src/dirs.txt
View File

@ -4,4 +4,7 @@
<tt>dirs</tt>
\subsection dirs-description Description
<tt>dirs</tt> prints the current directory stack.
<tt>dirs</tt> prints the current directory stack, as created by the
<code><a href="#pushd">pushd</a></code> command.
\c dirs does not accept any parameters.

14
doc_src/echo.txt
View File

@ -3,19 +3,21 @@
\subsection echo-synopsis Synopsis
<tt>echo [STRING]</tt>
\subsection echo-description Description
Display a line of text.
\subsection echo-description Description
\c echo displays a string of text.
The following options are available:
- \c -n, \c Do not output a newline
- \c -s, \c Do not separate arguments with spaces
- \c -s, \c Do not separate arguments with spaces
- \c -E, \c Disable interpretation of backslash escapes (default)
- \c -e, \c Enable interpretation of backslash escapes
- \c -h, \c --help Display this help
\subsection echo-escapes Escape Sequences
If -e is in effect, the following sequences are recognized:
If \c -e is used, the following sequences are recognized:
- \c \\\\ \c backslash
- \\a alert (BEL)

20
doc_src/else.txt
View File

@ -4,14 +4,18 @@
<tt>if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end</tt>
\subsection else-description Description
<tt>if</tt> will execute the command CONDITION. If the condition's exit
status is 0, the commands COMMANDS_TRUE will execute. If it is not 0 and
<tt>else</tt> is given, COMMANDS_FALSE will be executed. Hint: use
<a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions.
<tt>if</tt> will execute the command \c CONDITION. If the condition's exit
status is 0, the commands \c COMMANDS_TRUE will execute. If it is not 0 and
<tt>else</tt> is given, \c COMMANDS_FALSE will be executed.
\subsection else-example Example
The command <tt>if test -f foo.txt; echo foo.txt exists; else; echo foo.txt does not exist; end</tt>
will print <tt>foo.txt exists</tt> if the file foo.txt
exists and is a regular file, otherwise it will print
<tt>foo.txt does not exist</tt>.
The following code tests whether a file \c foo.txt exists as a regular file.
<pre>
if test -f foo.txt
echo foo.txt exists
else
echo foo.txt does not exist
end
</pre>

2
doc_src/emit.txt
View File

@ -5,7 +5,7 @@
\subsection emit-description Description
The emit builtin fires a generic fish event. Such events can be caught by special functions called event handlers. The arguments are passed to the event handlers as function arguments.
\c emit emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments.
\subsection emit-example Example

4
doc_src/end.txt
View File

@ -10,7 +10,9 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
</pre>
\subsection end-description Description
<tt>end</tt> ends a block of commands. For more information, read the
<tt>end</tt> ends a block of commands.
For more information, read the
documentation for the block constructs, such as \c if, \c for and \c
while.

7
doc_src/eval.txt
View File

@ -4,13 +4,16 @@
<tt>eval [COMMANDS...]</tt>
\subsection eval-description Description
The <tt>eval</tt> function causes fish to evaluate the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
<tt>eval</tt> evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
\subsection eval-example Example
The folloing code will call the ls command. Note that \c fish does not
support the use of environment variables as direct commands; \c eval can
be used to work around this.
<pre>
set cmd ls
eval $cmd
</pre>
will call the ls command.

10
doc_src/exec.txt
View File

@ -5,11 +5,11 @@
\subsection exec-description Description
The \c exec builtin is used to replace the currently running shells
process image with a new command. On successful completion, exec never
returns. exec can not be used inside a pipeline.
\c exec replaces the currently running shell with a new command.
On successful completion, \c exec never returns. \c exec cannot be used
inside a pipeline.
\subsection exec-example Example
<tt>exec emacs</tt> starts up the emacs text editor. When emacs exits,
the session will terminate.
<tt>exec emacs</tt> starts up the emacs text editor, and exits \c fish.
When emacs exits, the session will terminate.

6
doc_src/exit.txt
View File

@ -1,13 +1,13 @@
\section exit exit - exit the shell.
\section exit exit - exit the shell
\subsection exit-synopsis Synopsis
<tt>exit [STATUS]</tt>
\subsection exit-description Description
The <tt>exit</tt> builtin causes fish to exit. If <tt>STATUS</tt> is
\c exit causes fish to exit. If <tt>STATUS</tt> is
supplied, it will be converted to an integer and used as the exit
code. Otherwise the exit code will be that of the last command executed.
code. Otherwise, the exit code will be that of the last command executed.
If exit is called while sourcing a file (using the <a
href="#source">.</a> builtin) the rest of the file will be skipped,

8
doc_src/fg.txt
View File

@ -1,14 +1,14 @@
\section fg fg - send job to foreground
\section fg fg - bring job to foreground
\subsection fg-synopsis Synopsis
<tt>fg [PID]</tt>
\subsection fg-description Description
Sends the specified job to the foreground. While a foreground job is
executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group id is put in the foreground.
\c fg brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is
executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
\subsection fg-example Example
<tt>fg \%0</tt> will put the job with job id 0 in the foreground.
<tt>fg \%1</tt> will put the job with job ID 1 in the foreground.

4
doc_src/fish.txt
View File

@ -5,10 +5,12 @@ fish [-h] [-v] [-c command] [FILE [ARGUMENTS...]]
\subsection fish-description Description
A commandline shell written mainly with interactive use in mind. The
\c fish is a command-line shell written mainly with interactive use in mind. The
full manual is available <a href='index.html'>in HTML</a> by using the
<a href='#help'>help</a> command from inside fish.
The following options are available:
- <code>-c</code> or <code>--command=COMMANDS</code> evaluate the specified commands instead of reading from the commandline
- <code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
- <code>-h</code> or <code>--help</code> display help and exit

21
doc_src/fish_config.txt
View File

@ -1,5 +1,22 @@
\section fish_config fish_config - Start up the web-based configuration interface
\section fish_config fish_config - start the web-based configuration interface
\subsection fish_config-description Description
This command starts up the web-based configuration interface, which allows you to edit your colors and view your functions, variables, and history.
\c fish_config starts the web-based configuration interface.
The web interface allows you to view your functions, variables and history, and
to make changes to your prompt and color configuration.
\c fish_config starts a local web server and then opens a web browser window; when
you have finished, close the browser window and then press the Enter key to
terminate the configuration session.
There are no parameters for <code>fish_config</code>.
If the \c BROWSER environment variable is set, it will be used as the name
of the web browser to open instead of the system default.
\subsection fish_config-example Example
\c fish_config opens a new web browser window and allows you to configure certain
fish settings.

4
doc_src/fish_indent.txt
View File

@ -5,11 +5,11 @@
\subsection fish_indent-description Description
\c fish_indent is used to indent or otherwise prettify a piece of fish
\c fish_indent is used to indent a piece of fish
code. \c fish_indent reads commands from standard input and outputs
them to standard output.
\c fish_indent understands the following options:
The following options are available:
- <tt>-h</tt> or <tt>--help</tt> displays this help message and then exits
- <tt>-i</tt> or <tt>--no-indent</tt> do not indent commands

5
doc_src/fish_pager.txt
View File

@ -2,7 +2,6 @@
\subsection fish_pager-description Description
This command is used internally by fish to display a list of
completions. It should not be used by other commands, as it's
interface is liable to change in the future.
\c fish_pager is used internally by fish. It should not be used by other
commands, as its interface is liable to change in the future.

5
doc_src/fish_prompt.txt
View File

@ -11,7 +11,10 @@ By defining the \c fish_prompt function, the user can choose a custom
prompt. The \c fish_prompt function is executed when the prompt is to
be shown, and the output is used as a prompt.
The exit status of commands within \c fish_prompt will not modify the <a href="index.html#variables-status">$status</a> seen outside of fish_prompt.
The exit status of commands within \c fish_prompt will not modify the value of <a href="index.html#variables-status">$status</a> outside of the \c fish_prompt function.
\c fish ships with a number of example prompts that can be chosen with the
\c fish_config command.
\subsection fish_prompt-example Example

7
doc_src/fish_update_completions.txt
View File

@ -1,6 +1,9 @@
\section fish_update_completions fish_update_completions - Update man-page completions
\section fish_update_completions fish_update_completions - Update completions using manual pages
\subsection fish_update_completions-description Description
This command parses your installed man pages and writes completion files to the fish config directory. This does not overwrite custom completions.
\c fish_update_completions parses manual pages installed on the system, and attempts to create completion files in the \c fish configuration directory.
This does not overwrite custom completions.
There are no parameters for <code>fish_update_completions</code>.

28
doc_src/fishd.txt
View File

@ -6,26 +6,28 @@
\subsection fishd-description Description
The \c fishd daemon is used to load, save and distribute universal
variable information. fish automatically connects to fishd via a socket
on startup. If no instance of fishd is running, fish spawns a new
fishd instance. fishd will create a socket in /tmp, and wait for
incoming connections from universal variable clients, such as fish,
When no clients are connected, fishd will automatically shut down.
variable information. \c fish automatically connects to \c fishd via a socket
on startup.
\c fishd is started and stopped automatically.
The following options are available if starting \c fishd manually:
- <tt>-h</tt> or <tt>--help</tt> displays this help message and then exits
- <tt>-v</tt> or <tt>--version</tt> displays the current fish version and then exits
\subsection fishd-files Files
\c ~/.config/fish/fishd.MACHINE_ID permanent storage location for universal
variable data. MACHINE_ID is generally based on the machine's MAC address.
The data is stored as a set of \c set and \c set_export commands such as
would be parsed by fishd. The file must always be stored in ASCII format.
If an instance of fishd is running (which is generally the case), manual
modifications to ~/.fishd.MACHINE_ID will be lost. Do NOT edit this file manually!
- \c ~/.config/fish/fishd.MACHINE_ID - permanent storage location for universal
variable data. \c MACHINE_ID is generally based on the machine's MAC address.
\c /tmp/fishd.socket.USERNAME the socket which fishd uses to communicate
The data is stored as a set of \c set and \c set_export commands such as
would be parsed by fishd. The file must always be stored in YAML format.
If an instance of fishd is running (which is generally the case), manual
modifications to \c ~/.fishd.MACHINE_ID will be lost. Do NOT edit this file manually!
- \c /tmp/fishd.socket.USERNAME - the socket which fishd uses to communicate
with all clients.
/tmp/fishd.log.USERNAME the fishd log file
- /tmp/fishd.log.USERNAME - the fishd log file

4
doc_src/for.txt
View File

@ -5,8 +5,8 @@
\subsection for-description Description
<tt>for</tt> is a loop construct. It will perform the commands specified by
COMMANDS multiple times. Each time the environment variable specified by
VARNAME is assigned a new value from VALUES. If VALUES is empty, COMMANDS will
\c COMMANDS multiple times. On each iteration, the environment variable specified by
\c VARNAME is assigned a new value from \c VALUES. If \c VALUES is empty, \c COMMANDS will
not be executed at all.
\subsection for-example Example

13
doc_src/funced.txt
View File

@ -5,13 +5,14 @@
\subsection funced-description Description
Use the funced command to edit the definition of a function. If there is no
function with the name specified, a skeleton function is inserted. If the
function exists, its definition will be shown in your editor or on the command
line.
\c funced provides an interface to edit the definition of the function
<code>NAME</code>.
By default, funced edits functions using the text editor in your $EDITOR
variable, if set; otherwise it uses the built-in editor.
If the \c $EDITOR environment variable is set, it will be used as the program
to edit the function. Otherwise, a built-in editor will be used.
If there is no function called \c NAME a new function will be created with
the specified name
- <code>-e command</code> or <code>--editor command</code> Open the function
body inside the text editor given by the command (for example, "vi"). The

7
doc_src/funcsave.txt
View File

@ -1,12 +1,13 @@
\section funcsave funcsave - save the definition of a function to the user's autoload directory
\subsection funcsave-synopsis Synopsis
<tt>funcsave FUNCTION_NAME</tt>
<tt>funcsave FUNCTION_NAME</tt>
\subsection funcsave-description Description
funcsave is used to save the current definition of a function to
a file which will be autoloaded by current and future fish
\c funcsave saves the current definition of a function to
a file in the fish configuration directory. This function will be automatically
loaded by current and future fish
sessions. This can be useful if you have interactively created a new
function and wish to save it for later use.

36
doc_src/function.txt
View File

@ -5,32 +5,28 @@
\subsection function-description Description
- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description
\c function creates a new function \c NAME with the body <code>BODY</code>.
A function is a list of commands that will be executed when the name of the
function is given as a command.
The following options are available:
- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description.
- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
- <code>-j PID</code> or <code> --on-job-exit PID</code> tells fish to run this function when the job with group id PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process id PID exits
- <code>-s</code> or <code>--on-signal SIGSPEC</code> tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP)
- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value
This builtin command is used to create a new function. A function is a
list of commands that will be executed when the name of the function
is entered. The function
<pre>
function hi
echo hello
end
</pre>
will write <code>hello</code> whenever the user enters \c hi.
- <code>-j PID</code> or <code> --on-job-exit PID</code> tells fish to run this function when the job with group ID PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process ID PID exits.
- <code>-s</code> or <code>--on-signal SIGSPEC</code> tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value.
If the user enters any additional arguments after the function, they
are inserted into the environment <a href="index.html#variables-arrays">variable array</a> argv.
are inserted into the environment <a href="index.html#variables-arrays">variable array</a>
<code>$argv</code>.
By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the <a href="#emit">emit</a> builtin. Fish generates the following named events:
- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed
- \c fish_command_not_found, which is emitted whenever a command lookup failed
- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed.
- \c fish_command_not_found, which is emitted whenever a command lookup failed.
\subsection function-example Example

52
doc_src/functions.txt
View File

@ -1,31 +1,51 @@
\section functions functions - print or erase functions
\subsection function-synopsis Synopsis
<code>functions [-e] FUNCTIONS...</code>
<pre>functions [-n]
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [-eq] FUNCTIONS...</pre>
\subsection functions-description Description
This builtin command is used to print or erase functions.
\c functions prints or erases functions.
- <code>-a</code> or <code>--all</code> list all functions, even those whose name start with an underscore.
The following options are available:
- <code>-a</code> or <code>--all</code> lists all functions, even those whose name start with an underscore.
- <code>-c OLDNAME NEWNAME</code> or <code>--copy OLDNAME NEWNAME</code> creates a new function named NEWNAME, using the definition of the OLDNAME function.
- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> change the description of this function
- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> changes the description of this function.
- <code>-e</code> or <code>--erase</code> causes the specified functions to be erased.
- <code>-h</code> or <code>--help</code> display a help message and exit
- <code>-n</code> or <code>--names</code> list only the names of all defined functions, not their definition
- <code>-q</code> or <code>--query</code> test if the specified functions exist. Does not output anything, but the builtins exit status is the number of functions specified that were not defined.
- <code>-h</code> or <code>--help</code> displays a help message and exits.
- <code>-n</code> or <code>--names</code> lists the names of all defined functions.
- <code>-q</code> or <code>--query</code> tests if the specified functions exist.
The default behavior of \c functions when called with no arguments,
is to print the names and definitions of all defined functions. If any
non-switch parameters are given, only the definition of the specified
The default behavior of <code>functions</code>, when called with no arguments,
is to print the names of all defined functions. Unless the \c -a option is
given, no functions starting with underscores are not included in the output.
If any non-option parameters are given, the definition of the specified
functions are printed.
Automatically loaded functions can not be removed using functions
-e. Either remove the definition file or change the
Automatically loaded functions cannot be removed using <code>functions
-e</code>. Either remove the definition file or change the
$fish_function_path variable to remove autoloaded functions.
Function copies, created with -c, will not have any event/signal/on-exit
notifications that the original may have had.
Copying a function using \c -c copies only the body of the function, and
does not attach any event notifications from the original function.
The exit status of the functions builtin is the number functions
specified in the argument list that do not exist.
Only one function's description can be changed in a single invocation
of <code>functions -d</code>.
The exit status of \c functions is the number of functions
specified in the argument list that do not exist, which can be used in
concert with the \c -q option.
\subsection functions-example Examples
<code>functions -n</code> displays a list of currently-defined functions.
<code>functions -c foo bar</code> copies the \c foo function to a new function called
<code>bar</code>.
<code>functions -e bar</code> erases the function <code>bar</code>.

8
doc_src/help.txt
View File

@ -5,12 +5,14 @@
\subsection help-description Description
The \c help command is used to display a section of the fish help documentation.
\c help displays the fish help documentation.
If a \c SECTION is specified, the help for that command is shown.
If the BROWSER environment variable is set, it will be used to display the
documentation, otherwise fish will search for a suitable browser.
documentation. Otherwise, fish will search for a suitable browser.
Note also that most builtin commands display their help in the terminal when
Note that most builtin commands display their help in the terminal when
given the <tt>--help</tt> option.
\subsection help-example Example

52
doc_src/history.txt
View File

@ -1,4 +1,4 @@
\section history history - Show and manipulate user's command history
\section history history - Show and manipulate command history
\subsection history-synopsis Synopsis
<pre>
@ -8,29 +8,37 @@ history (--search | --delete ) (--prefix "prefix string" | --contains "search st
\subsection history-description Description
history is used to list, search and delete user's command history
\c history is used to list, search and delete the history of commands used.
The following options are available:
- \c --save saves all changes in the history file. The shell automatically
saves the history file; this option is provided for internal use.
- \c --clear clears the history file. A prompt is displayed before the history
is erased.
- \c --search returns history items in keeping with the \c --prefix or
\c --contains options.
- \c --delete deletes history items.
- \c --prefix searches or deletes items in the history that begin with the
specified text string.
- \c --contains searches or deletes items in the history that contain the
specified text string.
If \c --search is specified without \c --contains or <code>--prefix</code>,
\c --contains will be assumed.
If \c --delete is specified without \c --contains or <code>--prefix</code>,
only a history item which exactly matches the parameter will be erased. No
prompt will be given. If \c --delete is specified with either of these
parameters, an interactive prompt will be displayed before any items are
deleted.
\subsection history-examples Example
<pre>
history --save
Save all changes in history file
<code>history --clear</code> deletes all history items
history --clear
Delete all history items
<code>history --search --contains "foo"</code> outputs a list of all previous
commands containing the string "foo".
history --search --contains "foo"
Searches commands containing "foo" string
history --search --prefix "foo"
Searches for commands with prefix "foo"
history --delete --contains "foo"
Interactively delete commands containing string "foo"
history --delete --prefix "foo"
Interactively delete commands with prefix "foo"
history --delete "foo"
Delete command "foo" from history
</pre>
<code>history --delete --prefix "foo"</code> interactively deletes the record
of previous commands which start with "foo".

10
doc_src/if.txt
View File

@ -5,15 +5,15 @@
\subsection if-description Description
<tt>if</tt> will execute the command CONDITION. If the condition's
exit status is 0, the commands COMMANDS_TRUE will execute. If the
exit status is not 0 and <tt>else</tt> is given, COMMANDS_FALSE will
<tt>if</tt> will execute the command \c CONDITION. If the condition's
exit status is 0, the commands \c COMMANDS_TRUE will execute. If the
exit status is not 0 and <tt>else</tt> is given, \c COMMANDS_FALSE will
be executed.
In order to use the exit status of multiple commands as the condition
of an if block, use <a href="#begin"><tt>begin; ...; end</tt></a> and
the short circuit commands <a href="commands.html#and">and</a> and <a
href="commands.html#or">or</a>.
the short circuit commands <a href="commands.html#and"><tt>and</tt></a>
and <a href="commands.html#or"><tt>or</tt></a>.
The exit status of the last foreground command to exit can always be
accessed using the <a href="index.html#variables-status">$status</a>

9
doc_src/isatty.txt
View File

@ -4,12 +4,11 @@
<tt>isatty [FILE DESCRIPTOR]</tt>
\subsection isatty-description Description
The <tt>isatty</tt> command is used to test if a file descriptor is a tty.
<tt>isatty</tt> tests if a file descriptor is a tty.
FILE DESCRIPTOR may be either the number of a file descriptor, or one of the
strings stdin, stdout and stderr.
<tt>FILE DESCRIPTOR</tt> may be either the number of a file descriptor, or one of the
strings <tt>stdin</tt>, \c stdout and <tt>stderr</tt>.
If the specified file descriptor is a tty, the exit status of the command is
zero, otherwise, it is non-zero.
zero. Otherwise, it is non-zero.

18
doc_src/jobs.txt
View File

@ -4,18 +4,22 @@
<code>jobs [OPTIONS] [PID]</code>
\subsection jobs-description Description
The <code>jobs</code> builtin causes fish to print a list of the currently
running jobs and their status.
<code>jobs</code> prints a list of the currently
running <a href="index.html#syntax-job-control">jobs</a> and their status.
jobs accepts the following switches:
- <code>-c</code> or <code>--command</code> print the command name for each process in jobs
- <code>-g</code> or <code>--group</code> only print the group id of each job
- <code>-h</code> or <code>--help</code> display a help message and exit
- <code>-l</code> or <code>--last</code> only the last job to be started is printed
- <code>-p</code> or <code>--pid</code> print the process id for each process in all jobs
- <code>-c</code> or <code>--command</code> prints the command name for each process in jobs.
- <code>-g</code> or <code>--group</code> only prints the group ID of each job.
- <code>-h</code> or <code>--help</code> displays a help message and exits.
- <code>-l</code> or <code>--last</code> prints only the last job to be started.
- <code>-p</code> or <code>--pid</code> prints the process ID for each process in all jobs.
On systems that supports this feature, jobs will print the CPU usage
of each job since the last command was executed. The CPU usage is
expressed as a percentage of full CPU activity. Note that on
multiprocessor systems, the total activity may be more than 100\%.
\subsection jobs-example Example
<code>jobs</code> outputs a summary of the current jobs.

12
doc_src/math.txt
View File

@ -6,10 +6,10 @@
\subsection math-description Description
math is used to perform mathematical calculations. It is only a very
thin wrapper for the bc program, that makes it possible to specify an
\c math is used to perform mathematical calculations. It is a very
thin wrapper for the bc program, which makes it possible to specify an
expression from the command line without using non-standard extensions
or a pipeline. Simply use a command like <code>math 1+1</code>.
or a pipeline.
For a description of the syntax supported by math, see the manual for
the bc program. Keep in mind that parameter expansion takes place on
@ -18,3 +18,9 @@ order to perform calculations involving environment variables or the
output of command substitutions, but it also means that parenthesis
have to be escaped.
\subsection math-example Examples
<code>math 1+1</code> outputs 2.
<code>math $status-128</code> outputs the numerical exit status of the
last command minus 128.

33
doc_src/mimedb.txt
View File

@ -5,21 +5,22 @@
\subsection mimedb-description Description
- \c FILES is a list of files to analyse
- \c -t, \c --input-file-data the specified files type should be determined both by their filename and by their contents (Default)
- \c -f, \c --input-filename the specified files type should be determined by their filename
- \c -i, \c --input-mime the arguments are not files but mimetypes
- \c -m, \c --output-mime the output will be the mimetype of each file (Default)
- \c -f, \c --output-description the output will be the description of each mimetype
- \c -a, \c --output-action the output will be the default action of each mimetype
- \c -l, \c --launch launch the default action for the specified file(s)
- \c -h, \c --help display a help message and exit
- \c -v, \c --version display version number and exit
\c mimedb queries the MIME type database and the \c .desktop files
installed on the system in order to find information on
the files listed in <code>FILES</code>. The information that \c mimedb
can retrieve includes the MIME type for a file, a description of the type,
and the default action that can be performed on the file. \c mimedb can also
be used to launch the default action for this file.
The mimedb command is used to query the mimetype database and the
.desktop files installed on the system in order to find information on
a file. The information that mimedb can retrieve includes the mimetype
for a file, a description of the type and what its default action
is. mimedb can also be used to launch the default action for this
file.
The following options are available:
- \c -t, \c --input-file-data determines the files' type both by their filename and by their contents (default behaviour).
- \c -f, \c --input-filename determines the files' type by their filename.
- \c -i, \c --input-mime specifies that the arguments are not files, but MIME types.
- \c -m, \c --output-mime outputs the MIME type of each file (default behaviour).
- \c -f, \c --output-description outputs the description of each MIME type.
- \c -a, \c --output-action outputs the default action of each MIME type.
- \c -l, \c --launch launches the default action for the specified files.
- \c -h, \c --help displays a help message and exit.
- \c -v, \c --version displays the version number and exits.

22
doc_src/nextd.txt
View File

@ -1,10 +1,22 @@
\section nextd nextd - move forward through directory history
\subsection nextd-synopsis Synopsis
<tt>nextd [-l | --list] [pos]</tt>
<tt>nextd [-l | --list] [POS]</tt>
\subsection nextd-description Description
<tt>nextd</tt> moves forwards <tt>pos</tt> positions in the history of visited
directories; if the end of the history has been hit, a warning is printed. If
the <code>-l></code> or <code>--list</code> flag is specified, the current
history is also displayed.
<tt>nextd</tt> moves forwards <tt>POS</tt> positions in the history of visited
directories; if the end of the history has been hit, a warning is printed.
If the <code>-l></code> or <code>--list</code> flag is specified, the current
directory history is also displayed.
\subsection nextd-example Example
<pre>cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell</pre>

4
doc_src/not.txt
View File

@ -5,11 +5,13 @@
\subsection not-description Description
The \c not builtin is used to negate the exit status of another command.
\c not negates the exit status of another command. If the exit status
is zero, \c not returns 1. Otherwise, \c not returns 0.
\subsection not-example Example
The following code reports an error and exits if no file named spoon can be found.
<pre>
if not test -f spoon
echo There is no spoon

2
doc_src/open.txt
View File

@ -5,7 +5,7 @@
\subsection open-description Description
The \c open command is used to open a file in its default application. \c open is implemented using the \c xdg-open command if it exists, or else the <a href="commands.html#mimedb">mimedb</a> command.
\c open opens a file in its default application, using the \c xdg-open command if it exists, or else the <a href="commands.html#mimedb">mimedb</a> command.
\subsection open-example Example

8
doc_src/or.txt
View File

@ -5,10 +5,10 @@
\subsection or-description Description
The \c or builtin is used to execute a command if the current exit
\c or is used to execute a command if the current exit
status (as set by the last previous command) is not 0.
The or command does not change the current exit status.
\c or does not change the current exit status.
The exit status of the last foreground command to exit can always be
accessed using the <a href="index.html#variables-status">$status</a>
@ -16,10 +16,10 @@ variable.
\subsection or-example Example
The following code runs the \c make command to build a program, if the
The following code runs the \c make command to build a program. If the
build succeeds, the program is installed. If either step fails,
<tt>make clean</tt> is run, which removes the files created by the
build process
build process.
<pre>
make; and make install; or make clean

18
doc_src/popd.txt
View File

@ -4,5 +4,21 @@
<tt>popd</tt>
\subsection popd-description Description
<tt>popd</tt> removes the top directory from the directory stack and
cd's to the new top directory.
changes the working directory to the new top directory. Use <a
href="#pushd"><tt>pushd</tt></a> to add directories to the stack.
\subsection popd-example Example
<pre>
pushd /usr/src
# Working directory is now /usr/src
# Directory stack contains /usr/src
pushd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
# Directory stack contains /usr/src /usr/src/fish-shell
popd
# Working directory is now /usr/src
# Directory stack contains /usr/src
</pre>

21
doc_src/prevd.txt
View File

@ -1,11 +1,24 @@
\section prevd prevd - move backward through directory history
\subsection prevd-synopsis Synopsis
<tt>prevd [-l | --list] [pos]</tt>
<tt>prevd [-l | --list] [POS]</tt>
\subsection prevd-description Description
<tt>prevd</tt> moves backwards <tt>pos</tt> positions in the history
<tt>prevd</tt> moves backwards <tt>POS</tt> positions in the history
of visited directories; if the beginning of the history has been hit,
a warning is printed. If the <code>-l</code> or <code>--list</code>
flag is specified, the current history is also displayed.
a warning is printed.
If the <code>-l</code> or <code>--list</code> flag is specified, the current
history is also displayed.
\subsection prevd-example Example
<pre>cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell</pre>

6
doc_src/psub.txt
View File

@ -11,12 +11,12 @@ send the output of a command into the calling command, much like
command substitution, but with the difference that the output is not
sent through commandline arguments but through a named pipe, with the
filename of the named pipe sent as an argument to the calling
program. The psub shellscript function, which when combined with a
program. \c psub combined with a
regular command substitution provides the same functionality.
If the \c -f or \c --file switch is given to psub, psub will use a
If the \c -f or \c --file switch is given to <tt>psub</tt>, \c psub will use a
regular file instead of a named pipe to communicate with the calling
process. This will cause psub to be significantly slower when large
process. This will cause \c psub to be significantly slower when large
amounts of data are involved, but has the advantage that the reading
process can seek in the stream.

18
doc_src/pushd.txt
View File

@ -4,6 +4,20 @@
<tt>pushd [DIRECTORY]</tt>
\subsection pushd-description Description
The <tt>pushd</tt> function adds DIRECTORY to the top of the directory stack
and makes it the current directory. Use <tt>popd</tt> to pop it off and
The <tt>pushd</tt> function adds \c DIRECTORY to the top of the directory stack
and makes it the current working directory. <a href="#popd"><tt>popd</tt></a> will pop it off and
return to the original directory.
\subsection pushd-example Example
<pre>
pushd /usr/src
# Working directory is now /usr/src
# Directory stack contains /usr/src
pushd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
# Directory stack contains /usr/src /usr/src/fish-shell
popd
# Working directory is now /usr/src
# Directory stack contains /usr/src
</pre>

6
doc_src/pwd.txt
View File

@ -1,8 +1,10 @@
\section pwd pwd - returns the current directory
\section pwd pwd - output the current working directory
\subsection pwd-synopsis Synopsis
<tt>pwd</tt>
\subsection pwd-description Description
Returns the current directory. Note that fish always resolves symbolic links in the current directory path.
\c pwd outputs (prints) the current working directory.
Note that \c fish always resolves symbolic links in the current directory path.

9
doc_src/random.txt
View File

@ -5,10 +5,11 @@
\subsection random-description Description
The \c random command is used to generate a random number in the
interval 0<=N<32767. If an argument is given, it is used to seed the
random number generator. This can be useful for debugging purposes,
where it can be desirable to get the same random number sequence
\c random outputs a random number from 0 to 32766, inclusive.
If a \c SEED value is provided, it is used to seed the random number
generator, and no output will be produced. This can be useful for debugging
purposes, where it can be desirable to get the same random number sequence
multiple times. If the random number generator is called without first
seeding it, the current time will be used as the seed.

36
doc_src/read.txt
View File

@ -5,27 +5,29 @@
\subsection read-description Description
The <tt>read</tt> builtin causes fish to read one line from standard
input and store the result in one or more environment variables.
<tt>read</tt> reads one line from standard
input and stores the result in one or more environment variables.
- <tt>-c CMD</tt> or <tt>--command=CMD</tt> specifies that the initial string in the interactive mode command buffer should be CMD.
- <tt>-g</tt> or <tt>--global</tt> specifies that the variables will be made global.
- <tt>-l</tt> or <tt>--local</tt> specifies that the variables will be made local.
The following options are available:
- <tt>-c CMD</tt> or <tt>--command=CMD</tt> sets the initial string in the interactive mode command buffer to <tt>CMD</tt>.
- <tt>-g</tt> or <tt>--global</tt> makes the variables global (default behaviour).
- <tt>-l</tt> or <tt>--local</tt> makes the variables local.
- <tt>-m NAME</tt> or <tt>--mode-name=NAME</tt> specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
- <tt>-p PROMPT_CMD</tt> or <tt>--prompt=PROMPT_CMD</tt> specifies that the output of the shell command PROMPT_CMD should be used as the prompt for the interactive mode prompt. The default prompt command is <tt>set_color green; echo read; set_color normal; echo "> "</tt>.
- <code>-s</code> or <code>--shell</code> Use syntax highlighting, tab completions and command termination suitable for entering shellscript code
- <code>-u</code> or <code>--unexport</code> causes the specified environment not to be exported to child processes
- <code>-U</code> or <code>--universal</code> causes the specified environment variable to be made universal. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell.
- <code>-x</code> or <code>--export</code> causes the specified environment variable to be exported to child processes
- <tt>-p PROMPT_CMD</tt> or <tt>--prompt=PROMPT_CMD</tt> uses the output of the shell command \c PROMPT_CMD as the prompt for the interactive mode. The default prompt command is <tt>set_color green; echo read; set_color normal; echo "> "</tt>.
- <code>-s</code> or <code>--shell</code> enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
- <code>-u</code> or <code>--unexport</code> prevents the variables from being exported to child processes (default behaviour).
- <code>-U</code> or <code>--universal</code> causes the specified environment variable to be made universal.
- <code>-x</code> or <code>--export</code> exports the variables to child processes.
Read starts by reading a single line of input from stdin, the line is
then tokenized using the <tt>IFS</tt> environment variable. Each variable
specified in <tt>VARIABLES</tt> is then assigned one tokenized string
element. If there are more tokens than variables, the complete
remainder is assigned to the last variable.
\c read reads a single line of input from stdin, breaks it into tokens
based on the <tt>IFS</tt> environment variable, and then assigns one
token to each variable specified in <tt>VARIABLES</tt>. If there are more
tokens than variables, the complete remainder is assigned to the last variable.
\subsection read-example Example
<tt>echo hello|read foo</tt>
The following code stores the value 'hello' in the environment variable
<tt>$foo</tt>.
Will cause the variable \$foo to be assigned the value hello.
<tt>echo hello|read foo</tt>

10
doc_src/return.txt
View File

@ -1,19 +1,19 @@
\section return return - stop the innermost currently evaluated function
\section return return - stop the current inner function
\subsection return-synopsis Synopsis
<tt>function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end</tt>
\subsection return-description Description
The \c return builtin is used to halt a currently running function. It
is usually added inside of a conditional block such as an <a
\c return halts a currently running function. The exit status is set
to \c STATUS if it is given.
It is usually added inside of a conditional block such as an <a
href="#if">if</a> statement or a <a href="#switch">switch</a>
statement to conditionally stop the executing function and return to
the caller, but it can also be used to specify the exit status of a
function.
- \c STATUS is the return status of the function. If unspecified, the status is unchanged.
\subsection return-example Example
The following code is an implementation of the false command as a fish function

42
doc_src/set.txt
View File

@ -1,4 +1,4 @@
\section set set - handle environment variables.
\section set set - display and change environment variables.
\subsection set-synopsis Synopsis
<pre>
@ -10,31 +10,39 @@ set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME
set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
</pre>
The <code>set</code> builtin causes fish to assign the variable <code>VARIABLE_NAME</code> the values <code>VALUES...</code>.
\subsection set-description Description
- <code>-e</code> or <code>--erase</code> causes the specified environment variable to be erased
- <code>-l</code> or <code>--local</code> forces the specified environment variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local
- <code>-g</code> or <code>--global</code> causes the specified environment variable to be given a global scope. Non-global variables disappear when the block they belong to ends
- <code>-U</code> or <code>--universal</code> causes the specified environment variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell.
- <code>-n</code> or <code>--names</code> List only the names of all defined variables, not their value
- <code>-q</code> or <code>--query</code> test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined.
- <code>-u</code> or <code>--unexport</code> causes the specified environment not to be exported to child processes
- <code>-x</code> or <code>--export</code> causes the specified environment variable to be exported to child processes
- <code>-L</code> or <code>--long</code> do not abbreviate long values when printing set variables
<code>set</code> manipulates <a href="index.html#variables">environment
variables</a>.
If set is called with no arguments, the names and values of all
environment variables are printed. If some of the scope or export
flags have been given, only the variables matching the specified scope
are printed.
With both variable names and values provided, \c set assigns the variable
<code>VARIABLE_NAME</code> the values <code>VALUES...</code>.
The following options control variable scope:
- <code>-l</code> or <code>--local</code> forces the specified environment variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local
- <code>-g</code> or <code>--global</code> causes the specified environment variable to be given a global scope. Non-global variables disappear when the block they belong to ends
- <code>-U</code> or <code>--universal</code> causes the specified environment variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell.
- <code>-n</code> or <code>--names</code> List only the names of all defined variables, not their value
- <code>-u</code> or <code>--unexport</code> causes the specified environment not to be exported to child processes
- <code>-x</code> or <code>--export</code> causes the specified environment variable to be exported to child processes
The following options are available:
- <code>-e</code> or <code>--erase</code> causes the specified environment variable to be erased
- <code>-q</code> or <code>--query</code> test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined.
- <code>-L</code> or <code>--long</code> do not abbreviate long values when printing set variables
If a variable is set to more than one value, the variable will be an
array with the specified elements. If a variable is set to zero
elements, it will become an array with zero elements.
If the variable name is one or more array elements, such as
<code>PATH[1 3 7]</code>, only those array elements specified will be
changed. When array indices are specified to set, multiple arguments
changed. When array indices are specified to \c set, multiple arguments
may be used to specify additional indexes, e.g. <code>set PATH[1]
PATH[4] /bin /sbin</code>. If you specify a negative index when
expanding or assigning to an array variable, the index will be
@ -63,17 +71,17 @@ be specified. That way, a global variable can be erased even if a
local variable with the same name exists. Scope can not be specified
when erasing a slice of an array. The innermost scope is always used.
The set command requires all switch arguments to come before any
non-switch arguments. For example, <code>set flags -l</code> will have
\c set requires all options to come before any
other arguments. For example, <code>set flags -l</code> will have
the effect of setting the value of the variable <code>flags</code> to
'-l', not making the variable local.
In assignment mode, set exits with a non-zero exit status if variable
In assignment mode, \c set exits with a non-zero exit status if variable
assignments could not be successfully performed. If the variable assignments
were performed, the exit status is unchanged. This allows simultaneous capture
of the output and exit status of a subcommand, e.g. <code>if set output
(command)</code>. In query mode, the exit status is the number of variables that
were not found. In erase mode, set exits with a zero exit status in case of
were not found. In erase mode, \c set exits with a zero exit status in case of
success, with a non-zero exit status if the commandline was invalid, if the
variable was write-protected or if the variable did not exist.

27
doc_src/set_color.txt
View File

@ -5,37 +5,36 @@
\subsection set_color-description Description
Change the foreground and/or background color of the terminal.
COLOR is one of black, red, green, brown, yellow, blue, magenta,
\c set_color changes the foreground and/or background color of the terminal.
\c COLOR is one of black, red, green, brown, yellow, blue, magenta,
purple, cyan, white and normal.
If your terminal supports term256 (modern xterms and OS X Lion),
you can specify an RGB value with three or six hex digits, such
as A0FF33 or f2f. fish will choose the closest supported color.
as A0FF33 or f2f. \c fish will choose the closest supported color.
- \c -b, \c --background Set the background color
- \c -c, \c --print-colors Prints a list of all valid color names
- \c -h, \c --help Display help message and exit
- \c -o, \c --bold Set bold or extra bright mode
- \c -u, \c --underline Set underlined mode
The following options are available:
- \c -b, \c --background \c COLOR sets the background color.
- \c -c, \c --print-colors prints a list of all valid color names.
- \c -h, \c --help displays a help message and exit.
- \c -o, \c --bold sets bold or extra bright mode.
- \c -u, \c --underline sets underlined mode.
Calling <tt>set_color normal</tt> will set the terminal color to
whatever is the default color of the terminal.
the default color of the terminal.
Some terminals use the --bold escape sequence to switch to a brighter
color set. On such terminals, <code>set_color white</code> will result
in a grey font color, while <code>set_color --bold white</code> will
result in a white font color.
Not all terminal emulators support all these features. This is not a
bug in set_color but a missing feature in the terminal emulator.
Not all terminal emulators support all these features.
set_color uses the terminfo database to look up how to change terminal
\c set_color uses the terminfo database to look up how to change terminal
colors on whatever terminal is in use. Some systems have old and
incomplete terminfo databases, and may lack color information for
terminals that support it. Download and install the latest version of
ncurses and recompile fish against it in order to fix this issue.
terminals that support it.
\subsection set_color-example Examples
<pre>set_color red; echo "Roses are red"

12
doc_src/source.txt
View File

@ -5,24 +5,22 @@
\subsection source-description Description
Evaluates the commands of the specified file in the current
\c . (source) evaluates the commands of the specified file in the current
shell. This is different from starting a new process to perform the
commands (i.e. <tt>fish < FILENAME</tt>) since the commands will be
evaluated by the current shell, which means that changes in
environment variables, etc., will remain. If additional arguments are
environment variables affect the current shell. If additional arguments are
specified after the file name, they will be inserted into the $argv
variable.
If no file is specified, or if the file name '-' is used, stdin will
be read.
The return status of . is the return status of the last job to
The return status of \c . is the return status of the last job to
execute. If something goes wrong while opening or reading the file,
. exits with a non-zero status.
\c . exits with a non-zero status.
\subsection source-example Example
<tt>. ~/.config/fish/config.fish</tt>
causes fish to reread its initialization file.
<tt>. ~/.config/fish/config.fish</tt> causes fish to re-read its initialization file.

26
doc_src/status.txt
View File

@ -6,16 +6,16 @@
\subsection status-description Description
With no arguments, <tt>status</tt> displays a summary of the current login and job control status of the shell.
The following arguments are available:
- <tt>-c</tt> or <tt>--is-command-substitution</tt> returns 0 if fish is currently executing a command substitution
- <tt>-b</tt> or <tt>--is-block</tt> returns 0 if fish is currently executing a block of code
- <tt>-i</tt> or <tt>--is-interactive</tt> returns 0 if fish is interactive, i.e.connected to a keyboard
- <tt>-l</tt> or <tt>--is-login</tt> returns 0 if fish is a login shell, i.e. if fish should perform login tasks such as setting up the PATH.
- <tt>--is-full-job-control</tt> returns 0 if full job control is enabled
- <tt>--is-interactive-job-control</tt> returns 0 if interactive job control is enabled
- <tt>--is-no-job-control</tt> returns 0 if no job control is enabled
- <tt>-f</tt> or <tt>--current-filename</tt> prints the filename of the currently running script
- <tt>-n</tt> or <tt>--current-line-number</tt> prints the line number of the currently running script
- <tt>-j CONTROLTYPE</tt> or <tt>--job-control=CONTROLTYPE</tt> set the job control type. Can be one of: none, full, interactive
- <tt>-t</tt> or <tt>--print-stack-trace</tt> prints a stack trace of all function calls on the call stack
- <tt>-h</tt> or <tt>--help</tt> display a help message and exit
The following options are available:
- <tt>-c</tt> or <tt>--is-command-substitution</tt> returns 0 if fish is currently executing a command substitution.
- <tt>-b</tt> or <tt>--is-block</tt> returns 0 if fish is currently executing a block of code.
- <tt>-i</tt> or <tt>--is-interactive</tt> returns 0 if fish is interactive - that is, connected to a keyboard.
- <tt>-l</tt> or <tt>--is-login</tt> returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH.
- <tt>--is-full-job-control</tt> returns 0 if full job control is enabled.
- <tt>--is-interactive-job-control</tt> returns 0 if interactive job control is enabled.
- <tt>--is-no-job-control</tt> returns 0 if no job control is enabled.
- <tt>-f</tt> or <tt>--current-filename</tt> prints the filename of the currently running script.
- <tt>-n</tt> or <tt>--current-line-number</tt> prints the line number of the currently running script.
- <tt>-j CONTROLTYPE</tt> or <tt>--job-control=CONTROLTYPE</tt> sets the job control type, which can be <tt>none</tt>, <tt>full</tt>, or <tt>interactive</tt>.
- <tt>-t</tt> or <tt>--print-stack-trace</tt> prints a stack trace of all function calls on the call stack.
- <tt>-h</tt> or <tt>--help</tt> displays a help message and exit.

25
doc_src/switch.txt
View File

@ -5,27 +5,24 @@
\subsection switch-description Description
The \c switch statement is used to perform one of several blocks of
commands depending on whether a specified value equals one of several
wildcarded values. The \c case statement is used together with the \c
switch statement in order to determine which block should be
performed.
\c switch performs one of several blocks of commands, depending on whether
a specified value equals one of several wildcarded values. \c case is used
together with the \c switch statement in order to determine which block should
be executed.
Each \c case command is given one or more parameter. The first \c case
Each \c case command is given one or more parameters. The first \c case
command with a parameter that matches the string specified in the
switch command will be evaluated. \c case parameters may contain
wildcards. These need to be escaped or quoted in order to avoid
regular wildcard expansion using filenames.
Note that fish does not fall through on case statements. Though the
syntax may look a bit like C switch statements, it behaves more like
the case statements of traditional shells.
Note that fish does not fall through on case statements. Only the
first matching case is executed.
Also note that command substitutions in a case statement will be
evaluated even if it's body is not taken. This may seem
counterintuitive at first, but it is unavoidable, since it would be
impossible to know if a case command will evaluate to true before all
forms of parameter expansion have been performed for the case command.
Note that command substitutions in a case statement will be
evaluated even if its body is not taken. All substitutions, including
command substitutions, must be performed before the value can be compared
against the parameter.
\subsection switch-example Example

61
doc_src/test.txt
View File

@ -3,41 +3,40 @@
\subsection test-synopsis Synopsis
<tt>test [EXPRESSION]</tt>
\subsection test-description Description
Tests the expression given and returns true or false.
\subsection test-description Description
- \c -h, \c Display this help
- \c -G, \c File owned by effective group ID
- \c -L, \c File is symlink
- \c -O, \c File owned by effective user ID
- \c -S, \c File is socket
- \c -a, \c Logical and
- \c -b, \c File is block device
- \c -c, \c File is character device
- \c -d, \c File is a directory
- \c -e, \c File exists
- \c -f, \c File is regular
- \c -f, \c File is set-group-ID
- \c -k, \c File has sticky bit set
- \c -n, \c String length is non-zero
- \c -o, \c Logical or
- \c -p, \c File is named pipe
- \c -r, \c File is readable
- \c -s, \c File size is non-zero
- \c -t, \c FD is terminal
- \c -u, \c File set-user-ID bit is set
- \c -w, \c File is writable
- \c -x, \c File is executable
- \c -z, \c String length is zero
Tests the expression given and sets the exit status to 0 if true,
and 1 if false.
The following options are available:
- \c -h displays a help message and then exits.
- <tt>-L FILE</tt> returns true if \c FILE is a symbolic link.
- <tt>-S FILE</tt> returns true if \c FILE is a socket.
- <tt>COND1 -a COND2</tt> combines two conditions with a logical and.
- <tt>-b FILE</tt> returns true if \c FILE is a block device.
- <tt>-c FILE</tt> returns true if \c FILE is a character device.
- <tt>-d FILE</tt> returns true if \c FILE is a directory.
- <tt>-e FILE</tt> returns true if \c FILE exists.
- <tt>-f FILE</tt> returns true if \c FILE is a regular file.
- <tt>-f FILE</tt> returns true if \c FILE has set-group-ID bit set.
- <tt>-n STRING</tt> returns true if the length of \c STRING is non-zero.
- <tt>COND1 -o COND2</tt> combines two conditions with a logical or.
- <tt>-p FILE</tt> returns true if \c FILE is a named pipe.
- <tt>-r FILE</tt> returns true if \c FILE is readable.
- <tt>-s FILE</tt> returns true if the size of \c FILE is non-zero.
- <tt>-t FD</tt> returns true if \c FD is a terminal (TTY).
- <tt>-u FILE</tt> returns true if \c FILE has set-user-ID bit set.
- <tt>-w FILE</tt> returns true if \c FILE is writable.
- <tt>-x FILE</tt> returns true if \c FILE is executable.
- <tt>-z STRING</tt> returns true if \c STRING length is zero.
\subsection test-example Example
<pre>
if test -d "/"
echo "Fish is cool"
end
if test -d "/"
echo "Fish is cool"
end
</pre>
Because "/" is a directory the expression will evaluate
to true, and "Fish is cool" will be echoed
Because "/" is a directory, the expression will evaluate to true, and
"Fish is cool" will be output.

43
doc_src/trap.txt
View File

@ -5,32 +5,39 @@
\subsection trap-description Description
Trap is a shellscript wrapper around the fish event delivery
framework. It exists for backwards compatibility with Posix
shells. For other uses, it is recommended to define a <a
\c trap is a wrapper around the fish event delivery
framework. It exists for backwards compatibility with POSIX
shells. For other uses, it is recommended to define an <a
href='index.html#event'>event handler</a>.
- ARG is the command to be executed on signal delivery
- SIGSPEC is the name of the signal to trap
- \c -h or \c --help Display help and exit
- \c -l or \c --list-signals print a list of signal names
- \c -p or \c --print print all defined signal handlers
The following parameters are available:
If ARG and SIGSPEC are both specified, ARG is the command to be
executed when the signal specified by SIGSPEC is delivered.
- \c ARG is the command to be executed on signal delivery.
- \c SIGSPEC is the name of the signal to trap.
- \c -h or \c --help displays help and exits.
- \c -l or \c --list-signals prints a list of signal names.
- \c -p or \c --print prints all defined signal handlers.
If ARG is absent (and there is a single SIGSPEC) or -, each specified
If \c ARG and \c SIGSPEC are both specified, \c ARG is the command to be
executed when the signal specified by \c SIGSPEC is delivered.
If \c ARG is absent (and there is a single SIGSPEC) or -, each specified
signal is reset to its original disposition (the value it had upon
entrance to the shell). If ARG is the null string the signal
specified by each SIGSPEC is ignored by the shell and by the commands
entrance to the shell). If \c ARG is the null string the signal
specified by each \c SIGSPEC is ignored by the shell and by the commands
it invokes.
If ARG is not present and -p has been supplied, then the trap commands
associated with each SIGSPEC are displayed. If no arguments are
supplied or if only -p is given, trap prints the list of commands
If \c ARG is not present and \c -p has been supplied, then the trap commands
associated with each \c SIGSPEC are displayed. If no arguments are
supplied or if only \c -p is given, \c trap prints the list of commands
associated with each signal.
Signal names are case insensitive and the SIG prefix is optional.
Signal names are case insensitive and the \c SIG prefix is optional.
The return status is 1 if any SIGSPEC is invalid; otherwise trap
The return status is 1 if any \c SIGSPEC is invalid; otherwise trap
returns 0.
\subsection trap-example Example
<code>trap "status --print-stack-trace" SIGUSR1</code> prints a stack trace
each time the \c SIGUSR1 signal is sent to the shell.

24
doc_src/type.txt
View File

@ -1,21 +1,23 @@
\section type type - indicate how a name would be interpreted if used as a command name
\section type type - indicate how a command would be interpreted
\subsection type-synopsis Synopsis
<tt>type [OPTIONS] name [name ...]</tt>
<tt>type [OPTIONS] NAME [NAME ...]</tt>
\subsection type-description Description
With no options, indicate how each name would be interpreted if used as a command name.
With no options, \c type indicates how each \c NAME would be interpreted if used as a command name.
- \c -h or \c --help print this message
- \c -a or \c --all print all of possible definitions of the specified names
- \c -f or \c --no-functions suppresses function and builtin lookup
- \c -t or \c --type print a string which is one of keyword, function, builtin, or file if name is a shell reserved word, function, builtin, or disk file, respectively
- \c -p or \c --path either return the name of the disk file that would be executed if name were specified as a command name, or nothing if 'type -t name' would not return 'file'
- \c -P or \c --force-path either return the name of the disk file that would be executed if name were specified as a command name, or nothing no file with the specified name could be found in the PATH
The following options are available:
\c type returns a zero exit status if the specified command was found,
otherwise the exit status is one.
- \c -h or \c --help prints help and then exits.
- \c -a or \c --all prints all of possible definitions of the specified names.
- \c -f or \c --no-functions suppresses function and builtin lookup.
- \c -t or \c --type prints <tt>keyword</tt>, <tt>function</tt>, <tt>builtin</tt>, or <tt>file</tt> if \c NAME is a shell reserved word, function, builtin, or disk file, respectively.
- \c -p or \c --path returns the name of the disk file that would be executed, or nothing if 'type -t name' would not return 'file'.
- \c -P or \c --force-path returns the name of the disk file that would be executed, or nothing no file with the specified name could be found in the <tt>$PATH</tt>.
\c type sets the exit status to 0 if the specified command was found,
and 1 if it could not be found.
\subsection type-example Example

61
doc_src/ulimit.txt
View File

@ -1,67 +1,66 @@
\section ulimit ulimit - set or get the shells resource usage limits
\section ulimit ulimit - set or get resource usage limits
\subsection ulimit-synopsis Synopsis
<tt>ulimit [OPTIONS] [LIMIT]</tt>
\subsection ulimit-description Description
The ulimit builtin is used to set the resource usage limits of the
shell and any processes spawned by it. If a new limit value is
omitted, the current value of the limit of the resource is printed.
\c ulimit builtin sets or outputs the resource usage limits of the
shell and any processes spawned by it. If a new limit value is
omitted, the current value of the limit of the resource is printed; otherwise,
the specified limit is set to the new value.
Use one of the following switches to specify which resource limit to set or report:
- <code>-c</code> or <code>--core-size</code> The maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
- <code>-d</code> or <code>--data-size</code> The maximum size of a process's data segment
- <code>-f</code> or <code>--file-size</code> The maximum size of files created by the shell
- <code>-l</code> or <code>--lock-size</code> The maximum size that may be locked into memory
- <code>-m</code> or <code>--resident-set-size</code> The maximum resident set size
- <code>-n</code> or <code>--file-descriptor-count</code> The maximum number of open file descriptors (most systems do not allow this value to be set)
- <code>-s</code> or <code>--stack-size</code> The maximum stack size
- <code>-t</code> or <code>--cpu-time</code> The maximum amount of cpu time in seconds
- <code>-u</code> or <code>--process-count</code> The maximum number of processes available to a single user
- <code>-v</code> or <code>--virtual-memory-size</code> The maximum amount of virtual memory available to the shell. If supported by OS.
- <code>-c</code> or <code>--core-size</code>: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
- <code>-d</code> or <code>--data-size</code>: the maximum size of a process' data segment.
- <code>-f</code> or <code>--file-size</code>: the maximum size of files created by the shell.
- <code>-l</code> or <code>--lock-size</code>: the maximum size that may be locked into memory.
- <code>-m</code> or <code>--resident-set-size</code>: the maximum resident set size.
- <code>-n</code> or <code>--file-descriptor-count</code>: the maximum number of open file descriptors (most systems do not allow this value to be set).
- <code>-s</code> or <code>--stack-size</code>: the maximum stack size.
- <code>-t</code> or <code>--cpu-time</code>: the maximum amount of CPU time in seconds.
- <code>-u</code> or <code>--process-count</code>: the maximum number of processes available to a single user.
- <code>-v</code> or <code>--virtual-memory-size</code> The maximum amount of virtual memory available to the shell.
Note that not all these limits are available in all operating systems.
The value of limit can be a number in the unit specified for
the resource or one of the special values hard, soft, or unlimited,
the resource or one of the special values <tt>hard</tt>, <tt>soft</tt>, or <tt>unlimited</tt>,
which stand for the current hard limit, the current soft limit, and no
limit, respectively.
If limit is given, it is the new value of the specified resource. If
no option is given, then -f is assumed. Values are in kilobytes,
except for -t, which is in seconds and -n and -u, which are unscaled
no option is given, then \c -f is assumed. Values are in kilobytes,
except for \c -t, which is in seconds and \c -n and \c -u, which are unscaled
values. The return status is 0 unless an invalid option or argument is
supplied, or an error occurs while setting a new limit.
ulimit also accepts the following switches that determine what type of
\c ulimit also accepts the following switches that determine what type of
limit to set:
- <code>-H</code> or <code>--hard</code> Set hard resource limit
- <code>-S</code> or <code>--soft</code> Set soft resource limit
- <code>-H</code> or <code>--hard</code> sets hard resource limit
- <code>-S</code> or <code>--soft</code> sets soft resource limit
A hard limit can only be decreased, once it is set it can not be
A hard limit can only be decreased. Once it is set it cannot be
increased; a soft limit may be increased up to the value of the hard
limit. If neither -H nor -S is specified, both the soft and hard
limits are updated when assigning a new limit value, and the soft
limit is used when reporting the current value.
The following additional options are also understood by ulimit:
The following additional options are also understood by <tt>ulimit</tt>:
- <code>-a</code> or <code>--all</code> Print all current limits
- <code>-h</code> or <code>--help</code> Display help and exit
- <code>-a</code> or <code>--all</code> prints all current limits
- <code>-h</code> or <code>--help</code> displays help and exits.
The fish implementation of ulimit should behave identically to the
The \c fish implementation of \c ulimit should behave identically to the
implementation in bash, except for these differences:
- Fish ulimit supports GNU-style long options for all switches
- Fish ulimit does not support the -p option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.
- Fish ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch
- Fish \c ulimit supports GNU-style long options for all switches
- Fish \c ulimit does not support the \c -p option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.
- Fish \c ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch
\subsection ulimit-example Example
<tt>ulimit -Hs 64</tt>
would set the hard stack size limit to 64 kB:
<tt>ulimit -Hs 64</tt> sets the hard stack size limit to 64 kB.

35
doc_src/umask.txt
View File

@ -1,17 +1,31 @@
\section umask umask - set or get the file-creation mask
\section umask umask - set or get the file creation mode mask
\subsection umask-synopsis Synopsis
<code>umask [OPTIONS] [MASK]</code>
\subsection umask-description Description
With no argument, the current file-creation mask is printed, if an
argument is specified, it is the new file creation mask. The mask may
be specified as an octal number, in which case it is interpreted as
the rights that should be masked away, i.e. it is the inverse of the
file permissions any new files will have.
\c umask displays and manipulates the "umask", or file creation mode mask,
which is used to restrict the default access to files.
If a symbolic mask is specified, the actual file permission bits, and
The umask may be expressed either as an octal number, which represents
the rights that will be removed by default, or symbolically, which represents
the only rights that will be granted by default.
Access rights are explained in the manual page for the \c chmod(1) program.
With no parameters, the current file creation mode mask is printed as
an octal number.
- <code>-h</code> or <code>--help</code> prints this message.
- <code>-S</code> or <code>--symbolic</code> prints the umask in symbolic form instead of octal form.
- <code>-p</code> or <code>--as-command</code> outputs the umask in a form that may be reused as input
If a numeric mask is specified as a parameter, the current shell's umask
will be set to that value, and the rights specified by that mask will be
removed from new files and directories by default.
If a symbolic mask is specified, the desired permission bits, and
not the inverse, should be specified. A symbolic mask is a comma
separated list of rights. Each right consists of three parts:
@ -34,12 +48,7 @@ and \c =, respectively. As an example, <code>r,u+w</code> means all
users should have read access and the file owner should also have
write access.
- <code>-h</code> or <code>--help</code> print this message
- <code>-S</code> or <code>--symbolic</code> prints the file-creation mask in symbolic form instead of octal form. Use <code>man chmod</code> for more information.
- <code>-p</code> or <code>--as-command</code> prints any output in a form that may be reused as input
The umask implementation in fish should behave identically to the one
in bash.
Note that symbolic masks currently do not work as intended.
\subsection umask-example Example

4
doc_src/vared.txt
View File

@ -5,8 +5,8 @@
\subsection vared-description Description
vared is used to interactively edit the value of an environment
variable. Array variables as a whole can not be edited using vared,
\c vared is used to interactively edit the value of an environment
variable. Array variables as a whole can not be edited using \c vared,
but individual array elements can.
\subsection vared-example Example

14
doc_src/while.txt
View File

@ -4,16 +4,18 @@
<tt>while CONDITION; COMMANDS...; end</tt>
\subsection while-description Description
The <tt>while</tt> builtin causes fish to continually execute CONDITION and
execute COMMANDS as long as CONDITION returned with status 0. If CONDITION is
false on the first time, COMMANDS will not be executed at all. Hints: use
<a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions; more
<tt>while</tt> repeatedly executes <tt>CONDITION</tt>, and if the exit status
is 0, then executes <tt>COMMANDS</tt>.
If the exit status of \c CONDITION is non-zero on the first iteration,
\c COMMANDS will not be executed at all.
Use <a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions; more
complex control can be achieved with <tt>while true</tt> containing a
<a href="#break">break</a>.
\subsection while-example Example
<tt>while test -f foo.txt; echo file exists; sleep 10; end</tt>
causes fish to print the line 'file exists' at 10 second intervals as long as
outputs 'file exists' at 10 second intervals as long as
the file foo.txt exists.