fish
, go to the fish
homepage.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:
cd
, change the current directoryls
, list the contents of a directoryman
, print a manual pagemv
, move filescp
, copy filesopen
, open files with the default application associated with each filetypeless
, read the contents of filesCommands 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.
Example:
rm "cumbersome filename.txt"
Will remove the file 'cumbersome filename.txt'.
'\n'
, escapes a newline character'\t'
, escapes the tab character'\b'
, escapes the backspace character'\r'
, escapes the carriage return character'\e'
, escapes the escape character'\ '
, escapes the space character'\$'
, escapes the dollar character'\\'
, escapes the backslash character'\*'
, escapes the star character'\?'
, escapes the question mark character'\~'
, escapes the tilde character'\#'
, escapes the hash character'\('
, escapes the left parenthesis character'\)'
, escapes the right parenthesis character'\{'
, escapes the left curly bracket character'\}'
, escapes the right curly bracket character'\['
, escapes the left bracket character'\]'
, escapes the right bracket character'\<'
, escapes the less than character'\>'
, escapes the more than character'\^'
, escapes the circumflex character
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.
<SOURCE_FILE
>DESTINATION
^DESTINATION
>>DESTINATION_FILE
^^DESTINATION_FILE
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.
N<DESTINATION
N>DESTINATION
N>>DESTINATION_FILE
Example: echo Hello 2>-
and echo Hello ^-
are equivalent.
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
.
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
.
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.
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.
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.
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.
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.
self
, the shells pid is the resultThis 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.
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'.
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.
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
fish
by changing the values of certain environment variables.These are:
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.CDPATH
, which is an array of directories in which to search for the new directory for the cd
builtin.fish_color_normal
, fish_color_command
, fish_color_subshell
, fish_color_redirection
, fish_color_end
, fish_color_error
, fish_color_param
, fish_color_comment
, fish_color_match
, fish_color_search_match
, fish_color_pager_prefix
, fish_color_pager_completion
, fish_color_pager_description
and fish_color_pager_progress
are used to change the color of various elements in fish
.PATH
, which is an array of directories in which to search for commands
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:
_
, which is the name of the currently running command.fish_interactive
, which is only defined if the shell is reading from the keyboard, i.e. interactively.fish_login
, which is only defined if the shell is a login shell.history
, which is an array containing the last commands that where enteredPWD
, which is the current working directory.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.
fish
also uses several variables internally. Such variables are prefixed with the string __FISH or __fish. These should be ignored by the user.
fish
only implementing builtins for actions which cannot be performed by a regular command.
The following builtin commands are available in fish:
fish
to quit
For more information about these commands, use the --help
option of the command to display a longer explanation.
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:
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.
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.
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.
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.fish
. Some programs do not support this feature, or remap it to another key. Gnu emacs uses ^X z to stop running.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.
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.
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
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
fish_on_exit
, which is called before the shell exitsfish_on_exec
, which is called before interactively executing a commandfish_on_return
, which is called when control returns to the shell after interactively executing a command
make
target completion includes spaces between target name and colonfish
starts up slowly on some systems. *cough* Slolaris *cough* To improve startup time one could replace the huge completion file with one file for each command completion which could be loaded the first time that command is used.fish
seems to cause programs to hang, without exiting. Specifically, one user has had the problem that the rpm command hangs in fish
, but not in other shells. This seems to be caused by the lack of an exec builtin in fish. Thanks to Vidar Lökken for explaining this bug.If you think you have found a bug not described here, please send a report to axel@liljencrantz.se .
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.