fish
, the friendly interactive shell. fish
is a user friendly commandline shell intended mostly for interactive use. A shell is a program used to execute other programs. For the latest information on fish
, please visit the fish
homepage.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'. Everything in fish is done with commands. There are commands for performing a set of commands multiple times, commands for assigning variables, commands for treating a group of commands as a single command, etc.. And every single command follows the same simple syntax.
If you wish to find out more about the echo command used above, 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 your 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 (i.e. by pressing the return key) 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', while
rm cumbersome filename.txt
would remove the two files 'cumbersome' and 'filenmae.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'\xxx'
, where xx
is a hexadecimal number, escapes the ascii character with the specified value'\oooo'
, where ooo
is an octal number, escapes the ascii character with the specified value'\uxxxx'
, where xxxx
is a hexadecimal number, escapes the 16-bit unicode character with the specified value'\Uxxxxxxxx'
, where xxxxxxxx
is a hexadecimal number, escapes the 32-bit unicode character with the specified value
The reason for providing for two methods of output is that errors and warnings can be separated from regular program output.
Any file descriptor can be directed to a different output than it's default through a simple mechanism called a redirection.
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.
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
.
Pipes usually connect file descriptor 1 (standard output) of the first process to file descriptor 0 (standard input) of the second process. It is possible use a different output file descriptor by prepending the desired FD number and then output redirect symbol to the pipe. For example:
make fish 2>|less
will attempt to build the fish program, and any errors will be shown using the less pager.
fish
, fish
itself will pause, and give control of the terminal to the program just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append a & (ampersand) to your command. This will tell fish to run the job in the background.fish
by Pressing ^Z (Press and hold the Control key and press 'z'). Once back at the fish
commandline, you can start other programs and do anything you want. If you then want to go back to the suspended command by using the fg command.If you instead want to put a suspended job into the foreground, use the fg command.
To get a listing of all currently started jobs, use the jobs command.
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 fish
can only find 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 pressed 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:
apt-get
, rpm
and yum
commands use all installed packages as completions.complete
command. complete
takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program myprog
, one would start the completion command with complete -c myprog ...
. To provide a list of possible completions for myprog, use the -a
switch. If myprog
accepts the arguments start and stop, this can be specified as complete -c myprog -a 'start stop'
. The argument to the -a
switch is always a single string. At completion time, it will be tokenized on spaces and tabs, and variable expansion, command substitution and other forms of parameter expansion will take place.
Fish has a special syntax to support specifying switches accepted by a command. The switches -s
, -l
and -o
are used to specify a short switch (single character, such as -l), a gnu style long switch (such as --color) and an old-style long switch (like -shuffle), respectively. If the command 'myprog' has an option '-o' which can also be written as '--output', and which can take an additional value of either 'yes' or 'no', this can be specified by writing:
complete -c myprog -s o -l output -a "yes no"
There are also special switches for specifying that a switch requires an argument, to disable filename completion, to create completions that are only available in some combinations, etc.. For a complete description of the various switches accepted by the complete
command, see the documentation for the complete builtin, or write 'complete --help' inside the fish
shell.
For examples of how to write your own complex completions, study the completions in /etc/fish.d/completions (or ~/etc/fish.d/completions if you installed fish in your home directory).
If you wish to use a completion, you should consider adding it to your startup files. When completion has been requested for a command COMMAND
, fish will automatically look for the file ~/.fish.d/completions/COMMAND.fish. If it exists, it will be automatically loaded. If you have written new completions for a common Unix command, please consider sharing your work by sending it to the fish mailinglist.
fish
attempts to match 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*
matches any files beginning with an 'a' in the current directory.
???
matches any file in the current directory whose name is exactly three characters long.
If no matches are found for a specific wildcard, it will expand into zero arguments, i.e. to nothing. If none of the wildcarded arguments sent to a command result in any matches, the command will not be executed. If this happens when using the shell interactively, a warning will also be printed.
Example:
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 embed a variable inside running text like echo Konnichiwa {$USER}san
, which will print a personalized Japanese greeting.
The {$USER}san syntax might need a bit of an elaboration. Posix shells allow you to specify a variable name using '$VARNAME' or '${VARNAME}'. Fish only supports the former, but has no support whatsoever for the latter or anything remotely like it. So what is '{$VARNAME}' then? Well, '{WHATEVER}' is brace expansion, the same as supported by Posix shells, i.e. 'a{b,c}d' -> 'abd acd' works both in bash and on fish. So '{$VARNAME}' is a bracket-expansion with only a single element, i.e. it becomes expanded to '$VARNAME', which will be variable expanded to the value of the variable 'VARNAME'. So you might think that the brackets don't actually do anything, and that is nearly the truth. The snag is that there once along the way was a '}' in there somewhere, and } is not a valid character in a variable name. So anything after the otherwise pointless bracket expansion becomes NOT a part of the variable name, even if it happens to be a legal variable name character. That's why '{$USER}san' looks for the variable '$USER' and not for the variable '$USERsan'. It's a case of one syntax lending itself nicely to solving an unrelated problem in it's spare time.
Variable expansion is the only type of expansion performed on double quoted strings. There is, however, an important difference in how variables are expanded when quoted and when unquoted. An unquoted variable expansion will result in a variable number of arguments. For example, if the variable $foo has zero elements or is undefined, the argument $foo will expand to zero elements. If the variable $foo is an array of five elements, the argument $foo will expand to five elements. When quoted, like "$foo", a variable expansion will always result in exactly one argument. Undefined variables will expand to the empty string, and array variables will be concatenated using the space character.
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
, write $ (dollar symbol) followed by the name of the variable, like echo Smurfs are $smurf
, which would print the result 'Smurfs are blue'.
set -e
. 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 'for
, 'while'
, 'if'
, 'function'
, 'begin'
or 'switch'
, and ends with the command 'end'
. The user can specify that a variable should have either global or local scope using the -g/--global
or -l/--local
switches.
Variables can be explicitly set to be universal with the -U
or --universal
switch, global with the -g
or --global
switch, or local with the -l
or --local
switch. The scoping rules when creating or updating a variable are:
There may be many variables with the same name, but different scopes. 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.
Example:
The following code will not output anything:
begin # This is a nice local scope where all variables will die set -l pirate 'There be treasure in them thar hills' end
# This will not output anything, since the pirate was local echo $pirate
To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them set fish_color_cwd blue
. Since 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.
For example, the following code will output 'Avast, mateys':
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
Variables can be explicitly set to be exported with the -x
or --export
switch, or not exported with the -u
or --unexport
switch. The exporting rules when creating or updating a variable are identical to the scoping rules for variables:
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
It is also possible to set or erase individual elements of an array:
#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
fish
by changing the values of certain environment variables.
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_substitution
, fish_color_redirection
, fish_color_end
, fish_color_error
, fish_color_param
, fish_color_comment
, fish_color_match
, fish_color_search_match
, fish_color_cwd
, fish_pager_color_prefix
, fish_pager_color_completion
, fish_pager_color_description
and fish_pager_color_progress
are used to change the color of various elements in 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.PATH
, which is an array of directories in which to search for commandsumask
, which is the current file creation mask. The preferred way to change the umask variable is through the umask shellscript function. An attempt to set umask to an invalid value will always fail.
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.history
, which is an array containing the last commands that where entered.HOME
, which is the users home directory. This variable can only be changed by the root user.PWD
, 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.USER
, which is the username. This variable can only be changed by the root user.LANG
, LC_ALL
, LC_COLLATE
, LC_CTYPE
, LC_MESSAGES
, LC_MONETARY
, LC_NUMERIC
and LC_TIME
set the language option for the shell and subprograms. See the section Locale variables for more information.
Variables whose name are in uppercase are exported to the commands started by fish. This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables. fish
also uses several variables internally. Such variables are prefixed with the string __FISH or __fish. These should be ignored by the user.
LANG
, LC_ALL
, LC_COLLATE
, LC_CTYPE
, LC_MESSAGES
, LC_MONETARY
, LC_NUMERIC
and LC_TIME set the language option for the shell and subprograms. These variables work as follows: LC_ALL
forces all the aspects of the locale to the specified value. If LC_ALL is set, all other locale variables will be ignored. The other LC_ variables set the specified aspect of the locale information. LANG is a fallback value, it will be used if none of the LC_ variables are specified.
fish
only implementing builtins for actions which cannot be performed by a regular command.
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 many editor functions that can be bound to special keyboard shortcuts. The most important keybinding is probably the tab key, which is bound to the complete function. Here are some of the commands available in the editor:
You can change these key bindings by making an inputrc file. To do this, copy the file /etc/fish_inputrc to your home directory and rename it to '.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 that the list of key binding functions in fish is different to that offered by readline. Currently, the following functions are available:
backward-char
, moves one character to the leftbackward-delete-char
, deletes one character of input to the left of the cursorbackward-kill-line
, move everything from the beginning of the line to the cursor to the killringbackward-kill-word
, move the word to the left of the cursor to the killringbackward-word
, move one word to the leftbeginning-of-history
, move to the beginning of the historybeginning-of-line
, move to the beginning of the linecomplete
, guess the remainder of the current tokendelete-char
, delete one character to the right of the cursordelete-line
, delete the entire linedump-functions
, print a list of all key-bindingsend-of-history
, move to the end of the historyend-of-line
, move to the end of the lineexplain
, print a description of possible problems with the current commandforward-char
, move one character to the rightforward-word
, move one word to the righthistory-search-backward
, search the history for the previous matchhistory-search-forward
, search the history for the next matchkill-line
, move everything from the cursor to the end of the line to the killringkill-whole-line
, move the line to the killringkill-word
, move the next word to the killringyank
, insert the latest entry of the killring into the bufferyank-pop
, rotate to the previous entry of the killringYou can also bind a pice of shellscript to a key using the same syntax. For example, the Alt-p functionality described above is implemented using the following keybinding.
"\M-p": if commandline -j|grep -v 'less *$' >/dev/null; commandline -aj "|less;"; end
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.
By pressing Alt-up and Alt-down, a history search is also performed, but instead of searching for a complete commandline, each commandline is tokenized into separate elements just like it would be before execution, and each such token is matched agains the token under the cursor when the search began.
History searches can be aborted by pressing the escape key.
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 containing the word 'make', type 'make' 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. For example, you may wish to start an application with a graphical user interface from the terminal, and then be able to continue using the shell. 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 (Or ~/etc/fish if you installed fish in your home directory) and ~/.fish, in that order. If you want to run a command only on starting an interactive shell, use the exit status of the command 'status --is-interactive' to determine if the shell is interactive. If you want to run a command only on starting a login shell, use 'status --is-login' instead.Example:
If you want to add the directory ~/linux/bin to your PATH variable when loging in, add the following to your ~/.fish file:
if status --is-login set PATH $PATH ~/linux/bin end
If you want to run a set of commands when fish
exits, use an event handler that is triggered by the exit of the shell:
function on_exit --on-process self echo fish is now exiting end
Universal variables are stored in the file .fishd.HOSTNAME, where HOSTNAME is the name of your computer. Do not edit this file directly, edit them through fish scripts or by using fish interactively instead.
fish
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:
When the cursor is over a parenthesis or a quote, fish
also highlights it's matching quote or parenthesis.
To customize the syntax highlighting, you can set the environment variables fish_color_normal
, fish_color_command
, fish_color_substitution
, fish_color_redirection
, fish_color_end
, fish_color_error
, fish_color_param
, fish_color_comment
, fish_color_match
, fish_color_search_match
, fish_color_cwd
, fish_pager_color_prefix
, fish_pager_color_completion
, fish_pager_color_description
and fish_pager_color_progress
. Valid values are 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 foreground color for the terminal.
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" printf '%s@%s%s%s%s> ' (whoami) (hostname|cut -d . -f 1) (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) end
where prompt_pwd
is a shellscript function that displays a condensed version of the current working direcotry.
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
function fish_title echo $_ ' ' pwd end
When a signal is delivered When a process or job exits When the value of a variable is updated
Example:
To specify a signal handler for the WINCH signal, write:
function --on-signal WINCH my_signal_handler echo Got WINCH signal! end
For more information on how to define new event handlers, see the documentation for the function command.
To make a translation of fish, you will first need the sourcecode, available from the fish homepage. Download the latest version, and then extract it using a command like tar -zxf fish-VERSION.tar.gz
.
Next, cd into the newly created fish directory using cd fish-VERSION
.
You will now need to configure the sourcecode using the command ./configure
. This step might take a while.
Before you continue, you will need to know the ISO 639 language code of the language you are translating to. These codes can be found here. For example, the language code for Uighur is ug.
Now you have the sourcecode and it is properly configured. Lets start translating. To do this, first create an empty translation table for the language you wish to translate to by writing make po/[LANGUAGE CODE].po
in the fish terminal. For example, if you are translating to Uighur, you should write make po/ug.po
. This should create the file po/ug.po, a template translation table containing all the strings that need to be translated.
Now you are all set up to translate fish to a new language. Open the newly created .po file in your editor of choice, and start translating. The .po file format is rather simple. It contains pairs of string in a format like:
msgid "%ls: No suitable job\n" msgstr ""
The first line is the english string to translate, the second line should contain your translation. For example, in swedish the above might become:
msgid "%ls: No suitable job\n" msgstr "%ls: Inget jobb matchar\n"
s, ls, d and other tokens beginning with a '' are placeholders. These will be replaced by a value by fish at runtime. You must always take care to use exactly the same placeholders in the same order in your translation. (Actually, there are ways to avoid this, but they are to complicated for this short introduction. See the full manual for the printf C function for more information.)
Once you have provided a translation for fish, please send it to fish-users@lists.sf.net.
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.