fish home | Main documentation page | About fish | External commands | How fish differs from other shells | Builtin commands | License

fish

1

A shell is a program which allows you to execute other programs by typing their names. For updates on fish, go to the fish homepage.

Syntax overview

Shells like fish are used by giving them commands. Every fish command follows the same simple syntax.

A command is executed by writing the name of the command followed by any arguments.

Example:

echo hello world

calls the echo command. echo is a command which will write its arguments to the screen. In the example above, the output will be 'hello world'.

If you wish to find out more about the echo command, read the manual page for the echo command by writing:

man echo

man is a command for displaying a manual page on a given topic. There are manual pages for almost every command on most computers. There are also manual pages for many other things, such as system libraries and important files.

Every program on a computer can be used as a command in fish. If the program file is located in one of the directories in the PATH, it is sufficient to type the name of the program to use it. Otherwise the whole filename, including the directory (like /home/me/code/checkers/checkers or ../checkers) has to be used.

Here is a list of some useful commands:

Commands and parameters are separated by the space character ( ). Every command ends with either a newline or a semicolon (;). More than one command can be written on the same line by separating them with semicolons.

Quotes

Sometimes features such as parameter expansion and character escapes get in the way. When that happens, the user can write a parameter within quotes, either ' (single quote) or " (double quote). There is no difference between single quoted and double quoted strings. A quoted parameter will not be parameter expanded, may contain spaces, and the only escape sequences allowed is the corresponding quote character. Single and double quotes may be nested.

Example:

rm "cumbersome filename.txt"

Will remove the file 'cumbersome filename.txt'.

Escaping characters

Some characters can not be written directly on the command line. For these characters, so called escape sequences are provided. These are:

IO redirection

Most program use three types of input/output (IO), each represented by a number called a file descriptor (FD). These are:

The reason for providing for two methods of output is so errors and warnings can be separated from program output.

Any file descriptor can be directed to a different output than it's default through a simple mechanism called a redirecton.

An example of a file redirection is echo hello >output.txt, which directs the output of the echo command to the file error.txt.

DESTINATION can be one of the following:

Example:

To redirect both standard output and standard error to the file all_output.txt, you can write echo Hello >all_output.txt ^&1.

Any FD can be redirected in an arbitrary way by prefixing the redirection with the number of the FD.

Example: echo Hello 2>- and echo Hello ^- are equivalent.

Piping

The user can string together multiple commands in a so called pipe. This means that the standard output of one command will be read in as standard input into the next command. This is done by separating the commands by the pipe character (|).

For example

cat foo.txt | head

will call the 'cat' program with the parameter 'foo.txt', which will print the contents of the file 'foo.txt'. The contents of foo.txt will then be filtered through the program 'head', which will pass on the first ten lines of the file to the screen. For more information on how to combine commands through pipes, read the manual pages of the commands you want to use using the 'man' command. If you want to find out more about the 'cat' program, type man cat.

Help

fish has an extensive help system. Use the help command to obtain help on a specific subject or command. For instance, writing help syntax displays the syntax section of this documentation.

Help on a specific builtin can also be obtained with the -h parameter. For instance, to obtain help on the fg builtin, either type fg -h or help fg.

Tab completion

Tab completion is one of the most time saving features of any modern shell. By tapping the tab key, the user asks fish to guess the rest of the command or parameter that the user is currently typing. If there is only one possible completion, fish will write it out. If there is more than one completion, fish will write out the longest common prefix that all completions have in common. If all completions differ on the first character, a list of all possible completions is printed. The list features descriptions of the completions and if the list doesn't fit the screen, it is scrollable by using the arrow keys, the page up/page down keys or the space bar. Press any other key will exit the list and insert the presssed key into the command line.

These are the general purpose tab completions that fish provides:

fish provides a large number of program specific completions. Most of these completions are simple options like the -l option for ls, but some are more advanced. The latter include:

Specifying your own completions is easy. If the command 'myprog' has an option '-o' which can also be written as '--output', which requires an additional value of either 'yes' or 'no' and decides if the program should write anything, this can be specified by writing:

complete -c myprog -s o -l output -r -a "yes no" -d "Write output"

For a more complete description of how to specify your own completions, go here or write 'complete --help' in the fish shell.

If you wish to use a completion, you should consider adding it to your startup files. This can be done by editing the file '.fish' in your home directory.

Parameter expansion (Globbing)

There are many ways in which the user can specify a parameter to be expanded. These include:

Wildcards

If a star (*) or a question mark (?) is present in the parameter, fish will attempt to mach the given parameter to any files in such a way that '?' can match any character except '/' and '*' can match any string of characters not containing '/'.

Example: a* will match any files beginning with an 'a' in the current directory.

??? will match any file in the current directory whose name is exactly three characters long.

Subshells

A string of character enclosed in parenthesis will be executed in a subshell, and each line of output will become a new parameter.

Example:

If the current directory contains the files 'foo' and 'bar', the command echo (basename image.jpg .jpg).png will output 'image.png'.

The command for i in *.jpg; convert $i (basename $i .jpg).png; end will convert all Jpeg files in the current directory to the PNG format.

Brace expansion

A comma separated list of characters enclosed en curly braces will be expanded so each element of the list becomes a new parameter.

Example:

echo input.{c,h,txt} outputs 'input.c input.h input.txt'

The command mv *.{c,h} src/ moves all files with the suffix '.c' or '.h' to the subdirectory src.

Variable expansion

A dollar sign followed by a string of characters is expanded into the value of the environment variable with the same name. For an introduction to the concept of environment variables, read the Environment variables section.

Example:

echo $HOME 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 specify the end of the variable name like echo Konnichiwa {$USER}san, which will print a personalized Japanese greeting.

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.

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:

This form of expansion is useful for commands like kill and fg, which take the process ids as an argument.

Example:

fg %ema will search for a process whose command line begins with the letters 'ema', such as emacs, and if found, put it in the foreground.

kill -s SIGINT %3 will send the SIGINT signal to the job with job id 3.

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 echo a(ls){1,2,3} will output 'abar1 abar2 abar3 afoo1 afoo2 afoo3'.

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 set command.

Example:

To set the variable smurf to the value blue, use the command set smurf blue.

After a variable has been set, you can use the value of a variable in the shell through variable expansion.

Example:

To use the value of a the variable smurf, use the command echo Smurfs are $smurf, which would print the result 'Smurfs are blue'.

If the -x or --export option is supplied, the variable will be inherited by commands started by fish. It is convention that exported variables are in uppercase and unexported variables are in lowercase.

By default, new variables are inserted into the current block. This means that when the current block goes out of scope, the variable will dissapear. To make a variable global, use the -g or --global switch.

Arrays

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:

echo $PATH[3]

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:

for i in $PATH; echo $i is in the path; end

To create a variable smurf, containing the items blue and small, simply write:

set smurf blue small

If you wish to assign a new value to one element of an array, write:

set smurf[2] evil

Special variables

The user can change the settings of fish by changing the values of certain environment variables.These are:

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:

fish also uses several variables internally. Such variables are prefixed with the string __FISH or __fish. These should be ignored by the user.

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, fish only implementing builtins for actions which cannot be performed by a regular command.

The following builtin commands are available in fish:

For more information about these commands, use the --help option of the command to display a longer explanation.

Command Line editor

The fish editor features copy and paste, a searchable history and several editor commands. These are some of the commands available in the editor:

You can change these key bindings making an inputrc file. To do this, copy the file /etc/fish_inputrc to your home directory and rename it to '.fish_inputrc'. You can do this by running the command mv /etc/fish_inputrc ~/.fish_inputrc. Now you can edit the file .fish_inputrc, to change your key bindings. The fileformat of this file is described in the manual page for readline. Use the command man readline to read up on this syntax. Please note thet the key binding support in fish is still limited. You can not use the set command or the keyname-syntax, and the list functions is incomplete. Currently, only the following functions are supported:

Copy and paste (Kill Ring)

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, 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.

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.

Running multiple programs

Normally when fish starts a program, this program will be put in the foreground, meaning it will take control of the terminal and 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 fish's behaviour.

  1. By ending a command with the & (ampersand) symbol, the user tells fish to put the specified command into the background. A background process will be run simultaneous with fish. fish will retain control of the terminal, so the program will not be able to read from the keyboard.
  2. By pressing ^Z, the user stops a currently running foreground program and returns control to fish. Some programs do not support this feature, or remap it to another key. Gnu emacs uses ^X z to stop running.
  3. By using the fg and bg builtin commands, the user can send any currently running job into the foreground or background.

Initialization files

On startup, fish evaluates the file /etc/fish and ~/.fish, in that order. If you want to run a command only on starting an interactive shell, test if the environment variable fish_interactive is set. If you want to run a command only on starting a login shell, test if the environment variable fish_login is set.

If you want to run a set of commands when fish exits, redefine the function hook fish_on_exit. If the fish_on_exit is defined, it will be execute before the shell exits.

Other features

Syntax highlighting

fish will interprets the command line as it is typed and uses syntax highlighting to provide feedback to the user. The most important feedback is the detection of potential errors. By default, errors are marked red.

Detected errors include:

To customize the syntax highlighting, you can set the environment variables FISH_COLOR_NORMAL, FISH_COLOR_COMMAND, FISH_COLOR_SUBSHELL, FISH_COLOR_REDIRECTION, FISH_COLOR_END, FISH_COLOR_ERROR, FISH_COLOR_PARAM and FISH_COLOR_COMMENT to be one of black, red, green, brown, yellow, blue, magenta, purple, cyan, white or normal. Setting one of the above variables to normal will mean that the text color will be set to the default color for the terminal.

When the cursor is over a parenthesis or a quote, fish also highlights it's matching quote or parenthesis.

Programmable prompt

By defining the fish_prompt function, the user can choose a custom prompt. The fish_prompt function is executed and the output is used as a prompt.

Example:

The default fish prompt is

function fish_prompt -d "Write out the prompt"
	whoami
	echo @
	hostname|cut -d . -f 1
	echo ' '
	set_color green
	printf '
' prompt_pwd set_color normal printf '
> ' end

Programmable title

When running in a virtual terminal, the user define the fish_title function to print a custom titlebar message. The fish_title function is executed and the output is used as a titlebar message.

Example:

The default fish title is equivalent to

function fish_title
	echo $_ ' '
	pwd
end

Event hooks

There are several special function names in fish. If a function is given this name, it will be automatically called when a specific event has occured. These functions are:

Missing features and bugs

Missing features

  1. Fix bug that causes the 'script' command to hang on exit
  2. Add vi-mode key bindings
  3. Fix redirection of blocks
  4. Process expantion should expand jobs to the jobs process group, prepended with a minus
  5. '**' wildcard for recursive wildcard matching
  6. The commandline builtin should be much more powerful. You should be able to get, replace or append to the current token, or the whole buffer and move the cursor, list all tokens, substitute or append to arbitrary tokens, remove and insert tokens.
  7. next-history-complete
  8. builtin ulimit command
  9. builtin wait command
  10. More completions (for example xterm, vim, konsole, gnome-terminal, dcop, cdrecord, cron, xargs rlogin, telnet, rsync, arch, finger, nice, locate, latex, bibtex, diff, patch, gcc, aspell, xpdf, wget, uptime zip, compress, yum, wine, xmms, dig, wine, at, batch, cron, g++, javac, java, gcj, lpr, rpm, doxygen, whois, find)
  11. Undo support
  12. A directory history

Possible features

Known bugs

There are currently some issues with piping and redirecting output from functions. You should avoid outputing binary data from a function, since it will be buffered by fish and treated as text data.

If you think you have found a bug not described here, please send a report to axel@liljencrantz.se .

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.


Generated on Wed Jun 22 08:48:35 2005 for fish by  doxygen 1.4.3-20050530