<tt> echo \$HOME</tt> prints the home directory of the current
user. If you wish to combine environment variables with text, you can
encase the variables within braces to embed a variable inside running
text like <tt>echo Konnichiwa {$USER}san</tt>, which will print a
personalized Japanese greeting.
\subsection expand-home Home directory expansion
The ~ (tilde) character at the beginning of a parameter, followed by a
username, is expanded into the home directory of the specified user. A
lone ~, or a ~ followed by a slash, is expanded into the home
directory of the process owner.
\subsection expand-process Process expansion
The \% (percent) character at the beginning of a parameter followed by
a string is expanded into a process id. The following expantions are
performed:
- If the string is the entire word \c self, the shells pid is the result
- Otherwise, if the string is the id of a job, the result is the process
group id of the job.
- Otherwise, if any child processes match the specified string, their
pids are the result of the expansion.
- Otherwise, if any processes owned by the user match the specified
string, their pids are the result of the expansion.
This form of expansion is useful for commands like kill and fg, which
take the process ids as an argument.
Example:
<tt>fg \%ema</tt> will search for a process whose command line begins
with the letters 'ema', such as emacs, and if found, put it in the
foreground.
<tt>kill -s SIGINT \%3</tt> will send the SIGINT signal to the job
with job id 3.
\subsection combine Combining different expansions
All of the above expansions can be combined. If several expansions
result in more than one parameter, all possible combinations are
created.
Example:
If the current directory contains the files 'foo' and 'bar', the command
<tt>echo a(ls){1,2,3} </tt>
will output 'abar1 abar2 abar3 afoo1 afoo2 afoo3'.
\section variables Environment variables
The concept of environment variables are central to any
shell. Environment variables are variables, whose values can be set
and used by the user.
To set a variable value, use the <a href="builtins.html#set"> \c set
command</a>.
Example:
To set the variable \c smurf to the value \c blue, use the command
<tt>set smurf blue</tt>.
After a variable has been set, you can use the value of a variable in
the shell through <a href="expand-variable">variable expansion</a>.
Example:
To use the value of a the variable \c smurf, use the command <tt>echo
Smurfs are $smurf</tt>, which would print the result 'Smurfs are
blue'.
\subsection variables-scope Variable scope
There are three kinds of variables in fish, universal, global and
local variables. Universal variables are shared between all fish
sessions a user is running on one computer. Global variables are
specific to the current fish session, and will never be erased unless
the user explicitly requests it using <tt>set -e</tt>. Local variables
are specific to the current fish session, and associated with a
specific block of commands, and is automatically erased when a
specific block goes out of scope. A block of commands is a series of
commands that begins with one of the commands \c 'for, \c 'while' , \c
'if', \c 'function', \c 'begin' or \c 'switch', and ends with the
command \c 'end'. The user can specify that a variable should have
either global or local scope using the \c -g/--global or \c -l/--local
switches.
Variables can be explicitly set to be universal with the \c -U or \c
--universal switch, global with the \c -g or \c --global switch, or
local with the \c -l or \c --local switch. The scoping rules when
creating or updating a variable are:
-# If a variable is explicitly set to either universal, global or local, that setting will be honored
-# If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the variable scope is not changed
-# If a variable is not explicitly set to be either universal, global or local and has never befor been defined, the variable will be local to the current scope
When using a variable, the variable scope will be searched from the
inside out, i.e. a local variable will be used rather than a global
variable with the same name, a global variable will be used rather
than a universal variable with the same name.
For example, the following code will not output anything:
<pre>
if true
# This is a nice local scope where all variables will die
set pirate 'There be treasure in them thar hills'
end
# This will not output anything, since the pirate is dead
echo $pirate
</pre>
\subsection variables-universal More on universal variables
Universal variables are variables that are shared between all the
users fish sessions on the computer. Fish stores many of it's
configuration options as universal variables. This means that in order
to change fish settings, all you have to do is change the variable
value once, and it will be automatically updated for all sessions, and
preserved across computer reboots and login/logout.
To see universal variables in action, start two fish sessions side by
side, and issue the following command in one of them <tt>set
fish_color_cwd blue</tt>. Since \c fish_color_cwd is a universal
variable, the color of the current working directory listing in the
prompt will instantly change to blue on both terminals.
\subsection variables-functions Variable scope for functions
When calling a function, all non-global variables temporarily
dissapear. This shadowing of the local scope is needed since the
variable namespace would become cluttered, making it very easy to
accidentaly overwrite variables from another function.
For example, the following code will output 'Avast, mateys':
<pre>
function shiver
set phrase 'Shiver me timbers'
end
function avast
set phrase 'Avast, mateys'
# Calling the shiver function here can not change any variables
# in the local scope
shiver
echo $phrase
end
avast
</pre>
\subsection variables-export Exporting variables
Variables in fish can be exported. This means the variable will be
inherited by any commands started by fish. It is convention that
exported variables are in uppercase and unexported variables are in
lowercase.
Variables can be explicitly set to be exportes with the \c -x or \c
--export switch, or not exported with the \c -u or \c --unexport
switch. The exporting rules when creating or updating a variable are
identical to the scoping rules for variables:
-# If a variable is explicitly set to either be exported or not exported, that setting will be honored
-# If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept
-# If a variable is not explicitly set to be either global or local and has never befor been defined, the variable will not be exported
\subsection variables-arrays Arrays
\c fish can store a list of multiple strings inside of a variable. To
access one element of an array, use the index of the element inside of
square brackets, like this:
<pre>
echo $PATH[3]
</pre>
If you do not use any brackets, all the elements of the array will be
written as separate items. This means you can easily iterate over an
array using this syntax:
<pre>
for i in $PATH; echo $i is in the path; end
</pre>
To create a variable \c smurf, containing the items \c blue and \c
small, simply write:
<pre>
set smurf blue small
</pre>
It is also possible to set or erase individual elements of an array:
<pre>
\#Set smurf to be an array with the elements 'blue' and 'small'
set smurf blue small
\#Change the second element of smurf to 'evil'
set smurf[2] evil
\#Erase the first element
set -e smurf[1]
\#Output 'evil'
echo $smurf
</pre>
\subsection variables-special Special variables
The user can change the settings of \c fish by changing the values of
certain environment variables.These are:
- \c BROWSER, which is the users preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
- \c CDPATH, which is an array of directories in which to search for the new directory for the \c cd builtin.
- \c fish_color_normal, \c fish_color_command, \c fish_color_substitution, \c fish_color_redirection, \c fish_color_end, \c fish_color_error, \c fish_color_param, \c fish_color_comment, \c fish_color_match, \c fish_color_search_match, \c fish_color_cwd, \c fish_pager_color_prefix, \c fish_pager_color_completion, \c fish_pager_color_description and \c fish_pager_color_progress are used to change the color of various elements in \c fish. These variables are universal, i.e. when changing them, their new value will be used by all running fish sessions. The new value will also be retained when restarting fish.
- \c PATH, which is an array of directories in which to search for commands
\c fish also sends additional information to the user through the
values of certain environment variables. The user can not change the values of these variables. They are:
- \c _, which is the name of the currently running command.
- \c history, which is an array containing the last commands that where entered
- \c HOME, which is the users home directory. This variable can be changed by the root user.
- \c PWD, which is the current working directory.
- \c status, which is the exit status of the last foreground job to exit. If a job contains pipelines, the status of the last command in the pipeline is the status for the job.
\c fish also uses several variables internally. Such variables are
prefixed with the string __FISH or __fish. These should be ignored by the user.
\section builtin-overview Builtins
Many other shells have a large library of builtin commands. Most of
these commands are also available as standalone commands, but have
been implemented in the shell anyway for whatever reason. To avoid
code duplication, and to avoid the confusion of subtly differing
versions of the same command, \c fish only implementing builtins for
actions which cannot be performed by a regular command.
\section bundle Commands bundled with fish
The following commands are distributed with fish. Many of them are
builtins or shellscript functions, and can only be used inside fish.
- <a href="builtins.html#source">.</a>, to read and execute the commands in a file
- <a href="builtins.html#bg">bg</a>, to set a command to the background
- <a href="builtins.html#begin">begin</a>, to execute a block of commands
- <a href="builtins.html#bind">bind</a>, to change keyboard bindings
- Alt-l lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory will be listed
- \c backward-char, moves one character to the left
- \c backward-delete-char, deletes one character of input to the left of the cursor
- \c backward-kill-line, move everything from the beginning of the line to the cursor to the killring
- \c backward-kill-word, move the word to the left of the cursor to the killring
- \c backward-word, move one word to the left
- \c beginning-of-history, move to the beginning of the history
- \c beginning-of-line, move to the beginning of the line
- \c complete, guess the remainder of the current token
- \c delete-char, delete one character to the right of the cursor
- \c delete-line, delete the entire line
- \c dump-functions, print a list of all key-bindings
- \c end-of-history, move to the end of the history
- \c end-of-line, move to the end of the line
- \c explain, print a description of possible problems with the current command
- \c forward-char, move one character to the right
- \c forward-word, move one word to the right
- \c history-search-backward, search the history for the previous match
- \c history-search-forward, search the history for the next match
- \c kill-line, move everything from the cursor to the end of the line to the killring
- \c kill-whole-line, move the line to the killring
- \c kill-word, move the next word to the killring
- \c yank, insert the latest entry of the killring into the buffer
- \c yank-pop, rotate to the previous entry of the killring
\subsection killring Copy and paste (Kill Ring)
\c fish uses an Emacs style kill ring for copy and paste
functionality. Use Ctrl-K to cut from the current cursor position to
the end of the line. The string that is cut (a.k.a. killed) is
inserted into a linked list of kills, called the kill ring. To paste
the latest value from the kill ring use Ctrl-Y. After pasting, use
Meta-Y to rotate to the previous kill.
If the environment variable DISPLAY is set, \c fish will try to
connect to the X-windows server specified by this variable, and use
the clipboard on the X server for copying and pasting.
\subsection history Searchable history
After a command has been entered, it is inserted at the end of a
history list. Any duplicate history items are automatically
removed. By pressing the up and down keys, the user can search
forwards and backwards in the history. If the current command line is
not empty when starting a history search, only the commands starting
with the string entered into the command line are searched.
The history is stored in the file '.fish_history'. It is automatically
read on startup and merged on program exit.
Example:
To search for previous entries starting with the letter 'l', type 'l'
in the console and press the up key.
\section job-control Running multiple programs
Normally when \c fish starts a program, this program will be put
in the foreground, meaning it will take control of the terminal and
\c fish will be stopped until the program finishes. Sometimes
this is not desirable. In such cases, there are several ways in which
the user can change <tt>fish</tt>'s behaviour.
-# By ending a command with the \& (ampersand) symbol, the user tells \c fish to put the specified command into the background. A background process will be run simultaneous with \c fish. \c fish will retain control of the terminal, so the program will not be able to read from the keyboard.
-# By pressing ^Z, the user stops a currently running foreground program and returns control to \c fish. Some programs do not support this feature, or remap it to another key. Gnu emacs uses ^X z to stop running.
-# By using the <a href="builtins.html#fg">fg</a> and <a href="builtins.html#bg">bg</a> builtin commands, the user can send any currently running job into the foreground or background.
- Multiple input characters should be inserted in one batch whenever possible, to avoid flickering
- Check keybinding commands for output - if non has happened, don't repaint to reduce flicker
- the jobs builtin should be able to give information on a specific job, such as the pids of the processes in the job
- Syntax highlighting should mark cd to non-existing directories as an error
\subsection todo-possible Possible features
- Multiline editing
- tab completion could use smart casing
- Completions could support options beginning with a plus (like xterm
+fbx) and options without dashes (like top p) Do we really want to
complicate the code additionally for such a small number of programs?
- mouse support like zsh has with http://stchaz.free.fr/mouse.zsh
installed would be awesome
- suggest a completion on unique matches by writing it out in an understated color
- Maybe some functions should only be available from key-bindings. That way one could implement a large part of all the key-binding functions as regular fish functions without worrying about cluttering up the function name space.
- With a bit of tweakage, quite a few of the readline key-binding functions could be implemented in shellscript.
- Highlight beginning/end of block when moving over a block command
- Do not actually load most of the shellscript functions on startup. Only load a tiny wrapper that will load the real function when needed. This should shave of CPU-time spent on parsing 500-1000 lines of code and ~50 kB of memory on startup, and is pretty easy to implement.
- Do not actually load/parse .fish_history, only mmap it and use some clever string handling. Should save ~150 kB of memory permanently, but is very hard to implement.
- show the whole list of commands on using tab on an empty commandline
- Automatically move cursor to the end of the current token before completing
- Map variables. (export only the values. When expanding with no key specified, expand to all values.)
- psub function/builtin to make somthing like process substitution using command substitution
\subsection bugs Known bugs
- Completion for gcc -\#\#\# option doesn't work.
- Many completions are made specifically for the GNU
version of a POSIX command
- Yanking weird characters from clipboard prints Unicode escapes
- Prefix string in completion display is sometimes incorrect
If you think you have found a bug not described here, please send a
report to <a href="mailto:axel@liljencrantz.se"> axel@liljencrantz.se
</a>.
\subsection Known issues
Older versions of Doxygen has bugs in the man-page generation which
cause the builtin help to render incorrectly. Version 1.2.14 is known
to have this problem.
In version 1.9.2, the installation prefix for fish rpms and debs
changed from /usr/local to /usr. Packages should automatically change
any instances of /usr/local/bin/fish in /etc/passwd to /usr/bin/fish,
but some programs, like screen, may need to be restarted to notice the
changes when upgrading from pre1.9.2 to 1.9.2 or later. You may also
run into such problems when switching between using a package and
personal builds.
*/
/** \page design Design document
\section design-overview Design document
\subsection design-overview Overview
This is a description of the design principles that have been used to
design fish. The fish design has three high level goals. These are:
-# Everything that can be done in other shell languages should be
possible to do in fish, though fish may rely on external commands in
doing so.
-# Fish should be user friendly, but not at the expense of expressiveness.
Most tradeoffs between power and ease of use can be avoided with careful design.
-# Whenever possible without breaking the above goals, fish should
follow the Posix syntax.
\subsection ortho The law of orthogonality
The shell language should have a small set of orthogonal features. Any
situation where two features are related but not identical, one of them
should be removed, and the other should be made powerful and general
enough to handle all common use cases of either feature.
Rationale:
Related features make the language larger, which makes it harder to
learn. It also increases the size of the sourcecode, making the
program harder to maintain and update.
Examples:
- Here documents are too similar to using echo inside of a pipeline.
- The different quoting styles are silly. ("", '' and \$'')
\subsection sep The law of minimalism
The shell should only contain features that cannot be implemented in
a reasonable way outside of the shell. A large performance decrease,
as well as some program complexity increase is acceptable in order to
improve separation.
Rationale:
A modular project is easier to maintain since smaller programs are far
easier to understand than larger ones. A modular project is also more
future proof since the modules can be individually
replaced. Modularity also decreases the severity of bugs, since there
is good hope that a bug, even a serious one, in one module, does not
take the whole system down.
Examples:
- Builtin commands should only be created when it cannot be
avoided. \c echo, \c kill, \c printf and \c time are among the commands
that fish does not implement internally since they can be provided as
external commands. Several other commands that are commonly implemented
as builtins and can not be implemented as external commands,
including \c type, \c vared, \c pushd and \c popd are implemented as shellscript
functions in fish.
- Mathematical calculations, regex matching, generating lists of numbers
and many other funtions can easily be done in external programs. They
should not be supported internally by the shell.
The law of minimalism does not imply that a large feature set is
bad. So long as a feature is not part of the language itself, but a
separate command or at least a shellscript function, bloat is much
more acceptable.
\subsection conf Configurability is the root of all evil
Every configuration option in a program is a place where the program
is too stupid to figure out for itself what the user really wants, and
should be considered a failiure of both the program and the programmer
who implemented it.
Rationale:
Different configuration options are a nightmare to maintain, since the
number of potential bugs caused by specific configuration combinations
quickly becomes an issue. Configuration options often imply
assumptions about the code which change when reimplementing the code,
causing issues with backwards compatibility. But mostly, configuration
options should be avoided since they simply should not exist, as the
program should be smart enough to do what is best, or at least a good
enough approximation of it.
Examples:
- Fish allows the user to set various syntax highlighting colors. This is needed because fish does not know what colors the terminal uses by default, which might make some things unreadable. The proper solution would be for text color preferences to be defined centrally by the user for all programs, and for the terminal emulator to send these color properties to fish.
- Fish does not allow you to set the history filename, the number of history entries, different language substyles or any number of other common cshell configuration options
A special note on the evils of configurability is the long list of
very useful features found in some shells, that are not turned on by
default. Both zsh and bash support command specific completions, but
no such completions are shipped with bash by default, and they are
turned of by default in zsh. Other features that zsh support that are
disabled by default include tab-completion of strings containing
wildcards, a sane completion pager and a history file.
\subsection user The law of user focus
When designing a program, one should first think about how to make a
intuitive and powerful program. Implementation issues should only be
considered once a user interface has been designed.
Rationale:
If too much attention is given to what is easy to implement the law of
orthogonality and the law of minimalism will by necessity be disobeyed.
Examples:
- There should only be one type of input to the shell, lists of commands. Loops, conditionals and variable assignments are all performed through regular commands.
- The differences between builtin commands, shellscript functions and builtin commands should be made as small as possible. Builtins and shellscript functions should have exactly the same types of argument expantion as other commands, should be possible to use in any position in a pipeline, and should support any io redirection.
- Instead of forking when performing command substitution to provide a fake variable scope, all fish commands are performed from the same process, and fish instead supports true scoping
- All blocks end with the \c end builtin
\subsection disc The law of discoverability
The shell should implement it's features in a way that makes them as
easy as possible for the user to discover for her/himself.
Rationale:
A program whose features are discoverable makes a new user into an
expert in a shorter span of time, since the user will learn how to use
the program simply by using it.
The main benefit of a graphical program over a command line-based
program is discoverability. In a graphical program, one can discover
all the common features by simply looking at the user interface and
guessing what the different buttons, menus and other widgets do. The
traditional way to discover features in commandline programs is
through manual pages. This requires both that the user starts to use a
different program, and the she/he then remembers the new information
until the next time she/he uses the same program.
Examples:
- Everything should be tab-completable, and every tab completion should have a description
- Every syntax error and error in a builtin command should contain an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged red by the syntax highlighter.
- The help manual should be easy to read, easily available from the shell, complete and contain many examples
- The language should be uniform, so that once the user understands the command/argument syntax, he will know the whole language, and be able to use tab-completion to discover new featues.
*/
/** \page about About fish
\section about-program About the program
\c fish is meant to be used for interactive shell tasks on a modern
UNIX-like workstation. It is much more important for me to keep the
code maintainable, readable and bug free than to support esoteric old
hardware, software or wetware. As such, the program is often wildly
inefficient in its use of memory and CPU cycles. On my system, \c fish
uses a little less than half a megabyte of memory, a number that could
be significantly reduced with a little effort. \c fish performs a lot
of linear searches of things that could be done in logarithmic time,
does not usually cache file system data or other search result, and
uses the fork() call promiscuosly. None of these things matter because
\c fish is still fast enough to be perceived as instantaneous on a
semi-modern computer thanks to the miracles of copy-on-write, OS-level
caching and Moores law, and it only uses a fraction of the memory used
by most terminal emulators to display it. If this program was anything
other than an amusing hobby for me, I would of course feel otherwise,
but since my time is limited, this is the way it must be.
\section about-code About the source code
Fish is written using the ellemtel indentation style, using four space
tabs. \c fish regularly performs a large set of sanity checks to make
sure it is in a sane state. If not, the program will terminate before
it can do any harm.
Do not edit the file builtin_help.c, it is automatically generated.
\section about-documentation About the documentation
The documentation for \c fish is written for Doxygen. All header files
are pretty heavily commented.
Since it was desirable to use the same text files for producing the
HTML documentation as for producing the internal help output, some
rather ugly kludges had to be used for writing the documentation for
the builtin commands.
The directory doc_src contains a file called doc.hdr, containing
various general documentation for \c fish, and a large number of .txt
files. Each txt file contains the documentation for one \c fish
builtin. When creating the main doxygen documentation, all these files
are concatenated into one file, called doc.h. When creating the
internal documentation, each of the .txt files is converted to a .h
file by supplying a doxygen header/footer. These headers are then
converted into man style manuals, which in turn are converted to C
code by a script called gen_hdr.sh. The resulting C-file,
builtin_help.c, can then by linked into \c fish. This method is probably
not the most robust, elegant or clever method for generating
documentation. If someone has a suggestion of how to do i better,
please notify me.
*/
/** \page difference Why fish?
\section difference-overview What is different about fish?
This page is a summary of differences between \c fish and other shells.
\subsection difference-completion Tab completion features
\c fish, like many other shells, performs tab completion, i.e. the shell
tries to guess what the user is typing and complete the users
sentences whenever the user presses the tab key. If the shell finds
more than one possible completion, a list of all completions is
displayed when the users double taps on tab. \c fish extends tab
completion functionality in several ways:
- \c fish performs file completion on strings containing wildcards
- When showing a list of possible completions, \c fish adds a
description to each completion. For files this description is a
description of the format or filetype, like 'C source code',
'Character device' or 'Executable'. For variables, if the
value is short enough, the variable value will be displayed. For
commands, if there is room and few enough commands, the whatis
description of the command is used.
- \c fish has extensive command specific completions, including
completion of specific options. This is very powerful in combination
with completion descriptions, as the user can see what each option does
without consulting the manual. Simply type the command you wish to use,
type a dash and double tab TAB, and the screen will fill with a list of
the commands options and a description of what they do.
- \c fish uses a decent pager when the results won't fit on one
screen. The pager can scroll up and down, both one row and one page at
a time, and if any non movement key is pressed the pager exits without
consuming the character. Therefore, there is no need to press
'q' to exit before typing your completion.
Some examples of the completions performed by \c fish
- When completing an argument for the man command, the whatis
database is searched for manual pages as completions.
- When completing a command name, the whatis database is searched
for each possible command, and the description returned is used
as the description of the command.
- When completing an argument for the make command, the Makefile
in the current directory is searched for targets.
\subsection difference-killring X-Windows Copy and paste
\c fish supports using the X-Windows clipboard for storing copy and
paste information. This feature is automatically enabled if the
DISPLAY environment variable is set. For more information on how to
use copy and paste in \c fish, read <a href="index.html#killring">
this section</a>. This means you can easily share commands and strings
between different shell sessions and applications.
\subsection difference-open Simple launching of default applications
The open command uses the mimetype database (Also used by both Gnome
or KDE) to launch the default application for a file. Just type
<tt>open *.html</tt> and all the HTML files in your current directory
will be opened in your default browser. No longer will you have to
convert your filenames to URLS, remember clunky Open Office command
names, worry about absolute paths or any the other common pitfalls when
opening files from the commandline.
\subsection difference-help Help
\c fish is heavily commented. Both the source code and the
program in general features a great deal of easily accessible
documentation. The <tt>help</tt> command is used to display HTML-based
help files. Just type <tt>help</tt> and a subject, and the help system
will try to fill your needs. To view the page you are reading right
now, you could simply type <tt>help difference</tt>. <tt>help</tt>
also works great together with tab completion. Write \c help and
double tap on tab, a list of all help sections will be displayed, with
a description of the content of each section.
Also, all builtin commands have a help option. Passing '-h' or
'--help' to any builtin will give you the same help as the help
