FreeBSD Manual Pages
FISH-DOC(1) fish-shell FISH-DOC(1) NAME fish-doc - fish-shell Documentation This is the documentation for fish, the friendly interactive shell. A shell is a program which helps you operate your computer by starting other programs. fish offers a command-line interface focused on usabil- ity and interactive use. Unlike other shells, fish does not follow the POSIX standard, but still roughly belongs to the same family. Some of the special features of fish are: o Extensive UI: syntax highlighting, autosuggestions, tab completion and selection lists that can be navigated and filtered. o No configuration needed: fish is designed to be ready to use immedi- ately, without requiring extensive configuration. o Easy scripting: new functions can be added on the fly. The syntax is easy to learn and use. This bit of the documentation is a quick guide on how to get going. If you are new to this, see the tutorial. This section is on how to install, uninstall, start and exit a fish shell and on how to make fish the default shell: o Installation: How to install fish o Starting and Exiting How to start and exit a fish shell o Executing Bash: How to execute bash commands in fish o Default Shell: How to switch to fish as the default shell o Uninstalling: How to uninstall fish INSTALLATION Up-to-date instructions for installing the latest version of fish are on the fish homepage. To install the development version of fish see the instructions at the project's GitHub page. STARTING AND EXITING Once fish has been installed, open a terminal. If fish is not the de- fault shell: o Enter fish to start a fish shell: > fish o Enter exit to exit a fish shell: > exit EXECUTING BASH If fish is your default shell and you want to copy commands from the internet that are written in a different shell language, bash for exam- ple, you can proceed in the following way: Consider, that bash is also a command. With man bash you can see that there are two ways to do this: o bash has a switch -c to read from a string: > bash -c SomeBashCommand or bash without a switch, opens a bash shell that you can use and exit afterwards. DEFAULT SHELL You can make fish your default shell by adding fish's executable in two places: - add /usr/local/bin/fish to /etc/shells - change your default shell with chsh -s to /usr/local/bin/fish For for detailed instructions see Switching to fish. UNINSTALLING For uninstalling fish: see FAQ: Uninstalling fish. SHEBANG LINE Since scripts for shell commands can be written in many different lan- guages, they need to carry information about what interpreter is needed to execute them: For this they are expected to have a first line, the shebang line, which names an executable for this purpose: Example: A scripts written in bash it would need a first line like this: #!/bin/bash This line tells the shell to execute the file with the bash inter- preter, that is located at the path /bin/bash. For a script, written in another language, just replace the interpreter /bin/bash with the language interpreter of that other language (for ex- ample /bin/python for a python script) This line is only needed when scripts are executed without specifying the interpreter. For functions inside fish or when executing a script with `fish /path/to/script they aren't required (but don't hurt ei- ther!). Shells like fish are used by giving them commands. Every fish command follows the same basic syntax. A command is executed by writing the name of the command followed by any arguments. Example: echo hello world This calls the echo command. echo is a command which will write its ar- guments 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 com- mand, etc.. And every single command follows the same basic syntax. If you want 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. The man command takes the name of the manual page to display as an argument. There are manual pages for almost every command on most computers. There are also manual pages for many other things, such as system li- braries 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, you can just use the name of the program to use it. Otherwise the whole file- name, including the directory (like /home/me/code/checkers/checkers or ../checkers) has to be used. Here is a list of some useful commands: o cd, change the current directory o ls, list files and directories o man, display a manual page on the screen o mv, move (rename) files o cp, copy files o open, open files with the default application associated with each filetype o less, list the contents of files Commands 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. A switch is a very common special type of argument. Switches almost al- ways start with one or more hyphens '-' and alter the way a command op- erates. For example, the 'ls' command usually lists all the files and directories in the current working directory, but by using the '-l' switch, the behavior of 'ls' is changed to not only display the file- name, but also the size, permissions, owner and modification time of each file. Switches differ between commands and are documented in the manual page for each command. Some switches are common to most command though, for example '--help' will usually display a help text, '-i' will often turn on interactive prompting before taking action, while '-f' will turn it off. SOME COMMON WORDS This is a short explanation of some of the commonly used words in fish. o argument a parameter given to a command o builtin a command that is implemented in the shell. Builtins are com- mands that are so closely tied to the shell that it is impossible to implement them as external commands. o command a program that the shell can run. In another sense also specifically an external command (i.e. neither a function or builtin). o function a block of commands that can be called as if they were a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command. o job a running pipeline or command o pipeline a set of commands stringed together so that the output of one command is the input of the next command o redirection an operation that changes one of the input/output streams associated with a job o switch a special flag sent as an argument to a command that will al- ter the behavior of the command. A switch almost always begins with one or two hyphens. 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 one important difference between single quoted and double quoted strings: When using double quoted string, variable expansion still takes place. Other than that, no other kind of expansion (including brace expansion and parameter expansion) will take place, the parameter may contain spaces, and escape sequences are ignored. The only backslash escape accepted within single quotes is \', which escapes a single quote and \\, which escapes the backslash symbol. The only backslash escapes accepted within double quotes are \", which es- capes a double quote, \$, which escapes a dollar character, \ followed by a newline, which deletes the backslash and the newline, and lastly \\, which escapes the backslash symbol. Single quotes have no special meaning within double quotes and vice versa. Example: rm "cumbersome filename.txt" Will remove the file 'cumbersome filename.txt', while rm cumbersome filename.txt would remove the two files 'cumbersome' and '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: o \a represents the alert character o \b represents the backspace character o \e represents the escape character o \f represents the form feed character o \n represents a newline character o \r represents the carriage return character o \t represents the tab character o \v represents the vertical tab character o \ escapes the space character o \$ escapes the dollar character o \\ escapes the backslash character o \* escapes the star character o \? escapes the question mark character (this is not necessary if the qmark-noglob feature flag is enabled) o \~ escapes the tilde character o \# escapes the hash character o \( escapes the left parenthesis character o \) escapes the right parenthesis character o \{ escapes the left curly bracket character o \} escapes the right curly bracket character o \[ escapes the left bracket character o \] escapes the right bracket character o \\< escapes the less than character o \\> escapes the more than character o \^ escapes the circumflex character o \& escapes the ampersand character o \| escapes the vertical bar character o \; escapes the semicolon character o \" escapes the quote character o \' escapes the apostrophe character o \xHH, where HH is a hexadecimal number, represents the ascii charac- ter with the specified value. For example, \x9 is the tab character. o \XHH, where HH is a hexadecimal number, represents a byte of data with the specified value. If you are using a multibyte encoding, this can be used to enter invalid strings. Only use this if you know what you are doing. o \ooo, where ooo is an octal number, represents the ascii character with the specified value. For example, \011 is the tab character. o \uXXXX, where XXXX is a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example, \u9 is the tab character. o \UXXXXXXXX, where XXXXXXXX is a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example, \U9 is the tab character. o \cX, where X is a letter of the alphabet, represents the control se- quence generated by pressing the control key and the specified let- ter. For example, \ci is the tab character INPUT/OUTPUT REDIRECTION Most programs use three input/output [1] streams, each represented by a number called a file descriptor (FD). These are: o Standard input, FD 0, for reading, defaults to reading from the key- board. o Standard output, FD 1, for writing, defaults to writing to the screen. o Standard error, FD 2, for writing errors and warnings, defaults to writing to the screen. Any file descriptor can be directed to a different output than its de- fault through a mechanism called a redirection. An example of a file redirection is echo hello > output.txt, which di- rects the output of the echo command to the file output.txt. o To read standard input from a file, write <SOURCE_FILE o To write standard output to a file, write >DESTINATION o To write standard error to a file, write 2>DESTINATION [2] o To append standard output to a file, write >>DESTINATION_FILE o To append standard error to a file, write 2>>DESTINATION_FILE o To not overwrite ("clobber") an existing file, write >?DESTINATION or 2>?DESTINATION (this is also known as the "noclobber" redirection) DESTINATION can be one of the following: o A filename. The output will be written to the specified file. o An ampersand (&) followed by the number of another file descriptor. The output will be written to that file descriptor instead. o An ampersand followed by a minus sign (&-). The file descriptor will be closed. As a convenience, the redirection &> can be used to direct both stdout and stderr to the same file. Example: To redirect both standard output and standard error to the file 'all_output.txt', you can write echo Hello &> all_output.txt, which is a convenience for echo Hello > all_output.txt 2>&1. Any file descriptor can be redirected in an arbitrary way by prefixing the redirection with the file descriptor. o To redirect input of FD N, write N<DESTINATION o To redirect output of FD N, write N>DESTINATION o To append the output of FD N to a file, write N>>DESTINATION_FILE Example: echo Hello 2>output.stderr writes the standard error (file de- scriptor 2) of the target program to output.stderr. [1] Also shortened as "I/O" or "IO". [2] Previous versions of fish also allowed spelling this as ^DESTINA- TION, but that made another character special so it was deprecated and will be removed in future. PIPING The user can string together multiple commands into a pipeline. This means that the standard output of one command will be read in as stan- dard input into the next command. This is done by separating the com- mands 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 com- mands 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 to use a different output file descriptor by prepending the desired FD number and then output redirect symbol to the pipe. For ex- ample: make fish 2>| less will attempt to build the fish program, and any errors will be shown using the less pager. As a convenience, the pipe &| may be used to redirect both stdout and stderr to the same process. (Note this is different from bash, which uses |&). BACKGROUND JOBS When you start a job in 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 an & (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user inter- face. Example: emacs & will start the emacs text editor in the background. JOB CONTROL Most programs allow you to suspend the program's execution and return control to fish by pressing Control+Z (also referred to as ^Z). Once back at the fish commandline, you can start other programs and do any- thing you want. If you then want you can go back to the suspended com- mand by using the fg (foreground) command. If you instead want to put a suspended job into the background, use the bg command. To get a listing of all currently started jobs, use the jobs command. These listed jobs can be removed with the disown command. FUNCTIONS Functions are programs written in the fish syntax. They group together one or more commands and their arguments using a single name. It can also be used to start a specific command with additional arguments. For example, the following is a function definition that calls the com- mand ls with the argument '-l' to print a detailed listing of the con- tents of the current directory: function ll ls -l $argv end The first line tells fish that a function by the name of ll is to be defined. To use it, simply write ll on the commandline. The second line tells fish that the command ls -l $argv should be called when ll is in- voked. '$argv' is a list variable, which always contains all arguments sent to the function. In the example above, these are simply passed on to the ls command. For more information on functions, see the documen- tation for the function builtin. DEFINING ALIASES One of the most common uses for functions is to slightly alter the be- havior of an already existing command. For example, one might want to redefine the ls command to display colors. The switch for turning on colors on GNU systems is '--color=auto'. An alias, or wrapper, around ls might look like this: function ls command ls --color=auto $argv end There are a few important things that need to be noted about aliases: o Always take care to add the $argv variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command. o If the alias has the same name as the aliased command, you need to prefix the call to the program with command to tell fish that the function should not call itself, but rather a command with the same name. If you forget to do so, the function would call itself until the end of time. Usually fish is smart enough to figure this out and will refrain from doing so (which is hopefully in your interest). o Autoloading isn't applicable to aliases. Since, by definition, the function is created at the time the alias command is executed. You cannot autoload aliases. To easily create a function of this form, you can use the alias com- mand. AUTOLOADING FUNCTIONS Functions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. This has some advantages: o An autoloaded function becomes available automatically to all running shells. o If the function definition is changed, all running shells will auto- matically reload the altered version. o Startup time and memory usage is improved, etc. When fish needs to load a function, it searches through any directories in the list variable $fish_function_path for a file with a name con- sisting of the name of the function plus the suffix '.fish' and loads the first it finds. By default $fish_function_path contains the following: o A directory for end-users to keep their own functions, usually ~/.config/fish/functions (controlled by the XDG_CONFIG_HOME environ- ment variable). o A directory for systems administrators to install functions for all users on the system, usually /etc/fish/functions (really $__fish_sysconfdir/functions). o Directories for third-party software vendors to ship their own func- tions for their software. Fish searches the directories in the XDG_DATA_DIRS environment variable for a fish/vendor_functions.d di- rectory; if this variable is not defined, the default is usually to search /usr/share/fish/vendor_functions.d and /usr/lo- cal/share/fish/vendor_functions.d. o The functions shipped with fish, usually installed in /usr/share/fish/functions (really $__fish_data_dir/functions). These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above. This wide search may be confusing. If you are unsure, your functions probably belong in ~/.config/fish/functions. It is very important that function definition files only contain the definition for the specified function and nothing else. Otherwise, it is possible that autoloading a function files requires that the func- tion already be loaded, which creates a circular dependency. Autoloading also won't work for event handlers, since fish cannot know that a function is supposed to be executed when an event occurs when it hasn't yet loaded the function. See the event handlers section for more information. Autoloading is not applicable to functions created by the alias com- mand. For functions simple enough that you prefer to use the alias com- mand to define them you'll need to put those commands in your ~/.con- fig/fish/config.fish script or some other script run when the shell starts. If you are developing another program, you may wish to install func- tions which are available for all users of the fish shell on a system. They can be installed to the "vendor" functions directory. As this path may vary from system to system, the pkgconfig framework should be used to discover this path with the output of pkg-config --variable func- tionsdir fish. Your installation system should support a custom path to override the pkgconfig path, as other distributors may need to alter it easily. CONDITIONAL EXECUTION OF CODE AND FLOW CONTROL There are four fish builtins that let you execute commands only if a specific criterion is met. These builtins are if, switch, and and or. The switch command is used to execute one of possibly many blocks of commands depending on the value of a string. See the documentation for switch for more information. The other conditionals use the exit status of a command to decide if a command or a block of commands should be executed. See their documenta- tion for more information. PARAMETER EXPANSION (GLOBBING) When an argument for a program is given on the commandline, it under- goes the process of parameter expansion before it is sent on to the command. Parameter expansion is a powerful mechanism that allows you to expand the parameter in various ways, including performing wildcard matching on files, inserting the value of a shell variable into the pa- rameter or even using the output of another command as a parameter list. WILDCARDS If a star (*) or a question mark (?) is present in the parameter, fish attempts to match the given parameter to any files in such a way that: o * can match any string of characters not containing '/'. This in- cludes matching an empty string. o ** matches any string of characters. This includes matching an empty string. The matched string may include the / character; that is, it recurses into subdirectories. Note that augmenting this wildcard with other strings will not match files in the current working directory ($PWD) if you separate the strings with a slash ("/"). This is unlike other shells such as zsh. For example, **\/*.fish in zsh will match .fish files in the PWD but in fish will only match such files in a subdirectory. In fish you should type **.fish to match files in the PWD as well as subdirectories. o ? can match any single character except '/'. This is deprecated and can be disabled via the qmark-noglob feature flag, so ? will just be an ordinary character. Other shells, such as zsh, provide a rich glob syntax for restricting the files matched by globs. For example, **(.), to only match regular files. Fish prefers to defer such features to programs, such as find, rather than reinventing the wheel. Thus, if you want to limit the wild- card expansion to just regular files the fish approach is to define and use a function. For example, function ff --description 'Like ** but only returns plain files.' # This also ignores .git directories. find . \( -name .git -type d -prune \) -o -type f | \ sed -n -e '/^\.\/\.git$/n' -e 's/^\.\///p' end You would then use it in place of ** like this, my_prog (ff), to pass only regular files in or below $PWD to my_prog. Wildcard matches are sorted case insensitively. When sorting matches containing numbers, consecutive digits are considered to be one ele- ment, so that the strings '1' '5' and '12' would be sorted in the order given. File names beginning with a dot are not considered when wildcarding un- less a dot is specifically given as the first character of the file name. Examples: o a* matches any files beginning with an 'a' in the current directory. o ??? matches any file in the current directory whose name is exactly three characters long. o ** matches any files and directories in the current directory and all of its subdirectories. Note that for most commands, if any wildcard fails to expand, the com- mand is not executed, $status is set to nonzero, and a warning is printed. This behavior is consistent with setting shopt -s failglob in bash. There are exactly 4 exceptions, namely set, overriding variables in overrides, count and for. Their globs are permitted to expand to zero arguments, as with shopt -s nullglob in bash. Examples: ls *.foo # Lists the .foo files, or warns if there aren't any. set foos *.foo if count $foos >/dev/null ls $foos end # Lists the .foo files, if any. COMMAND SUBSTITUTION The output of a series of commands can be used as the parameters to an- other command. If a parameter contains a set of parenthesis, the text enclosed by the parenthesis will be interpreted as a list of commands. On expansion, this list is executed, and substituted by the output. If the output is more than one line long, each line will be expanded to a new parameter. Setting IFS to the empty string will disable line split- ting. If the output is piped to string split or string split0 as the last step, those splits are used as they appear and no additional splitting on newlines takes place. The exit status of the last run command substitution is available in the status variable if the substitution occurs in the context of a set command. Only part of the output can be used, see index range expansion for de- tails. Fish has a default limit of 100 MiB on the amount of data a command substitution can output. If the limit is exceeded the entire command, not just the substitution, is failed and $status is set to 122. You can modify the limit by setting the fish_read_limit variable at any time including in the environment before fish starts running. If you set it to zero then no limit is imposed. This is a safety mechanism to keep the shell from consuming too much memory if a command outputs an unrea- sonable amount of data, typically your operating system also has a limit, and it's often much lower. Note that this limit also affects how much data the read command will process. Examples: echo (basename image.jpg .jpg).png # Outputs 'image.png'. for i in *.jpg; convert $i (basename $i .jpg).png; end # Convert all JPEG files in the current directory to the # PNG format using the 'convert' program. begin; set -l IFS; set data (cat data.txt); end # Set the ``data`` variable to the contents of 'data.txt' # without splitting it into a list. set data (cat data | string split0) # Set ``$data`` to the contents of data, splitting on NUL-bytes. BRACE EXPANSION A comma separated list of characters enclosed in curly braces will be expanded so each element of the list becomes a new parameter. This is useful to save on typing, and to separate a variable name from sur- rounding text. Examples: > echo input.{c,h,txt} input.c input.h input.txt > mv *.{c,h} src/ # Moves all files with the suffix '.c' or '.h' to the subdirectory src. > cp file{,.bak} # Make a copy of `file` at `file.bak`. > set -l dogs hot cool cute > echo {$dogs}dog hotdog cooldog cutedog If two braces do not contain a "," or a variable expansion, they will not be expanded in this manner: > echo foo-{} foo-{} > git reset --hard HEAD@{2} # passes "HEAD@{2}" to git > echo {{a,b}} {a} {b} # because the inner brace pair is expanded, but the outer isn't. If after expansion there is nothing between the braces, the argument will be removed (see the cartesian product section): > echo foo-{$undefinedvar} # Output is an empty line, just like a bare `echo`. If there is nothing between a brace and a comma or two commas, it's in- terpreted as an empty element: > echo {,,/usr}/bin /bin /bin /usr/bin To use a "," as an element, quote or escape it. VARIABLE EXPANSION A dollar sign followed by a string of characters is expanded into the value of the shell variable with the same name. For more on shell vari- ables, read the Shell variables section. Examples: echo $HOME # Prints the home directory of the current user. Undefined and empty variables expand to nothing: echo $nonexistentvariable # Prints no output. To separate a variable name from text encase the variable within dou- ble-quotes or braces: echo The plural of $WORD is "$WORD"s # Prints "The plural of cat is cats" when $WORD is set to cat. echo The plural of $WORD is {$WORD}s # ditto Note that without the quotes or braces, fish will try to expand a vari- able called $WORDs, which may not exist. The latter syntax {$WORD} works by exploiting brace expansion. In these cases, the expansion eliminates the string, as a result of the implicit cartesian product. If, in the example above, $WORD is undefined or an empty list, the "s" is not printed. However, it is printed if $WORD is the empty string (like after set WORD ""). Unlike all the other expansions, variable expansion also happens in double quoted strings. Inside double quotes ("these"), variables will always expand to exactly one argument. If they are empty or undefined, it will result in an empty string. If they have one element, they'll expand to that element. If they have more than that, the elements will be joined with spaces [3]. Outside of double quotes, variables will expand to as many arguments as they have elements. That means an empty list will expand to nothing, a variable with one element will expand to that element, and a variable with multiple elements will expand to each of those elements sepa- rately. When two unquoted expansions directly follow each other, you need to watch out for expansions that expand to nothing. This includes unde- fined variables and empty lists, but also command substitutions with no output. See the cartesian product section for more information. The $ symbol can also be used multiple times, as a kind of "derefer- ence" operator (the * in C or C++), like in the following code: set foo a b c set a 10; set b 20; set c 30 for i in (seq (count $$foo)) echo $$foo[$i] end # Output is: # 10 # 20 # 30 When using this feature together with list brackets, the brackets will always match the innermost $ dereference. Thus, $$foo[5] will always mean the fifth element of the foo variable should be dereferenced, not the fifth element of the doubly dereferenced variable foo. The latter can instead be expressed as $$foo[1][5]. [3] Unlike bash or zsh, which will join with the first character of $IFS (which usually is space). CARTESIAN PRODUCTS Lists adjacent to other lists or strings are expanded as cartesian products: Examples: >_ echo {good,bad}" apples" good apples bad apples >_ set -l a x y z >_ set -l b 1 2 3 >_ echo $a$b x1 y1 z1 x2 y2 z2 x3 y3 z3 >_ echo $a"-"$b x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3 >_ echo {x,y,z}$b x1 y1 z1 x2 y2 z2 x3 y3 z3 >_ echo {$b}word 1word 2word 3word >_ echo {$c}word # Output is an empty line Be careful when you try to use braces to separate variable names from text. The problem shown above can be avoided by wrapping the variable in double quotes instead of braces (echo "$c"word). This also happens after command substitution. Therefore strings might be eliminated. This can be avoided by making the inner command return a trailing newline. E.g. >_ echo (printf '%s' '')banana # the printf prints literally nothing >_ echo (printf '%s\n' '')banana # the printf prints just a newline, so the command substitution expands to an empty string banana # After command substitution, the previous line looks like: >_ echo ""banana Examples: >_ set b 1 2 3 >_ echo (echo x)$b x1 x2 x3 INDEX RANGE EXPANSION Sometimes it's necessary to access only some of the elements of a list, or some of the lines a command substitution outputs. Both allow this by providing a set of indices in square brackets. Sequences of elements can be written with the range operator '..'. A range 'a..b' ('a' and 'b' being integers) is expanded into a sequence of indices 'a a+1 a+2 ... b' or 'a a-1 a-2 ... b' depending on which of 'a' or 'b' is higher. Negative range limits are calculated from the end of the list. If an index is too large or small it's silently clamped to one or the size of the list as appropriate. If the end is smaller than the start, or the start is larger than the end, range expansion will go in reverse. This is unless exactly one of the given indices is negative, so the direction doesn't change if the list has fewer elements than expected. Some examples: echo (seq 10)[1 2 3] # Prints: 1 2 3 # Limit the command substitution output echo (seq 10)[2..5] # Uses elements from 2 to 5 # Output is: 2 3 4 5 # Use overlapping ranges: echo (seq 10)[2..5 1..3] # Takes elements from 2 to 5 and then elements from 1 to 3 # Output is: 2 3 4 5 1 2 3 # Reverse output echo (seq 10)[-1..1] # Uses elements from the last output line to # the first one in reverse direction # Output is: 10 9 8 7 6 5 4 3 2 1 # The command substitution has only one line, # so these will result in empty output: echo (echo one)[2..-1] echo (echo one)[-3..1] The same works when setting or expanding variables: # Reverse path variable set PATH $PATH[-1..1] # or set PATH[-1..1] $PATH # Use only n last items of the PATH set n -3 echo $PATH[$n..-1] Variables can be used as indices for expansion of variables, like so: set index 2 set letters a b c d echo $letters[$index] # returns 'b' However using variables as indices for command substitution is cur- rently not supported, so: echo (seq 5)[$index] # This won't work set sequence (seq 5) # It needs to be written on two lines like this. echo $sequence[$index] # returns '2' When using indirect variable expansion with multiple $ ($$name), you have to give all indices up to the variable you want to slice: > set -l list 1 2 3 4 5 > set -l name list > echo $$name[1] 1 2 3 4 5 > echo $$name[1..-1][1..3] # or $$name[1][1..3], since $name only has one element. 1 2 3 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. COMBINING DIFFERENT EXPANSIONS All of the above expansions can be combined. If several expansions re- sult in more than one parameter, all possible combinations are created. When combining multiple parameter expansions, expansions are performed in the following order: o Command substitutions o Variable expansions o Bracket expansion o Wildcard expansion Expansions are performed from right to left, nested bracket expansions are performed from the inside and out. Example: If the current directory contains the files 'foo' and 'bar', the com- mand echo a(ls){1,2,3} will output abar1 abar2 abar3 afoo1 afoo2 afoo3. SHELL VARIABLE AND FUNCTION NAMES The names given to shell objects like variables and function names are known as "identifiers". Each type of identifier has rules that define what sequences of characters are valid to use. A variable name cannot be empty. It can contain only letters, digits, and underscores. It may begin and end with any of those characters. A function name cannot be empty. It may not begin with a hyphen ("-") and may not contain a slash ("/"). All other characters, including a space, are valid. A bind mode name (e.g., bind -m abc ...) is restricted to the rules for valid variable names. SHELL VARIABLES Shell variables are named pieces of data, which can be created, deleted and their values changed and used by the user. Variables may option- ally be "exported", so that a copy of the variable is available to any subprocesses the shell creates. An exported variable is referred to as an "environment variable". To set a variable value, use the set command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters. Example: To set the variable smurf_color to the value blue, use the command set smurf_color 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 the variable smurf_color, write $ (dollar symbol) followed by the name of the variable, like echo Smurfs are usually $smurf_color, which would print the result 'Smurfs are usually blue'. VARIABLE SCOPE There are three kinds of variables in fish: universal, global and local variables. o Universal variables are shared between all fish sessions a user is running on one computer. o Global variables are specific to the current fish session, but are not associated with any specific block scope, and will never be erased unless the user explicitly requests it using set -e. o Local variables are specific to the current fish session, and associ- ated with a specific block of commands, and is automatically erased when a specific block goes out of scope. A block of commands is a se- ries of commands that begins with one of the commands for, while , if, function, begin or switch, and ends with the command end. Variables can be explicitly set to be universal with the -U or --uni- versal 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: o If a variable is explicitly set to a scope (universal, global or lo- cal), that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed. o If a variable is not explicitly set to a scope, but has been previ- ously defined, the variable scope is not changed. o If a variable is not explicitly set to a scope and has not been de- fined, the variable will be local to the currently executing func- tion. Note that this is different from using the -l or --local flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the vari- able will be global. There may be many variables with the same name, but different scopes. When using a variable, the variable scope will be searched from the in- side out, i.e. a local variable will be used rather than a global vari- able 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 echo $pirate # This will not output anything, since the pirate was local OVERRIDING VARIABLES FOR A SINGLE COMMAND If you want to override a variable for a single command, you can use "var=val" statements before the command: # Call git status on another directory (can also be done via `git -C somerepo status`) GIT_DIR=somerepo git status Note that, unlike other shells, fish will first set the variable and then perform other expansions on the line, so: set foo banana foo=gagaga echo $foo # prints gagaga, while in other shells it might print "banana" Multiple elements can be given in a brace expansion: # Call bash with a reasonable default path. PATH={/usr,}/{s,}bin bash This syntax is supported since fish 3.1. MORE ON UNIVERSAL VARIABLES Universal variables are variables that are shared between all the users' fish sessions on the computer. Fish stores many of its configu- ration 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 pre- served 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 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. Universal variables are stored in the file .config/fish/fish_variables. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively in- stead. Do not append to universal variables in config.fish, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line. VARIABLE SCOPE FOR FUNCTIONS When calling a function, all current local variables temporarily disap- pear. This shadowing of the local scope is needed since the variable namespace would become cluttered, making it very easy to accidentally overwrite variables from another function. For example: function shiver set phrase 'Shiver me timbers' end function avast set --local phrase 'Avast, mateys' # Calling the shiver function here can not # change any variables in the local scope shiver echo $phrase end avast # Outputs "Avast, mateys" EXPORTING VARIABLES Variables in fish can be "exported", so they will be inherited by any commands started by fish. In particular, this is necessary for vari- ables used to configure external commands like $LESS or $GOPATH, but also for variables that contain general system settings like $PATH or $LANGUAGE. If an external command needs to know a variable, it needs to be exported. Variables can be explicitly set to be exported with the -x or --export switch, or not exported with the -u or --unexport switch. The export- ing rules when setting a variable are identical to the scoping rules for variables: o If a variable is explicitly set to either be exported or not ex- ported, that setting will be honored. o 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. o Otherwise, by default, the variable will not be exported. o If a variable has local scope and is exported, any function called receives a _copy_ of it, so any changes it makes to the variable dis- appear once the function returns. o Global variables are accessible to functions whether they are ex- ported or not. As a naming convention, exported variables are in uppercase and unex- ported variables are in lowercase. LISTS fish can store a list (or an "array" if you wish) of multiple strings inside of a variable. To access one element of a list, use the index of the element inside of square brackets, like this: echo $PATH[3] Note that list indices start at 1 in fish, not 0, as is more common in other languages. This is because many common Unix tools like seq are more suited to such use. An invalid index is silently ignored resulting in no value being substituted (not an empty string). If you do not use any brackets, all the elements of the list will be written as separate items. This means you can easily iterate over a list 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 a list: # Set smurf to be a list 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 If you specify a negative index when expanding or assigning to a list variable, the index will be calculated from the end of the list. For example, the index -1 means the last index of a list. A range of indices can be specified, see index range expansion for de- tails. All lists are one-dimensional and cannot contain other lists, although it is possible to fake nested lists using the dereferencing rules of variable expansion. When a list is exported as an environment variable, it is either space or colon delimited, depending on whether it is a path variable: set -x smurf blue small set -x smurf_PATH forest mushroom env | grep smurf # smurf=blue small # smurf_PATH=forest:mushroom fish automatically creates lists from all environment variables whose name ends in PATH, by splitting them on colons. Other variables are not automatically split. PATH VARIABLES Path variables are a special kind of variable used to support colon-de- limited path lists including PATH, CDPATH, MANPATH, PYTHONPATH, etc. All variables that end in PATH (case-sensitive) become PATH variables. PATH variables act as normal lists, except they are are implicitly joined and split on colons. set MYPATH 1 2 3 echo "$MYPATH" # 1:2:3 set MYPATH "$MYPATH:4:5" echo $MYPATH # 1 2 3 4 5 echo "$MYPATH" # 1:2:3:4:5 Variables can be marked or unmarked as PATH variables via the --path and --unpath options to set. SPECIAL VARIABLES The user can change the settings of fish by changing the values of cer- tain variables. o PATH, a list of directories in which to search for commands o CDPATH, a list of directories in which to search for the new direc- tory for the cd builtin. o LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NU- MERIC and LC_TIME set the language option for the shell and subpro- grams. See the section Locale variables for more information. o A large number of variable starting with the prefixes fish_color and fish_pager_color. See Variables for changing highlighting colors for more information. o fish_emoji_width controls the computed width of certain characters, in particular emoji, whose rendered width changed in Unicode 9 and hence varies across terminal emulators. This should be set to 2 if your terminal emulator supports Unicode >= 9 and renders them dou- ble-width, and 1 otherwise. Set this only if you see graphical glitching when printing emoji, typically it will be automatically de- tected. o fish_ambiguous_width controls the computed width of ambiguous-width characters. This should be set to 1 if your terminal emulator renders these characters as single-width (typical), or 2 if double-width. o fish_escape_delay_ms overrides the default timeout of 30ms after see- ing an escape character before giving up on matching a key binding. This is explained in the documentation for the bind builtin command. This delay facilitates using escape as a meta key. o fish_greeting, the greeting message printed on startup. o fish_history, the current history session name. If set, all subse- quent commands within an interactive fish session will be logged to a separate file identified by the value of the variable. If unset, or set to default, the default session name "fish" is used. If set to an empty string, history is not saved to disk (but is still available within the interactive session). o fish_trace, if set and not empty, will cause fish to print commands before they execute, similar to set -x in bash. The trace is printed to the path given by the --debug-output option to fish (stderr by de- fault). o fish_user_paths, a list of directories that are prepended to PATH. This can be a universal variable. o umask, the current file creation mask. The preferred way to change the umask variable is through the umask function. An attempt to set umask to an invalid value will always fail. o BROWSER, the user's 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. fish also sends additional information to the user through the values of certain environment variables. The user cannot change the values of most of these variables. o _, the name of the currently running command (though this is depre- cated, and the use of status current-command is preferred). o argv, a list of arguments to the shell or function. argv is only de- fined when inside a function call, or if fish was invoked with a list of arguments, like fish myscript.fish foo bar. This variable can be changed by the user. o history, a list containing the last commands that were entered. o HOME, the user's home directory. This variable can be changed by the user. o hostname, the machine's hostname. o IFS, the internal field separator that is used for word splitting with the read builtin. Setting this to the empty string will also disable line splitting in command substitution. This variable can be changed by the user. o PWD, the current working directory. o status, the exit status of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number. o pipestatus, a list of exit statuses of all processes that made up the last executed pipe. o USER, the current username. This variable can be changed by the user. o CMD_DURATION, the runtime of the last command in milliseconds. o version, the version of the currently running fish (also available as FISH_VERSION for backward compatibility). o SHLVL, the level of nesting of shells o COLUMNS and LINES, the current size of the terminal in height and width. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are up- dated when the window size changes. The names of these variables are mostly derived from the csh family of shells and differ from the ones used by Bourne style shells such as bash. Variables whose name are in uppercase are generally exported to the commands started by fish, while those in lowercase are not exported (CMD_DURATION is an exception, for historical reasons). 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 never be used by the user. Chang- ing their value may break fish. THE STATUS VARIABLE Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command ex- ecuted without problem, but a non-zero exit status means there was some form of problem. Fish stores the exit status of the last process in the last job to exit in the status variable. If fish encounters a problem while executing a command, the status variable may also be set to a specific value: o 0 is generally the exit status of fish commands if they successfully performed the requested operation. o 1 is generally the exit status of fish commands if they failed to perform the requested operation. o 121 is generally the exit status of fish commands if they were sup- plied with invalid arguments. o 123 means that the command was not executed because the command name contained invalid characters. o 124 means that the command was not executed because none of the wild- cards in the command produced any matches. o 125 means that while an executable with the specified name was lo- cated, the operating system could not actually execute the command. o 126 means that while a file with the specified name was located, it was not executable. o 127 means that no function, builtin or command with the given name could be located. If a process exits through a signal, the exit status will be 128 plus the number of the signal. VARIABLES FOR CHANGING HIGHLIGHTING COLORS The colors used by fish for syntax highlighting can be configured by changing the values of a various variables. The value of these vari- ables can be one of the colors accepted by the set_color command. The --bold or -b switches accepted by set_color are also accepted. The following variables are available to change the highlighting colors in fish: o fish_color_normal, the default color o fish_color_command, the color for commands o fish_color_quote, the color for quoted blocks of text o fish_color_redirection, the color for IO redirections o fish_color_end, the color for process separators like ';' and '&' o fish_color_error, the color used to highlight potential errors o fish_color_param, the color for regular command parameters o fish_color_comment, the color used for code comments o fish_color_match, the color used to highlight matching parenthesis o fish_color_selection, the color used when selecting text (in vi vis- ual mode) o fish_color_search_match, used to highlight history search matches and the selected pager item (must be a background) o fish_color_operator, the color for parameter expansion operators like '*' and '~' o fish_color_escape, the color used to highlight character escapes like '\n' and '\x70' o fish_color_cwd, the color used for the current working directory in the default prompt o fish_color_autosuggestion, the color used for autosuggestions o fish_color_user, the color used to print the current username in some of fish default prompts o fish_color_host, the color used to print the current host system in some of fish default prompts o fish_color_host_remote, the color used to print the current host sys- tem in some of fish default prompts, if fish is running remotely (via ssh or similar) o fish_color_cancel, the color for the '^C' indicator on a canceled command Additionally, the following variables are available to change the high- lighting in the completion pager: o fish_pager_color_progress, the color of the progress bar at the bot- tom left corner o fish_pager_color_background, the background color of a line o fish_pager_color_prefix, the color of the prefix string, i.e. the string that is to be completed o fish_pager_color_completion, the color of the completion itself o fish_pager_color_description, the color of the completion description o fish_pager_color_secondary_background, fish_pager_color_background of every second unselected completion. Defaults to fish_pager_color_background o fish_pager_color_secondary_ prefix, fish_pager_color_prefix of every second unselected completion. Defaults to fish_pager_color_prefix o fish_pager_color_secondary_completion, fish_pager_color_completion of every second unselected completion. Defaults to fish_pager_color_com- pletion o fish_pager_color_secondary_description, fish_pager_color_description of every second unselected completion. Defaults to fish_pager_color_description o fish_pager_color_selected_background, fish_pager_color_background of the selected completion. Defaults to fish_color_search_match o fish_pager_color_selected_prefix, fish_pager_color_prefix of the se- lected completion. Defaults to fish_pager_color_prefix o fish_pager_color_selected_completion, fish_pager_color_completion of the selected completion. Defaults to fish_pager_color_completion o fish_pager_color_selected_description, fish_pager_color_description of the selected completion. Defaults to fish_pager_color_description Example: To make errors highlighted and red, use: set fish_color_error red --bold LOCALE VARIABLES The most common way to set the locale to use a command like 'set -x LANG en_GB.utf8', which sets the current locale to be the English lan- guage, as used in Great Britain, using the UTF-8 character set. For a list of available locales, use 'locale -a'. LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NU- MERIC and LC_TIME set the language option for the shell and subpro- grams. 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 lo- cale variables will be ignored. The other LC_ variables set the speci- fied aspect of the locale information. LANG is a fallback value, it will be used if none of the LC_ variables are specified. BUILTIN COMMANDS 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. To avoid code duplication, and to avoid the confusion of subtly differing versions of the same command, fish generally only implements builtins for actions which cannot be performed by a regular command. For a list of all builtins, functions and commands shipped with fish, see the list of commands. The documentation is also available by using the --help switch of the command. Fish prides itself on being really nice to use interactively. That's down to a few features we'll explain in the next few sections. 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. fish also has man pages for its commands. For example, man set will show the documentation for set as a man page. 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. AUTOSUGGESTIONS fish suggests commands as you type, based on command history, comple- tions, and valid file paths. As you type commands, you will see a sug- gestion offered after the cursor, in a muted gray color (which can be changed with the fish_color_autosuggestion variable). To accept the autosuggestion (replacing the command line contents), press right arrow or Control+F. To accept the first suggested word, press Alt+^a,Right or Alt+F. If the autosuggestion is not what you want, just ignore it: it won't execute unless you accept it. Autosuggestions are a powerful way to quickly summon frequently entered commands, by typing the first few characters. They are also an effi- cient technique for navigating through directory hierarchies. 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 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 prefix that all completions have in common. If the 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, the tab key or the space bar. If the list is visible, pressing control-S (or the pager-toggle-search binding) will allow filtering the list. Shift-tab (or the com- plete-and-search binding) will trigger completion with the search field immediately visible. These are the general purpose tab completions that fish provides: o Completion of commands (builtins, functions and regular programs). o Completion of shell variable names. o Completion of usernames for tilde expansion. o Completion of filenames, even on strings with wildcards such as '*' and '**'. 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: o The programs man and whatis show all installed manual pages as com- pletions. o The make program uses all targets in the Makefile in the current di- rectory as completions. o The mount command uses all mount points specified in fstab as comple- tions. o The ssh command uses all hosts that are stored in the known_hosts file as completions. (See the ssh documentation for more information) o The su command uses all users on the system as completions. o The apt-get, rpm and yum commands use all installed packages as com- pletions. WRITING YOUR OWN COMPLETIONS To specify a completion, use the complete command. complete takes as a parameter the name of the command to specify a completion for. For ex- ample, 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 tok- enized 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'), respec- tively. 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 descrip- tion of the various switches accepted by the complete command, see the documentation for the complete builtin, or write complete --help inside the fish shell. As a more comprehensive example, here's a commented excerpt of the com- pletions for systemd's timedatectl: # All subcommands that timedatectl knows - this is useful for later. set -l commands status set-time set-timezone list-timezones set-local-rtc set-ntp # Disable file completions for the entire command # because it does not take files anywhere # Note that this can be undone by using "-F". # # File completions also need to be disabled # if you want to have more control over what files are offered (e.g. just directories, or just files ending in ".mp3"). complete -c timedatectl -f # This line offers the subcommands # -"status", # -"set-timezone", # -"set-time" # -"list-timezones" # if no subcommand has been given so far. # # The `-n`/`--condition` option takes script as a string, which it executes. # If it returns true, the completion is offered. # Here the condition is the `__fish_seen_subcommands_from` helper function. # If returns true if any of the given commands is used on the commandline, # as determined by a simple heuristic. # For more complex uses, you can write your own function. # See e.g. the git completions for an example. # complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" -a "status set-time set-timezone list-timezones" # If the "set-timezone" subcommand is used, # offer the output of `timedatectl list-timezones` as completions. # Each line of output is used as a separate candidate, # and anything after a tab is taken as the description. # It's often useful to transform command output with `string` into that form. complete -c timedatectl -n "__fish_seen_subcommand_from set-timezone" -a "(timedatectl list-timezones)" # Completion candidates can also be described via `-d`, # which is useful if the description is constant. # Try to keep these short, because that means the user gets to see more at once. complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" -a "set-local-rtc" -d "Maintain RTC in local time" # We can also limit options to certain subcommands by using conditions. complete -c timedatectl -n "__fish_seen_subcommand_from set-local-rtc" -l adjust-system-clock -d 'Synchronize system clock from the RTC' # These are simple options that can be used everywhere. complete -c timedatectl -s h -l help -d 'Print a short help text and exit' complete -c timedatectl -l version -d 'Print a short version string and exit' complete -c timedatectl -l no-pager -d 'Do not pipe output into a pager' For examples of how to write your own complex completions, study the completions in /usr/share/fish/completions. (The exact path depends on your chosen installation prefix and may be slightly different) USEFUL FUNCTIONS FOR WRITING COMPLETIONS fish ships with several functions that are very useful when writing command specific completions. Most of these functions name begins with the string '__fish_'. Such functions are internal to fish and their name and interface may change in future fish versions. Still, some of them may be very useful when writing completions. A few of these func- tions are described here. Be aware that they may be removed or changed in future versions of fish. Functions beginning with the string __fish_print_ print a newline sepa- rated list of strings. For example, __fish_print_filesystems prints a list of all known file systems. Functions beginning with __fish_com- plete_ print out a newline separated list of completions with descrip- tions. The description is separated from the completion by a tab char- acter. o __fish_complete_directories STRING DESCRIPTION performs path comple- tion on STRING, allowing only directories, and giving them the de- scription DESCRIPTION. o __fish_complete_path STRING DESCRIPTION performs path completion on STRING, giving them the description DESCRIPTION. o __fish_complete_groups prints a list of all user groups with the groups members as description. o __fish_complete_pids prints a list of all processes IDs with the com- mand name as description. o __fish_complete_suffix SUFFIX performs file completion allowing only files ending in SUFFIX, with an optional description. o __fish_complete_users prints a list of all users with their full name as description. o __fish_print_filesystems prints a list of all known file systems. Currently, this is a static list, and not dependent on what file sys- tems the host operating system actually understands. o __fish_print_hostnames prints a list of all known hostnames. This functions searches the fstab for nfs servers, ssh for known hosts and checks the /etc/hosts file. o __fish_print_interfaces prints a list of all known network inter- faces. o __fish_print_packages prints a list of all installed packages. This function currently handles Debian, rpm and Gentoo packages. WHERE TO PUT COMPLETIONS Completions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. Fish automatically searches through any directories in the list variable $fish_com- plete_path, and any completions defined are automatically loaded when needed. A completion file must have a filename consisting of the name of the command to complete and the suffix '.fish'. By default, Fish searches the following for completions, using the first available file that it finds: o A directory for end-users to keep their own completions, usually ~/.config/fish/completions (controlled by the XDG_CONFIG_HOME envi- ronment variable); o A directory for systems administrators to install completions for all users on the system, usually /etc/fish/completions; o Directories for third-party software vendors to ship their own com- pletions for their software. Fish searches the directories in the XDG_DATA_DIRS environment variable for a fish/vendor_completions.d directory; if this variable is not defined, the default is usually to search /usr/share/fish/vendor_completions.d and /usr/lo- cal/share/fish/vendor_completions.d; o The completions shipped with fish, usually installed in /usr/share/fish/completions; and o Completions automatically generated from the operating system's manu- als, usually stored in ~/.local/share/fish/generated_completions. These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above. This wide search may be confusing. If you are unsure, your completions probably belong in ~/.config/fish/completions. If you have written new completions for a common Unix command, please consider sharing your work by submitting it via the instructions in Further help and development. If you are developing another program and would like to ship comple- tions with your program, install them to the "vendor" completions di- rectory. As this path may vary from system to system, the pkgconfig framework should be used to discover this path with the output of pkg-config --variable completionsdir fish. Your installation system should support a custom path to override the pkgconfig path, as other distributors may need to alter it easily. The fish editor features copy and paste, a searchable history and many editor functions that can be bound to special keyboard shortcuts. Similar to bash, fish has Emacs and Vi editing modes. The default edit- ing mode is Emacs. You can switch to Vi mode with fish_vi_key_bindings and switch back with fish_default_key_bindings. You can also make your own key bindings by creating a function and setting $fish_key_bindings to its name. For example: function hybrid_bindings --description "Vi-style bindings that inherit emacs-style bindings in all modes" for mode in default insert visual fish_default_key_bindings -M $mode end fish_vi_key_bindings --no-erase end set -g fish_key_bindings hybrid_bindings SHARED BINDINGS Some bindings are shared between emacs- and vi-mode because they aren't text editing bindings or because what Vi/Vim does for a particular key doesn't make sense for a shell. o Tab completes the current token. Shift, Tab completes the current to- ken and starts the pager's search mode. o Alt+^a,Left and Alt+^a,Right move the cursor one word left or right (to the next space or punctuation mark), or moves forward/backward in the directory history if the command line is empty. If the cursor is al- ready at the end of the line, and an autosuggestion is available, Alt+^a,Right (or Alt+F) accepts the first word in the suggestion. o Shift,^a,Left and Shift,^a,Right move the cursor one word left or right, without stopping on punctuation. o ^a (Up) and ^a (Down) (or Control+P and Control+N for emacs aficiona- dos) search the command history for the previous/next command con- taining the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the history section for more infor- mation on history searching. o Alt+^a,Up and Alt+^a,Down search the command history for the previ- ous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the history section for more information on history searching. o Control+C cancels the entire line. o Control+D delete one character to the right of the cursor. If the command line is empty, Control+D will exit fish. o Control+U moves contents from the beginning of line to the cursor to the killring. o Control+L clears and repaints the screen. o Control+W moves the previous path component (everything up to the previous "/", ":" or "@") to the killring. o Control+X copies the current buffer to the system's clipboard, Con- trol+V inserts the clipboard contents. o Alt+d moves the next word to the killring. o Alt+h (or F1) shows the manual page for the current command, if one exists. o Alt+l lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that di- rectory will be listed. o Alt+p adds the string '| less;' to the end of the job under the cur- sor. The result is that the output of the command will be paged. o Alt+w prints a short description of the command under the cursor. o Alt+e edit the current command line in an external editor. The editor is chosen from the first available of the $VISUAL or $EDITOR vari- ables. o Alt+v Same as Alt+e. o Alt+s Prepends sudo to the current commandline. EMACS MODE COMMANDS o Home or Control+A moves the cursor to the beginning of the line. o End or Control+E moves to the end of line. If the cursor is already at the end of the line, and an autosuggestion is available, End or Control+E accepts the autosuggestion. o ^a (Left) (or Control+B) and ^a (Right) (or Control+F) move the cursor left or right by one character. If the cursor is already at the end of the line, and an autosuggestion is available, the ^a (Right) key and the Control+F combination accept the suggestion. o Delete and Backspace removes one character forwards or backwards re- spectively. o Control+K moves contents from the cursor to the end of line to the killring. o Alt+c capitalizes the current word. o Alt+u makes the current word uppercase. o Control+t transposes the last two characters o Alt+t transposes the last two words You can change these key bindings using the bind builtin. VI MODE COMMANDS Vi mode allows for the use of Vi-like commands at the prompt. Ini- tially, insert mode is active. Escape enters command mode. The commands available in command, insert and visual mode are described below. Vi mode shares some bindings with Emacs mode. It is also possible to add all emacs-mode bindings to vi-mode by using something like: function fish_user_key_bindings # Execute this once per mode that emacs bindings should be used in fish_default_key_bindings -M insert # Without an argument, fish_vi_key_bindings will default to # resetting all bindings. # The argument specifies the initial mode (insert, "default" or visual). fish_vi_key_bindings insert end When in vi-mode, the fish_mode_prompt function will display a mode in- dicator to the left of the prompt. To disable this feature, override it with an empty function. To display the mode elsewhere (like in your right prompt), use the output of the fish_default_mode_prompt function. When a binding switches the mode, it will repaint the mode-prompt if it exists, and the rest of the prompt only if it doesn't. So if you want a mode-indicator in your fish_prompt, you need to erase fish_mode_prompt e.g. by adding an empty file at ~/.config/fish/func- tions/fish_mode_prompt.fish. (Bindings that change the mode are sup- posed to call the repaint-mode bind function, see bind) The fish_vi_cursor function will be used to change the cursor's shape depending on the mode in supported terminals. The following snippet can be used to manually configure cursors after enabling vi-mode: # Emulates vim's cursor shape behavior # Set the normal and visual mode cursors to a block set fish_cursor_default block # Set the insert mode cursor to a line set fish_cursor_insert line # Set the replace mode cursor to an underscore set fish_cursor_replace_one underscore # The following variable can be used to configure cursor shape in # visual mode, but due to fish_cursor_default, is redundant here set fish_cursor_visual block Additionally, blink can be added after each of the cursor shape parame- ters to set a blinking cursor in the specified shape. COMMAND MODE Command mode is also known as normal mode. o h moves the cursor left. o l moves the cursor right. o i enters insert mode at the current cursor position. o v enters visual mode at the current cursor position. o a enters insert mode after the current cursor position. o Shift,A enters insert mode at the end of the line. o 0 (zero) moves the cursor to beginning of line (remaining in command mode). o dd deletes the current line and moves it to the killring. o Shift,D deletes text after the current cursor position and moves it to the killring. o p pastes text from the killring. o u search history backwards. o [ and ] search the command history for the previous/next token con- taining the token under the cursor before the search was started. See the history section for more information on history searching. o Backspace moves the cursor left. INSERT MODE o Escape enters command mode. o Backspace removes one character to the left. VISUAL MODE o ^a (Left) and ^a (Right) extend the selection backward/forward by one character. o b and w extend the selection backward/forward by one word. o d and x move the selection to the killring and enter command mode. o Escape and Control+C enter command mode. COPY AND PASTE (KILL RING) fish uses an Emacs-style kill ring for copy and paste functionality. For example, use Control+K (kill-line) to cut from the current cursor position to the end of the line. The string that is cut (a.k.a. killed in emacs-ese) is inserted into a list of kills, called the kill ring. To paste the latest value from the kill ring (emacs calls this "yank- ing") use Control+Y (the yank input function). After pasting, use Alt+Y (yank-pop) to rotate to the previous kill. Copy and paste from outside are also supported, both via the Control+X / Control+V bindings (the fish_clipboard_copy and fish_clipboard_paste functions [4]) and via the terminal's paste function, for which fish enables "Bracketed Paste Mode", so it can tell a paste from manually entered text. In addition, when pasting inside single quotes, pasted single quotes and backslashes are automatically escaped so that the re- sult can be used as a single token simply by closing the quote after. [4] These rely on external tools. Currently xsel, xclip, wl-copy/wl-paste and pbcopy/pbpaste are supported. SEARCHABLE HISTORY After a command has been entered, it is inserted at the end of a his- tory list. Any duplicate history items are automatically removed. By pressing the up and down keys, the user can search forwards and back- wards in the history. If the current command line is not empty when starting a history search, only the commands containing the string en- tered into the command line are shown. By pressing Alt+^a,Up and Alt+^a,Down, a history search is also per- formed, but instead of searching for a complete commandline, each com- mandline is broken into separate elements just like it would be before execution, and the history is searched for an element matching that un- der the cursor. History searches can be aborted by pressing the escape key. Prefixing the commandline with a space will prevent the entire line from being stored in the history. The command history is stored in the file ~/.local/share/fish/fish_his- tory (or $XDG_DATA_HOME/fish/fish_history if that variable is set) by default. However, you can set the fish_history environment variable to change the name of the history session (resulting in a <session>_his- tory file); both before starting the shell and while the shell is run- ning. See the history command for other manipulations. Examples: To search for previous entries containing the word 'make', type make in the console and press the up key. If the commandline reads cd m, place the cursor over the m character and press Alt+^a,Up to search for previously typed words containing 'm'. MULTILINE EDITING The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line: o Pressing the Enter key while a block of commands is unclosed, such as when one or more block commands such as for, begin or if do not have a corresponding end command. o Pressing Alt+Enter instead of pressing the Enter key. o By inserting a backslash (\) character before pressing the Enter key, escaping the newline. The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right ar- row keys and other such keyboard shortcuts. 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. 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 behavior. o 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. o By pressing Control+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 Control+X z to stop running. o By using the bg and fg builtin commands, the user can send any cur- rently running job into the foreground or background. Note that functions cannot be started in the background. Functions that are stopped and then restarted in the background using the bg command will not execute correctly. On startup, Fish evaluates a number of configuration files, which can be used to control the behavior of the shell. The location of these is controlled by a number of environment variables, and their default or usual location is given below. Configuration files are evaluated in the following order: o Configuration shipped with fish, which should not be edited, in $__fish_data_dir/config.fish (usually /usr/share/fish/config.fish). o Configuration snippets in files ending in .fish, in the directories: o $__fish_config_dir/conf.d (by default, ~/.config/fish/conf.d/) o $__fish_sysconf_dir/conf.d (by default, /etc/fish/conf.d/) o Directories for third-party software vendors to ship their own con- figuration snippets for their software. Fish searches the directo- ries in the XDG_DATA_DIRS environment variable for a fish/ven- dor_conf.d directory; if this variable is not defined, the default is usually to search /usr/share/fish/vendor_conf.d and /usr/lo- cal/share/fish/vendor_conf.d If there are multiple files with the same name in these directories, only the first will be executed. They are executed in order of their filename, sorted (like globs) in a natural order (i.e. "01" sorts be- fore "2"). o System-wide configuration files, where administrators can include initialization that should be run for all users on the system - simi- lar to /etc/profile for POSIX-style shells - in $__fish_sysconf_dir (usually /etc/fish/config.fish). o User initialization, usually in ~/.config/fish/config.fish (con- trolled by the XDG_CONFIG_HOME environment variable, and accessible as $__fish_config_dir). These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above. This wide search may be confusing. If you are unsure where to put your own customisations, use ~/.config/fish/config.fish. Note that ~/.config/fish/config.fish is sourced _after_ the snippets. This is so users can copy snippets and override some of their behavior. These files are all executed on the startup of every shell. 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 when using a login shell, use status --is-login instead. This will speed up the starting of non-interactive or non-login shells. If you are developing another program, you may wish to install configu- ration which is run for all users of the fish shell on a system. This is discouraged; if not carefully written, they may have side-effects or slow the startup of the shell. Additionally, users of other shells will not benefit from the Fish-specific configuration. However, if they are absolutely required, you may install them to the "vendor" configuration directory. As this path may vary from system to system, the pkgconfig framework should be used to discover this path with the output of pkg-config --variable confdir fish. Examples: If you want to add the directory ~/linux/bin to your PATH variable when using a login shell, add the following to your ~/.config/fish/con- fig.fish file: if status --is-login set -x PATH $PATH ~/linux/bin end If you want to run a set of commands when fish exits, use an event han- dler that is triggered by the exit of the shell: function on_exit --on-event fish_exit echo fish is now exiting end Feature flags are how fish stages changes that might break scripts. Breaking changes are introduced as opt-in, in a few releases they be- come opt-out, and eventually the old behavior is removed. You can see the current list of features via status features: > status features stderr-nocaret on 3.0 ^ no longer redirects stderr qmark-noglob off 3.0 ? no longer globs regex-easyesc off 3.1 string replace -r needs fewer \\'s There are two breaking changes in fish 3.0: caret ^ no longer redirects stderr, and question mark ? is no longer a glob. There is one breaking change in fish 3.1: string replace -r does a su- perfluous round of escaping for the replacement, so escaping back- slashes would look like string replace -ra '([ab])' '\\\\\\\$1' a. This flag removes that if turned on, so '\\\\$1' is enough. These changes are off by default. They can be enabled on a per session basis: > fish --features qmark-noglob,stderr-nocaret or opted into globally for a user: > set -U fish_features stderr-nocaret qmark-noglob Features will only be set on startup, so this variable will only take effect if it is universal or exported. You can also use the version as a group, so 3.0 is equivalent to "stderr-nocaret" and "qmark-noglob". Prefixing a feature with no- turns it off instead. SYNTAX HIGHLIGHTING fish interprets the command line as it is typed and uses syntax high- lighting 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: o Non existing commands. o Reading from or appending to a non existing file. o Incorrect use of output redirects o Mismatched parenthesis When the cursor is over a parenthesis or a quote, fish also highlights its matching quote or parenthesis. To customize the syntax highlighting, you can set the environment vari- ables listed in the Variables for changing highlighting colors section. PROGRAMMABLE TITLE When using most virtual terminals, it is possible to set the message displayed in the titlebar of the terminal window. This can be done au- tomatically in fish by defining the fish_title function. The fish_title function is executed before and after a new command is executed or put into the foreground and the output is used as a titlebar message. The status current-command builtin will always return the name of the job to be put into the foreground (or 'fish' if control is returning to the shell) when the fish_prompt function is called. The first argument to fish_title will contain the most recently executed foreground command as a string, starting with fish 2.2. Examples: The default fish title is: function fish_title echo (status current-command) ' ' pwd end To show the last command in the title: function fish_title echo $argv[1] end PROGRAMMABLE PROMPT When fish waits for input, it will display a prompt by evaluating the fish_prompt and fish_right_prompt functions. The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of fish_mode_prompt will be prepended on the left, though the default function only does this when in vi-mode. CONFIGURABLE GREETING If a function named fish_greeting exists, it will be run when entering interactive mode. Otherwise, if an environment variable named fish_greeting exists, it will be printed. PRIVATE MODE fish supports launching in private mode via fish --private (or fish -P for short). In private mode, old history is not available and any in- teractive commands you execute will not be appended to the global his- tory file, making it useful both for avoiding inadvertently leaking personal information (e.g. for screencasts) and when dealing with sen- sitive information to prevent it being persisted to disk. You can query the global variable fish_private_mode` (if set -q fish_private_mode ...) if you would like to respect the user's wish for privacy and alter the behavior of your own fish scripts. EVENT HANDLERS When defining a new function in fish, it is possible to make it into an event handler, i.e. a function that is automatically run when a spe- cific event takes place. Events that can trigger a handler currently are: o When a signal is delivered o When a process or job exits o When the value of a variable is updated o When the prompt is about to be shown o When a command lookup fails Example: To specify a signal handler for the WINCH signal, write: function my_signal_handler --on-signal WINCH echo Got WINCH signal! end Please note that event handlers only become active when a function is loaded, which means you might need to otherwise source or execute a function instead of relying on autoloading. One approach is to put it into your initialization file. For more information on how to define new event handlers, see the docu- mentation for the function command. DEBUGGING FISH SCRIPTS Fish includes a built in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can exe- cute any fish command (there are no debug commands as such). For exam- ple, you can check or change the value of any variables using printf and set. As another example, you can run status print-stack-trace to see how this breakpoint was reached. To resume normal execution of the script, simply type exit or [ctrl-D]. To start a debug session simply run the builtin command breakpoint at the point in a function or script where you wish to gain control. Also, the default action of the TRAP signal is to call this builtin. So a running script can be debugged by sending it the TRAP signal with the kill command. Once in the debugger, it is easy to insert new break- points by using the funced function to edit the definition of a func- tion. If you have a question not answered by this documentation, there are several avenues for help: o The official mailing list at fish-users@lists.sourceforge.net o The Internet Relay Chat channel, #fish on irc.oftc.net o The project GitHub page If you have an improvement for fish, you can submit it via the mailing list or the GitHub page. COMMANDS fish ships with the following commands: abbr - manage fish abbreviations Synopsis abbr --add [SCOPE] WORD EXPANSION abbr --erase WORD abbr --rename [SCOPE] OLD_WORD NEW_WORD abbr --show abbr --list abbr --query WORD... Description abbr manages abbreviations - user-defined words that are replaced with longer phrases after they are entered. For example, a frequently-run command like git checkout can be abbrevi- ated to gco. After entering gco and pressing Space or Enter, the full text git checkout will appear in the command line. Options The following options are available: o -a WORD EXPANSION or --add WORD EXPANSION Adds a new abbreviation, causing WORD to be expanded to EXPANSION. o -r OLD_WORD NEW_WORD or --rename OLD_WORD NEW_WORD Renames an abbre- viation, from OLD_WORD to NEW_WORD. o -s or --show Show all abbreviations in a manner suitable for export and import. o -l or --list Lists all abbreviated words. o -e WORD or --erase WORD Erase the abbreviation WORD. o -q or --query Return 0 (true) if one of the WORDs is an abbreviation. In addition, when adding or renaming abbreviations: o -g or --global to use a global variable. o -U or --universal to use a universal variable (default). See the "Internals" section for more on them. Examples abbr -a -g gco git checkout Add a new abbreviation where gco will be replaced with git checkout global to the current shell. This abbreviation will not be automati- cally visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish). abbr -a -U l less Add a new abbreviation where l will be replaced with less universal so all shells. Note that you omit the -U since it is the default. abbr -r gco gch Renames an existing abbreviation from gco to gch. abbr -e gco Erase the gco abbreviation. ssh another_host abbr -s | source Import the abbreviations defined on another_host over SSH. Internals Each abbreviation is stored in its own global or universal variable. The name consists of the prefix _fish_abbr_ followed by the WORD after being transformed by string escape style=var. The WORD cannot contain a space but all other characters are legal. Defining an abbreviation with global scope is slightly faster than uni- versal scope (which is the default). But in general you'll only want to use the global scope when defining abbreviations in a startup script like ~/.config/fish/config.fish like this: if status --is-interactive abbr --add --global first 'echo my first abbreviation' abbr --add --global second 'echo my second abbreviation' abbr --add --global gco git checkout # etcetera end You can create abbreviations interactively and they will be visible to other fish sessions if you use the -U or --universal flag or don't ex- plicitly specify the scope and the abbreviation isn't already defined with global scope. If you want it to be visible only to the current shell use the -g or --global flag. alias - create a function Synopsis alias alias [OPTIONS] NAME DEFINITION alias [OPTIONS] NAME=DEFINITION Description alias is a simple wrapper for the function builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell alias. For other uses, it is recommended to define a function. fish marks functions that have been created by alias by including the command used to create them in the function description. You can list alias-created functions by running alias without arguments. They must be erased using functions -e. o NAME is the name of the alias o DEFINITION is the actual command to execute. The string $argv will be appended. You cannot create an alias to a function with the same name. Note that spaces need to be escaped in the call to alias just like at the command line, even inside quoted parts. The following options are available: o -h or --help displays help about using this command. o -s or --save Automatically save the function created by the alias into your fish configuration directory using funcsave. Example The following code will create rmi, which runs rm with additional argu- ments on every invocation. alias rmi="rm -i" # This is equivalent to entering the following function: function rmi --wraps rm --description 'alias rmi=rm -i' rm -i $argv end # This needs to have the spaces escaped or "Chrome.app..." will be seen as an argument to "/Applications/Google": alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana' and - conditionally execute a command Synopsis COMMAND1; and COMMAND2 Description and is used to execute a command if the previous command was successful (returned a status of 0). and statements may be used as part of the condition in an while or if block. and does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the $status variable. Example The following code runs the make command to build a program. If the build succeeds, make's exit status is 0, and the program is installed. If either step fails, the exit status is 1, and make clean is run, which removes the files created by the build process. make; and make install; or make clean See Also o or command argparse - parse options passed to a fish script or function Synopsis argparse [OPTIONS] OPTION_SPEC... -- [ARG...] Description This command makes it easy for fish scripts and functions to handle ar- guments like how fish builtin commands handle their arguments. You pass arguments that define the known options, followed by a literal --, then the arguments to be parsed (which might also include a literal --). argparse then sets variables to indicate the passed options with their values, and sets $argv (and always $argv) to the remaining arguments. More on this in the usage section below. Each option specification (OPTION_SPEC) is written in the domain spe- cific language described below. All OPTION_SPECs must appear after any argparse flags and before the -- that separates them from the arguments to be parsed. Each option that is seen in the ARG list will result in a var name of the form _flag_X, where X is the short flag letter and the long flag name. The OPTION_SPEC always requires a short flag even if it can't be used. So there will always be _flag_X var set using the short flag let- ter if the corresponding short or long flag is seen. The long flag name var (e.g., _flag_help) will only be defined, obviously, if the OP- TION_SPEC includes a long flag name. For example _flag_h and _flag_help if -h or --help is seen. The var will be set with local scope (i.e., as if the script had done set -l _flag_X). If the flag is a boolean (that is, it just is passed or not, it doesn't have a value) the values are the short and long flags seen. If the option is not a boolean the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag var will not be set. Options The following argparse options are available. They must appear before all OPTION_SPECs: o -n or --name is the command name for use in error messages. By de- fault the current function name will be used, or argparse if run out- side of a function. o -x or --exclusive should be followed by a comma separated list of short or long options that are mutually exclusive. You can use this more than once to define multiple sets of mutually exclusive options. o -N or --min-args is followed by an integer that defines the minimum number of acceptable non-option arguments. The default is zero. o -X or --max-args is followed by an integer that defines the maximum number of acceptable non-option arguments. The default is infinity. o -i or --ignore-unknown ignores unknown options, keeping them and their arguments in $argv instead. o -s or --stop-nonopt causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options. o -h or --help displays help about using this command. Usage Using this command requires first passing option specifications (OP- TION_SPEC below), then a mandatory --, and then the arguments you want to have parsed. More about this below but here is a simple example that might be used in a function named my_function: argparse --name=my_function 'h/help' 'n/name=' -- $argv or return If $argv is empty then there is nothing to parse and argparse returns zero to indicate success. If $argv is not empty then it is checked for flags -h, --help, -n and --name. If they are found they are removed from the arguments and local variables are set so the script can deter- mine which options were seen. Assuming $argv doesn't have any errors, such as a missing mandatory value for an option, then argparse exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one. The -- argument is required. You do not have to include any arguments after the -- but you must include the --. For example, this is accept- able: set -l argv argparse 'h/help' 'n/name' -- $argv But this is not: set -l argv argparse 'h/help' 'n/name' $argv The first -- seen is what allows the argparse command to reliably sepa- rate the option specifications from the command arguments. Option Specifications Each option specification is a string composed of o A short flag letter (which is mandatory). It must be an alphanumeric or "#". The "#" character is special and means that a flag of the form -123 is valid. The short flag "#" must be followed by "-" (since the short name isn't otherwise valid since _flag_# is not a valid var name) and must be followed by a long flag name with no modifiers. o A / if the short flag can be used by someone invoking your command else - if it should not be exposed as a valid short flag. If there is no long flag name these characters should be omitted. You can also specify a '#' to indicate the short and long flag names can be used and the value can be specified as an implicit int; i.e., a flag of the form -NNN. o A long flag name which is optional. If not present then only the short flag letter can be used. o Nothing if the flag is a boolean that takes no argument or is an im- plicit int flag, else o = if it requires a value and only the last instance of the flag is saved, else o =? it takes an optional value and only the last instance of the flag is saved, else o =+ if it requires a value and each instance of the flag is saved. o Optionally a ! followed by fish script to validate the value. Typi- cally this will be a function to run. If the exit status is zero the value for the flag is valid. If non-zero the value is invalid. Any error messages should be written to stdout (not stderr). See the sec- tion on Flag Value Validation for more information. See the fish_opt command for a friendlier but more verbose way to cre- ate option specifications. In the following examples if a flag is not seen when parsing the argu- ments then the corresponding _flag_X var(s) will not be set. Flag Value Validation Sometimes you need to validate the option values. For example, that it is a valid integer within a specific range, or an ip address, or some- thing entirely different. You can always do this after argparse returns but you can also request that argparse perform the validation by exe- cuting arbitrary fish script. To do so simply append an ! (exclama- tion-mark) then the fish script to be run. When that code is executed three vars will be defined: o _argparse_cmd will be set to the value of the value of the argparse --name value. o _flag_name will be set to the short or long flag that being pro- cessed. o _flag_value will be set to the value associated with the flag being processed. If you do this via a function it should be defined with the --no-scope-shadowing flag. Otherwise it won't have access to those variables. The script should write any error messages to stdout, not stderr. It should return a status of zero if the flag value is valid otherwise a non-zero status to indicate it is invalid. Fish ships with a _validate_int function that accepts a --min and --max flag. Let's say your command accepts a -m or --max flag and the minimum allowable value is zero and the maximum is 5. You would define the op- tion like this: m/max=!_validate_int --min 0 --max 5. The default if you just call _validate_int without those flags is to simply check that the value is a valid integer with no limits on the min or max value al- lowed. Example OPTION_SPECs Some OPTION_SPEC examples: o h/help means that both -h and --help are valid. The flag is a boolean and can be used more than once. If either flag is used then _flag_h and _flag_help will be set to the count of how many times either flag was seen. o h-help means that only --help is valid. The flag is a boolean and can be used more than once. If the long flag is used then _flag_h and _flag_help will be set to the count of how many times the long flag was seen. o n/name= means that both -n and --name are valid. It requires a value and can be used at most once. If the flag is seen then _flag_n and _flag_name will be set with the single mandatory value associated with the flag. o n/name=? means that both -n and --name are valid. It accepts an op- tional value and can be used at most once. If the flag is seen then _flag_n and _flag_name will be set with the value associated with the flag if one was provided else it will be set with no values. o n-name=+ means that only --name is valid. It requires a value and can be used more than once. If the flag is seen then _flag_n and _flag_name will be set with the values associated with each occur- rence of the flag. o x means that only -x is valid. It is a boolean that can be used more than once. If it is seen then _flag_x will be set to the count of how many times the flag was seen. o x=, x=?, and x=+ are similar to the n/name examples above but there is no long flag alternative to the short flag -x. o x- is not valid since there is no long flag name and therefore the short flag, -x, has to be usable. o #-max means that flags matching the regex "^--?d+$" are valid. When seen they are assigned to the variable _flag_max. This allows any valid positive or negative integer to be specified by prefixing it with a single "-". Many commands support this idiom. For example head -3 /a/file to emit only the first three lines of /a/file. o n#max means that flags matching the regex "^--?d+$" are valid. When seen they are assigned to the variables _flag_n and _flag_max. This allows any valid positive or negative integer to be specified by pre- fixing it with a single "-". Many commands support this idiom. For example head -3 /a/file to emit only the first three lines of /a/file. You can also specify the value using either flag: -n NNN or --max NNN in this example. After parsing the arguments the argv var is set with local scope to any values not already consumed during flag processing. If there are not unbound values the var is set but count $argv will be zero. If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr. begin - start a new block of code Synopsis begin; [COMMANDS...;] end Description begin is used to create a new block of code. A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like and. The block is unconditionally executed. begin; ...; end is equivalent to if true; ...; end. begin does not change the current exit status itself. After the block has completed, $status will be set to the status returned by the most recent command. Example The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends. begin set -l PIRATE Yarrr ... end echo $PIRATE # This will not output anything, since the PIRATE variable # went out of scope at the end of the block In the following code, all output is redirected to the file out.html. begin echo $xml_header echo $html_header if test -e $file ... end ... end > out.html bg - send jobs to background Synopsis bg [PID...] Description bg sends jobs to the background, resuming them if they are stopped. A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background. When at least one of the arguments isn't a valid job specifier (i.e. PID), bg will print an error without backgrounding anything. When all arguments are valid job specifiers, bg will background all matching jobs that exist. Example bg 123 456 789 will background 123, 456 and 789. If only 123 and 789 exist, it will still background them and print an error about 456. bg 123 banana or bg banana 123 will complain that "banana" is not a valid job specifier. bind - handle fish key bindings Synopsis bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [(-s | --silent)] [(-k | --key)] SEQUENCE COMMAND [COMMAND...] bind [(-M | --mode) MODE] [(-k | --key)] [--preset] [--user] SEQUENCE bind (-K | --key-names) [(-a | --all)] [--preset] [--user] bind (-f | --function-names) bind (-L | --list-modes) bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...]) Description bind adds a binding for the specified key sequence to the specified command. SEQUENCE is the character sequence to bind to. These should be written as fish escape sequences. For example, because pressing the Alt key and another character sends that character prefixed with an escape charac- ter, Alt-based key bindings can be written using the \e escape. For ex- ample, Alt+w can be written as \ew. The control character can be writ- ten in much the same way using the \c escape, for example Control+X (^X) can be written as \cx. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not fish. The default key binding can be set by specifying a SEQUENCE of the empty string (that is, '' ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the self-insert function (i.e. bind '' self-insert) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable. If the -k switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See terminfo(5) for more information, or use bind --key-names for a list of all available named keys.) If used in conjunction with the -s switch, bind will silently ignore bindings to named keys that are not found in termcap for the current $TERMINAL, otherwise a warning is emitted. COMMAND can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use bind --function-names for a complete list of these input functions. When COMMAND is a shellscript command, it is a good practice to put the actual code into a function and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well. If a script produces output, it should finish by calling commandline -f repaint to tell fish that a repaint is in order. When multiple COMMANDs are provided, they are all run in the specified order when the key is pressed. Note that special input functions cannot be combined with ordinary shell script commands. The commands must be entirely a sequence of special input functions (from bind -f) or all shell script commands (i.e., valid fish script). If no SEQUENCE is provided, all bindings (or just the bindings in the specified MODE) are printed. If SEQUENCE is provided without COMMAND, just the binding matching that sequence is printed. To save custom keybindings, put the bind statements into config.fish. Alternatively, fish also automatically executes a function called fish_user_key_bindings if it exists. Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the $fish_bind_mode variable. The following parameters are available: o -k or --key Specify a key name, such as 'left' or 'backspace' instead of a character sequence o -K or --key-names Display a list of available key names. Specifying -a or --all includes keys that don't have a known mapping o -f or --function-names Display a list of available input functions o -L or --list-modes Display a list of defined bind modes o -M MODE or --mode MODE Specify a bind mode that the bind is used in. Defaults to "default" o -m NEW_MODE or --sets-mode NEW_MODE Change the current mode to NEW_MODE after this binding is executed o -e or --erase Erase the binding with the given sequence and mode in- stead of defining a new one. Multiple sequences can be specified with this flag. Specifying -a or --all with -M or --mode erases all binds in the given mode regardless of sequence. Specifying -a or --all without -M or --mode erases all binds in all modes regardless of se- quence. o -a or --all See --erase and --key-names o --preset and --user specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all bind invocations work on the "user" level except for listing, which will show both levels. All in- vocations except for inserting new bindings can operate on both lev- els at the same time. --preset should only be used in full binding sets (like when working on fish_vi_key_bindings). Special input functions The following special input functions are available: o and, only execute the next function if the previous succeeded (note: only some functions report success) o accept-autosuggestion, accept the current autosuggestion completely o backward-char, moves one character to the left o backward-bigword, move one whitespace-delimited word to the left o backward-delete-char, deletes one character of input to the left of the cursor o backward-kill-bigword, move the whitespace-delimited word to the left of the cursor to the killring o backward-kill-line, move everything from the beginning of the line to the cursor to the killring o backward-kill-path-component, move one path component to the left of the cursor to the killring. A path component is everything likely to belong to a path component, i.e. not any of the following: /={,}'":@ |;___, plus newlines and tabs. o backward-kill-word, move the word to the left of the cursor to the killring. The "word" here is everything up to punctuation or white- space. o backward-word, move one word to the left o beginning-of-buffer, moves to the beginning of the buffer, i.e. the start of the first line o beginning-of-history, move to the beginning of the history o beginning-of-line, move to the beginning of the line o begin-selection, start selecting text o cancel, cancel the current commandline and replace it with a new empty one o capitalize-word, make the current word begin with a capital letter o complete, guess the remainder of the current token o complete-and-search, invoke the searchable pager on completion op- tions (for convenience, this also moves backwards in the completion pager) o delete-char, delete one character to the right of the cursor o delete-or-exit, deletes one character to the right of the cursor or exits the shell if the commandline is empty. o down-line, move down one line o downcase-word, make the current word lowercase o end-of-buffer, moves to the end of the buffer, i.e. the end of the first line o end-of-history, move to the end of the history o end-of-line, move to the end of the line o end-selection, end selecting text o expand-abbr expands any abbreviation currently under the cursor o execute run the current commandline o force-repaint reexecute the prompt functions without coalescing o forward-bigword, move one whitespace-delimited word to the right o forward-char, move one character to the right o forward-word, move one word to the right o history-search-backward, search the history for the previous match o history-search-forward, search the history for the next match o history-prefix-search-backward, search the history for the previous prefix match o history-prefix-search-forward, search the history for the next prefix match o history-token-search-backward, search the history for the previous matching argument o history-token-search-forward, search the history for the next match- ing argument o forward-jump and backward-jump, read another character and jump to its next occurence after/before the cursor o forward-jump-till and backward-jump-till, jump to right before the next occurence o repeat-jump and repeat-jump-reverse, redo the last jump in the same/opposite direction o kill-bigword, move the next whitespace-delimited word to the killring o kill-line, move everything from the cursor to the end of the line to the killring o kill-selection, move the selected text to the killring o kill-whole-line, move the line to the killring o kill-word, move the next word to the killring o pager-toggle-search, toggles the search field if the completions pager is visible. o repaint reexecutes the prompt functions and redraws the prompt. Mul- tiple successive repaints are coalesced. o repaint-mode reexecutes the fish_mode_prompt function and redraws the prompt. This is useful for vi-mode. If no fish_mode_prompt exists, it acts like a normal repaint. o self-insert, inserts the matching sequence into the command line o self-insert-notfirst, inserts the matching sequence into the command line, unless the cursor is at the beginning o suppress-autosuggestion, remove the current autosuggestion o swap-selection-start-stop, go to the other end of the highlighted text without changing the selection o transpose-chars, transpose two characters to the left of the cursor o transpose-words, transpose two words to the left of the cursor o up-line, move up one line o upcase-word, make the current word uppercase o yank, insert the latest entry of the killring into the buffer o yank-pop, rotate to the previous entry of the killring Examples bind \cd 'exit' Causes fish to exit when Control+D is pressed. bind -k ppage history-search-backward Performs a history search when the Page Up key is pressed. set -g fish_key_bindings fish_vi_key_bindings bind -M insert \cc kill-whole-line force-repaint Turns on Vi key bindings and rebinds Control+C to clear the input line. Special Case: The escape Character The escape key can be used standalone, for example, to switch from in- sertion mode to normal mode when using Vi keybindings. Escape can also be used as a "meta" key, to indicate the start of an escape sequence, like for function or arrow keys. Custom bindings can also be defined that begin with an escape character. Holding alt and something else also typically sends escape, for example holding alt+a will send an escape character and then an "a". fish waits for a period after receiving the escape character, to deter- mine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone es- cape. The waiting period is set to 30 milliseconds (0.03 seconds). It can be configured by setting the fish_escape_delay_ms variable to a value between 10 and 5000 ms. This can be a universal variable that you set once from an interactive session. block - temporarily block delivery of events Synopsis block [OPTIONS...] Description block prevents events triggered by fish or the emit command from being delivered and acted upon while the block is in place. In functions, block can be useful while performing work that should not be interrupted by the shell. The block can be removed. Any events which triggered while the block was in place will then be delivered. Event blocks should not be confused with code blocks, which are created with begin, if, while or for The following parameters are available: o -l or --local Release the block automatically at the end of the cur- rent innermost code block scope o -g or --global Never automatically release the lock o -e or --erase Release global block Example # Create a function that listens for events function --on-event foo foo; echo 'foo fired'; end # Block the delivery of events block -g emit foo # No output will be produced block -e # 'foo fired' will now be printed Notes Note that events are only received from the current fish process as there is no way to send events from one fish process to another. break - stop the current inner loop Synopsis LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end Description break halts a currently running loop, such as a switch, for or while loop. It is usually added inside of a conditional block such as an if block. There are no parameters for break. Example The following code searches all .c files for "smurf", and halts at the first occurrence. for i in *.c if grep smurf $i echo Smurfs are present in $i break end end breakpoint - Launch debug mode Synopsis breakpoint Description breakpoint is used to halt a running script and launch an interactive debugging prompt. For more details, see Debugging fish scripts in the fish manual. There are no parameters for breakpoint. builtin - run a builtin command Synopsis builtin [OPTIONS...] BUILTINNAME builtin --query BUILTINNAMES... Description builtin forces the shell to use a builtin command, rather than a func- tion or program. The following parameters are available: o -n or --names List the names of all defined builtins o -q or --query tests if any of the specified builtins exists Example builtin jobs # executes the jobs builtin, even if a function named jobs exists case - conditionally execute a block of commands Synopsis switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end Description switch executes one of several blocks of commands, depending on whether a specified value matches one of several values. case is used together with the switch statement in order to determine which block should be executed. Each case command is given one or more parameters. The first case com- mand with a parameter that matches the string specified in the switch command will be evaluated. case parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expan- sion using filenames. Note that fish does not fall through on case statements. Only the first matching case is executed. Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. Example Say $animal contains the name of an animal. Then this code would clas- sify it: switch $animal case cat echo evil case wolf dog human moose dolphin whale echo mammal case duck goose albatross echo bird case shark trout stingray echo fish # Note that the next case has a wildcard which is quoted case '*' echo I have no idea what a $animal is end If the above code was run with $animal set to whale, the output would be mammal. If $animal was set to "banana", it would print "I have no idea what a banana is". cd - change directory Synopsis cd [DIRECTORY] Description cd changes the current working directory. If DIRECTORY is supplied, it will become the new directory. If no pa- rameter is given, the contents of the HOME environment variable will be used. If DIRECTORY is a relative path, the paths found in the CDPATH list will be tried as prefixes for the specified path, in addition to $PWD. Note that the shell will attempt to change directory without requiring cd if the name of a directory is provided (starting with ., / or ~, or ending with /). Fish also ships a wrapper function around the builtin cd that under- stands cd - as changing to the previous directory. See also prevd. This wrapper function maintains a history of the 25 most recently visited directories in the $dirprev and $dirnext global variables. If you make those universal variables your cd history is shared among all fish in- stances. As a special case, cd . is equivalent to cd $PWD, which is useful in cases where a mountpoint has been recycled or a directory has been re- moved and recreated. Examples cd # changes the working directory to your home directory. cd /usr/src/fish-shell # changes the working directory to /usr/src/fish-shell See Also See also the cdh command for changing to a recently visited directory. cdh - change to a recently visited directory Synopsis cdh [ directory ] Description cdh with no arguments presents a list of recently visited directories. You can then select one of the entries by letter or number. You can also press tab to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to cd direc- tory. Note that the cd command limits directory history to the 25 most re- cently visited directories. The history is stored in the $dirprev and $dirnext variables which this command manipulates. If you make those universal variables your cd history is shared among all fish instances. See Also See also the prevd and pushd commands which also work with the recent cd history and are provided for compatibility with other shells. command - run a program Synopsis command [OPTIONS] COMMANDNAME [ARGS...] Description command forces the shell to execute the program COMMANDNAME and ignore any functions or builtins with the same name. The following options are available: o -a or --all returns all the external COMMANDNAMEs that are found in $PATH in the order they are found. o -q or --quiet, silences the output and prints nothing, setting only the exit status. Implies --search. o -s or --search returns the name of the external command that would be executed, or nothing if no file with the specified name could be found in the $PATH. With the -s option, command treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified com- mands were found, or 1 if no commands could be found. Additionally passing a -q or --quiet option prevents any paths from being printed, like type -q, for testing only the exit status. For basic compatibility with POSIX command, the -v flag is recognized as an alias for -s. Examples command ls causes fish to execute the ls program, even if an ls func- tion exists. command -s ls returns the path to the ls program. command -q git; and command git log runs git log only if git exists. commandline - set or get the current command line buffer Synopsis commandline [OPTIONS] [CMD] Description commandline can be used to set or get the current contents of the com- mand line buffer. With no parameters, commandline returns the current value of the com- mand line. With CMD specified, the command line buffer is erased and replaced with the contents of CMD. The following options are available: o -C or --cursor set or get the current cursor position, not the con- tents of the buffer. If no argument is given, the current cursor po- sition is printed, otherwise the argument is interpreted as the new cursor position. o -f or --function causes any additional arguments to be interpreted as input functions, and puts them into the queue, so that they will be read before any additional actual key presses are. This option cannot be combined with any other option. See bind for a list of input func- tions. The following options change the way commandline updates the command line buffer: o -a or --append do not remove the current commandline, append the specified string at the end of it o -i or --insert do not remove the current commandline, insert the specified string at the current cursor position o -r or --replace remove the current commandline and replace it with the specified string (default) The following options change what part of the commandline is printed or updated: o -b or --current-buffer select the entire buffer, including any dis- played autosuggestion (default) o -j or --current-job select the current job o -p or --current-process select the current process o -s or --current-selection selects the current selection o -t or --current-token select the current token The following options change the way commandline prints the current commandline buffer: o -c or --cut-at-cursor only print selection up until the current cur- sor position o -o or --tokenize tokenize the selection and print one string-type to- ken per line If commandline is called during a call to complete a given string using complete -C STRING, commandline will consider the specified string to be the current contents of the command line. The following options output metadata about the commandline state: o -L or --line print the line that the cursor is on, with the topmost line starting at 1 o -S or --search-mode evaluates to true if the commandline is perform- ing a history search o -P or --paging-mode evaluates to true if the commandline is showing pager contents, such as tab completions Example commandline -j $history[3] replaces the job under the cursor with the third item from the command line history. If the commandline contains >_ echo $fl___ounder >&2 | less; and echo $catfish (with the cursor on the "o" of "flounder") Then the following invocations behave like this: >_ commandline -t $flounder >_ commandline -ct $fl >_ commandline -b # or just commandline echo $flounder >&2 | less; and echo $catfish >_ commandline -p echo $flounder >&2 >_ commandline -j echo $flounder >&2 | less complete - edit command specific tab-completions Synopsis complete ( -c | --command | -p | --path ) COMMAND [( -c | --command | -p | --path ) COMMAND]... [( -e | --erase )] [( -s | --short-option ) SHORT_OPTION]... [( -l | --long-option | -o | --old-option ) LONG_OPTION]... [( -a | --arguments ) OPTION_ARGUMENTS] [( -k | --keep-order )] [( -f | --no-files )] [( -F | --force-files )] [( -r | --require-parameter )] [( -x | --exclusive )] [( -w | --wraps ) WRAPPED_COMMAND]... [( -n | --condition ) CONDITION] [( -d | --description ) DESCRIPTION] complete ( -C [STRING] | --do-complete[=STRING] ) Description For an introduction to specifying completions, see Writing your own completions in the fish manual. o COMMAND is the name of the command for which to add a completion. o SHORT_OPTION is a one character option for the command. o LONG_OPTION is a multi character option for the command. o OPTION_ARGUMENTS is parameter containing a space-separated list of possible option-arguments, which may contain command substitutions. o DESCRIPTION is a description of what the option and/or option argu- ments do. o -c COMMAND or --command COMMAND specifies that COMMAND is the name of the command. o -p COMMAND or --path COMMAND specifies that COMMAND is the absolute path of the program (optionally containing wildcards). o -e or --erase deletes the specified completion. o -s SHORT_OPTION or --short-option=SHORT_OPTION adds a short option to the completions list. o -l LONG_OPTION or --long-option=LONG_OPTION adds a GNU style long op- tion to the completions list. o -o LONG_OPTION or --old-option=LONG_OPTION adds an old style long op- tion to the completions list (See below for details). o -a OPTION_ARGUMENTS or --arguments=OPTION_ARGUMENTS adds the speci- fied option arguments to the completions list. o -k or --keep-order preserves the order of the OPTION_ARGUMENTS speci- fied via -a or --arguments instead of sorting alphabetically. Multi- ple complete calls with -k result in arguments of the later ones dis- played first. o -f or --no-files says that the options specified by this completion may not be followed by a filename. o -F or --force-files says that the options specified by this comple- tion may be followed by a filename, even if another applicable com- plete specified --no-files. o -r or --require-parameter says that the options specified by this completion must have an option argument, i.e. may not be followed by another option. o -x or --exclusive implies both -r and -f. o -w WRAPPED_COMMAND or --wraps=WRAPPED_COMMAND causes the specified command to inherit completions from the wrapped command (See below for details). o -n or --condition specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify comple- tions that should only be used in some cases. o -CSTRING or --do-complete=STRING makes complete try to find all pos- sible completions for the specified string. o -C or --do-complete with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned. o -A and --authoritative no longer do anything and are silently ig- nored. o -u and --unauthoritative no longer do anything and are silently ig- nored. Command specific tab-completions in fish are based on the notion of op- tions and arguments. An option is a parameter which begins with a hy- phen, such as '-h', '-help' or '--help'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are: o Short options, like '-a'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '-la', which is equivalent to '-l -a'). Option arguments may be spec- ified in the following parameter ('-w 32') or by appending the option with the value ('-w32'). o Old style long options, like '-Wall'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the fol- lowing parameter ('-ao null'). o GNU style long options, like '--colors'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('--quoting-style shell') or by appending the op- tion with a '=' and the value ('--quoting-style=shell'). GNU style long options may be abbreviated so long as the abbreviation is unique ('--h') is equivalent to '--help' if help is the only long option be- ginning with an 'h'). The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands. The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single call. Invoking complete multiple times for the same command adds the new def- initions on top of any existing completions defined for the command. When -a or --arguments is specified in conjunction with long, short, or old style options, the specified arguments are only used as completions when attempting to complete an argument for any of the specified op- tions. If -a or --arguments is specified without any long, short, or old style options, the specified arguments are used when completing any argument to the command (except when completing an option argument that was specified with -r or --require-parameter). Command substitutions found in OPTION_ARGUMENTS are not expected to re- turn a space-separated list of arguments. Instead they must return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Any descrip- tion provided in this way overrides a description given with -d or --description. The -w or --wraps options causes the specified command to inherit com- pletions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own comple- tions in addition to inherited ones. A command may wrap multiple com- mands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the -e or --erase options. Note that wrapping only works for com- pletions specified with -c or --command and are ignored when specifying completions with -p or --path. When erasing completions, it is possible to either erase all comple- tions for a specific command by specifying complete -c COMMAND -e, or by specifying a specific completion option to delete by specifying ei- ther a long, short or old style option. Example The short style option -o for the gcc command requires that a file fol- lows it. This can be done using writing: complete -c gcc -s o -r The short style option -d for the grep command requires that one of the strings 'read', 'skip' or 'recurse' is used. This can be specified writing: complete -c grep -s d -x -a "read skip recurse" The su command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as: complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)" The rpm command has several different modes. If the -e or --erase flag has been specified, rpm should delete one or more packages, in which case several switches related to deleting packages are valid, like the nodeps switch. This can be written as: complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies" where __fish_contains_opt is a function that checks the command line buffer for the presence of a specified set of options. To implement an alias, use the -w or --wraps option: complete -c hub -w git Now hub inherits all of the completions from git. Note this can also be specified in a function declaration. contains - test if a word is present in a list Synopsis contains [OPTIONS] KEY [VALUES...] Description contains tests whether the set VALUES contains the string KEY. If so, contains exits with status 0; if not, it exits with status 1. The following options are available: o -i or --index print the word index Note that, like GNU tools and most of fish's builtins, contains inter- prets all arguments starting with a - as options to contains, until it reaches an argument that is -- (two dashes). See the examples below. Example If $animals is a list of animals, the following will test if it con- tains a cat: if contains cat $animals echo Your animal list is evil! end This code will add some directories to $PATH if they aren't yet in- cluded: for i in ~/bin /usr/local/bin if not contains $i $PATH set PATH $PATH $i end end While this will check if hasargs was run with the -q option: function hasargs if contains -- -q $argv echo '$argv contains a -q option' end end The -- here stops contains from treating -q to an option to itself. In- stead it treats it as a normal string to check. continue - skip the remainder of the current iteration of the current inner loop Synopsis LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end Description continue skips the remainder of the current iteration of the current inner loop, such as a for loop or a while loop. It is usually added in- side of a conditional block such as an if statement or a switch state- ment. Example The following code removes all tmp files that do not contain the word smurf. for i in *.tmp if grep smurf $i continue end # This "rm" is skipped over if "continue" is executed. rm $i # As is this "echo" echo $i end count - count the number of elements of a list Synopsis count $VARIABLE COMMAND | count count < FILE Description count prints the number of arguments that were passed to it, plus the number of newlines passed to it via stdin. This is usually used to find out how many elements an environment variable list contains, or how many lines there are in a text file. count does not accept any options, not even -h or --help. count exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed. Note that, like wc -l, reading from stdin counts newlines, so echo -n foo | count will print 0. Example count $PATH # Returns the number of directories in the users PATH variable. count *.txt # Returns the number of files in the current working directory ending with the suffix '.txt'. git ls-files --others --exclude-standard | count # Returns the number of untracked files in a git repository printf '%s\n' foo bar | count baz # Returns 3 (2 lines from stdin plus 1 argument) count < /etc/hosts # Counts the number of entries in the hosts file dirh - print directory history Synopsis dirh Description dirh prints the current directory history. The current position in the history is highlighted using the color defined in the fish_color_his- tory_current environment variable. dirh does not accept any parameters. Note that the cd command limits directory history to the 25 most re- cently visited directories. The history is stored in the $dirprev and $dirnext variables. dirs - print directory stack Synopsis dirs dirs -c Description dirs prints the current directory stack, as created by pushd and modi- fied by popd. With "-c", it clears the directory stack instead. dirs does not accept any parameters. disown - remove a process from the list of jobs Synopsis disown [ PID ... ] Description disown removes the specified job from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer. Jobs in the list of jobs are sent a hang-up signal when fish termi- nates, which usually causes the job to terminate; disown allows these processes to continue regardless. If no process is specified, the most recently-used job is removed (like bg and fg). If one or more PIDs are specified, jobs with the specified process IDs are removed from the job list. Invalid jobs are ignored and a warning is printed. If a job is stopped, it is sent a signal to continue running, and a warning is printed. It is not possible to use the bg builtin to con- tinue a job once it has been disowned. disown returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered. Example firefox &; disown will start the Firefox web browser in the background and remove it from the job list, meaning it will not be closed when the fish process is closed. disown (jobs -p) removes all jobs from the job list without terminating them. echo - display a line of text Synopsis echo [OPTIONS] [STRING] Description echo displays a string of text. The following options are available: o -n, Do not output a newline o -s, Do not separate arguments with spaces o -E, Disable interpretation of backslash escapes (default) o -e, Enable interpretation of backslash escapes Escape Sequences If -e is used, the following sequences are recognized: o \ backslash o \a alert (BEL) o \b backspace o \c produce no further output o \e escape o \f form feed o \n new line o \r carriage return o \t horizontal tab o \v vertical tab o \0NNN byte with octal value NNN (1 to 3 digits) o \xHH byte with hexadecimal value HH (1 to 2 digits) Example echo 'Hello World' Print hello world to stdout echo -e 'Top\\nBottom' Print Top and Bottom on separate lines, using an escape sequence else - execute command if a condition is not met Synopsis if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end Description if will execute the command CONDITION. If the condition's exit status is 0, the commands COMMANDS_TRUE will execute. If it is not 0 and else is given, COMMANDS_FALSE will be executed. Example The following code tests whether a file foo.txt exists as a regular file. if test -f foo.txt echo foo.txt exists else echo foo.txt does not exist end emit - Emit a generic event Synopsis emit EVENT_NAME [ARGUMENTS...] Description emit emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments. Example The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type. function event_test --on-event test_event echo event test: $argv end emit test_event something Notes Note that events are only sent to the current fish process as there is no way to send events from one fish process to another. end - end a block of commands. Synopsis begin; [COMMANDS...] end if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end while CONDITION; COMMANDS...; end for VARNAME in [VALUES...]; COMMANDS...; end switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end Description end ends a block of commands. For more information, read the documentation for the block constructs, such as if, for and while. The end command does not change the current exit status. Instead, the status after it will be the status returned by the most recent command. eval - evaluate the specified commands Synopsis eval [COMMANDS...] Description eval evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator. If your command does not need access to stdin, consider using source instead. If no piping or other compound shell constructs are required, vari- able-expansion-as-command, as in set cmd ls -la; $cmd, is also an op- tion. Example The following code will call the ls command and truncate each filename to the first 12 characters. set cmd ls \| cut -c 1-12 eval $cmd exec - execute command in current process Synopsis exec COMMAND [OPTIONS...] Description exec replaces the currently running shell with a new command. On suc- cessful completion, exec never returns. exec cannot be used inside a pipeline. Example exec emacs starts up the emacs text editor, and exits fish. When emacs exits, the session will terminate. exit - exit the shell Synopsis exit [STATUS] Description exit causes fish to exit. If STATUS is supplied, it will be converted to an integer and used as the exit status. Otherwise, the exit status will be that of the last command executed. If exit is called while sourcing a file (using the source builtin) the rest of the file will be skipped, but the shell itself will not exit. false - return an unsuccessful result Synopsis false Description false sets the exit status to 1. See Also o true command o $status variable fg - bring job to foreground Synopsis fg [PID] Description fg brings the specified job to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground. Example fg will put the last job in the foreground. fish - the friendly interactive shell Synopsis fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]] Description fish is a command-line shell written mainly with interactive use in mind. This page briefly describes the options for invoking fish. The full manual is available in HTML by using the help command from inside fish, and in the fish-doc(1) man page. The tutorial is available as HTML via help tutorial or in fish-tutorial(1). The following options are available: o -c or --command=COMMANDS evaluate the specified commands instead of reading from the commandline o -C or --init-command=COMMANDS evaluate the specified commands after reading the configuration, before running the command specified by -c or reading interactive input o -d or --debug=CATEGORY_GLOB enables debug output and specifies a glob for matching debug categories (like fish -d). Defaults to empty. o -o or --debug-output=path Specify a file path to receive the debug output, including categories and fish_trace. The default is stderr. o -i or --interactive specify that fish is to run in interactive mode o -l or --login specify that fish is to run as a login shell o -n or --no-execute do not execute any commands, only perform syntax checking o -p or --profile=PROFILE_FILE when fish exits, output timing informa- tion on all executed commands to the specified file o -P or --private enables private mode, so fish will not access old or store new history. o --print-rusage-self when fish exits, output stats from getrusage o --print-debug-categories outputs the list of debug categories, and then exits. o -v or --version display version and exit o -D or --debug-stack-frames=DEBUG_LEVEL specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128. o -f or --features=FEATURES enables one or more feature flags (sepa- rated by a comma). These are how fish stages changes that might break scripts. The fish exit status is generally the exit status of the last fore- ground command. If fish is exiting because of a parse error, the exit status is 127. fish_breakpoint_prompt - define the prompt when stopped at a breakpoint Synopsis function fish_breakpoint_prompt ... end Description By defining the fish_breakpoint_prompt function, the user can choose a custom prompt when asking for input in response to a breakpoint com- mand. The fish_breakpoint_prompt function is executed when the prompt is to be shown, and the output is used as a prompt. The exit status of commands within fish_breakpoint_prompt will not mod- ify the value of $status outside of the fish_breakpoint_prompt func- tion. fish ships with a default version of this function that displays the function name and line number of the current execution context. Example A simple prompt that is a simplified version of the default debugging prompt: function fish_breakpoint_prompt -d "Write out the debug prompt" set -l function (status current-function) set -l line (status current-line-number) set -l prompt "$function:$line >" echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) ' ' end fish_config - start the web-based configuration interface Synopsis fish_config [TAB] Description fish_config starts the web-based configuration interface. The web interface allows you to view your functions, variables and his- tory, and to make changes to your prompt and color configuration. fish_config starts a local web server and then opens a web browser win- dow; when you have finished, close the browser window and then press the Enter key to terminate the configuration session. fish_config optionally accepts name of the initial configuration tab. For e.g. fish_config history will start configuration interface with history tab. If the BROWSER environment variable is set, it will be used as the name of the web browser to open instead of the system default. Example fish_config opens a new web browser window and allows you to configure certain fish settings. fish_git_prompt - output git information for use in a prompt Synopsis function fish_prompt echo -n (pwd)(fish_git_prompt) '$ ' end Description The fish_git_prompt function displays information about the current git repository, if any. Git must be installed. There are numerous customization options, which can be controlled with git options or fish variables. git options, where available, take precedence over the fish variable with the same function. git options can be set on a per-repository or global basis. git options can be set with the git config command, while fish variables can be set as usual with the set command. o $__fish_git_prompt_show_informative_status or the git option bash.showInformativeStatus can be set to enable the "informative" display, which will show a large amount of information - the number of untracked files, dirty files, unpushed/unpulled commits, and more. In large repositories, this can take a lot of time, so it you may wish to disable it in these repositories with git config --local bash.showInformativeStatus false. o $__fish_git_prompt_showdirtystate or the git option bash.showDirtyS- tate can be set to show if the repository is "dirty", i.e. has uncom- mitted changes. o $__fish_git_prompt_showuntrackedfiles or the git option bash.showUn- trackedFiles can be set to show if the repository has untracked files (that aren't ignored). o $__fish_git_prompt_showupstream can be set to a list of values to de- termine how changes between HEAD and upstream are shown: auto summarize the difference between HEAD and its upstream verbose show number of commits ahead/behind (+/-) upstream name if verbose, then also show the upstream abbrev name informative similar to verbose, but shows nothing when equal - this is the default if informative status is enabled. git always compare HEAD to @{upstream} svn always compare HEAD to your SVN upstream none disables (useful with informative status) o $__fish_git_prompt_showstashstate can be set to display the state of the stash. o $__fish_git_prompt_shorten_branch_len can be set to the number of characters that the branch name will be shortened to. o $__fish_git_prompt_describe_style can be set to one of the following styles to describe the current HEAD: contains relative to newer annotated tag, such as (v1.6.3.2~35) branch relative to newer tag or branch, such as (master~4) describe relative to older annotated tag, such as (v1.6.3.1-13-gdd42c2f) default exactly matching tag o $__fish_git_prompt_showcolorhints can be set to enable coloring for the branch name and status symbols. A number of variables set characters and color used as indicators. Many of these have a different default if used with informative status en- abled, or $__fish_git_prompt_use_informative_chars set. The usual de- fault is given first, then the informative default (if it is differ- ent). If no default for the colors is given, they default to $__fish_git_prompt_color. o $__fish_git_prompt_char_stateseparator (' ', |) o $__fish_git_prompt_color ('') o $__fish_git_prompt_color_prefix o $__fish_git_prompt_color_suffix o $__fish_git_prompt_color_bare o $__fish_git_prompt_color_merging Some variables are only used in some modes, like when informative sta- tus is enabled: o $__fish_git_prompt_char_cleanstate (a) o $__fish_git_prompt_color_cleanstate Variables used with showdirtystate: o $__fish_git_prompt_char_dirtystate (*, a) o $__fish_git_prompt_char_invalidstate (#, a) o $__fish_git_prompt_char_stagedstate (+, a) o $__fish_git_prompt_color_dirtystate (red with showcolorhints, same as color_flags otherwise) o $__fish_git_prompt_color_invalidstate o $__fish_git_prompt_color_stagedstate (green with showcolorhints, color_flags otherwise) Variables used with showstashstate: o $__fish_git_prompt_char_stashstate ($, a) o $__fish_git_prompt_color_stashstate (same as color_flags) Variables used with showuntrackedfiles: o $__fish_git_prompt_char_untrackedfiles (%, a|) o $__fish_git_prompt_color_untrackedfiles (same as color_flags) Variables used with showupstream (also implied by informative status): o $__fish_git_prompt_char_upstream_ahead (>, a) o $__fish_git_prompt_char_upstream_behind (<, a) o $__fish_git_prompt_char_upstream_diverged (<>) o $__fish_git_prompt_char_upstream_equal (=) o $__fish_git_prompt_char_upstream_prefix ('') o $__fish_git_prompt_color_upstream Colors used with showcolorhints: o $__fish_git_prompt_color_branch (green) o $__fish_git_prompt_color_branch_detached (red) o $__fish_git_prompt_color_flags (--bold blue) Note that all colors can also have a corresponding _done color. For ex- ample, the contents of $__fish_git_prompt_color_upstream_done is printed right _after_ the upstream. See also fish_vcs_prompt, which will call all supported version control prompt functions, including git, Mercurial and Subversion. Example A simple prompt that displays git info: function fish_prompt # ... set -g __fish_git_prompt_showupstream auto printf '%s %s$' $PWD (fish_git_prompt) end fish_hg_prompt - output Mercurial information for use in a prompt Synopsis function fish_prompt echo -n (pwd)(fish_hg_prompt) '$ ' end Description The fish_hg_prompt function displays information about the current Mer- curial repository, if any. Mercurial (hg) must be installed. By default, only the current branch is shown because hg status can take be slow on large repository. You can enable a more informative prompt by setting the variable $fish_prompt_hg_show_informative_status, for example: set --universal fish_prompt_hg_show_informative_status If you enabled the informative status, there are numerous customization options, which can be controlled with fish variables. o $fish_color_hg_clean, $fish_color_hg_modified and $fish_color_hg_dirty are colors used when the repository has the re- spective status. Some colors for status symbols: o $fish_color_hg_added o $fish_color_hg_renamed o $fish_color_hg_copied o $fish_color_hg_deleted o $fish_color_hg_untracked o $fish_color_hg_unmerged The status symbols themselves: o $fish_prompt_hg_status_added, default 'a' o $fish_prompt_hg_status_modified, default '*' o $fish_prompt_hg_status_copied, default 'a' o $fish_prompt_hg_status_deleted, default 'a' o $fish_prompt_hg_status_untracked, default '?' o $fish_prompt_hg_status_unmerged, default '!' Finally, $fish_prompt_hg_status_order, which can be used to change the order the status symbols appear in. It defaults to added modified copied deleted untracked unmerged. See also fish_vcs_prompt, which will call all supported version control prompt functions, including git, Mercurial and Subversion. Example A simple prompt that displays hg info: function fish_prompt ... set -g fish_prompt_hg_show_informative_status printf '%s %s$' $PWD (fish_hg_prompt) end fish_indent - indenter and prettifier Synopsis fish_indent [OPTIONS] [FILE...] Description fish_indent is used to indent a piece of fish code. fish_indent reads commands from standard input or the given filenames and outputs them to standard output or a specified file (if -w is given). The following options are available: o -w or --write indents a specified file and immediately writes to that file. o -i or --no-indent do not indent commands; only reformat to one job per line. o -v or --version displays the current fish version and then exits. o --ansi colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as $fish_color_command). o --html outputs HTML, which supports syntax highlighting if the appro- priate CSS is defined. The CSS class names are the same as the vari- able names, such as fish_color_command. o -d or --debug=CATEGORY_GLOB enables debug output and specifies a glob for matching debug categories (like fish -d). Defaults to empty. o -D or --debug-stack-frames=DEBUG_LEVEL specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128. o --dump-parse-tree dumps information about the parsed statements to stderr. This is likely to be of interest only to people working on the fish source code. fish_key_reader - explore what characters keyboard keys send Synopsis fish_key_reader [OPTIONS] Description fish_key_reader is used to study input received from the terminal and can help with key binds. The program is interactive and works on stan- dard input. Individual characters themselves and their hexadecimal val- ues are displayed. The tool will write an example bind command matching the character se- quence captured to stdout. If the character sequence matches a special key name (see bind --key-names), both bind CHARS ... and bind -k KEY- NAME ... usage will be shown. Additional details about the characters received, such as the delay between chars, are written to stderr. The following options are available: o -c or --continuous begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence. o -d or --debug=CATEGORY_GLOB enables debug output and specifies a glob for matching debug categories (like fish -d). Defaults to empty. o -D or --debug-stack-frames=DEBUG_LEVEL specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128. o -h or --help prints usage information. o -v or --version prints fish_key_reader's version and exits. Usage Notes The delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This informa- tion may be useful to determine the optimal fish_escape_delay_ms set- ting or learn the amount of lag introduced by tools like ssh, mosh or tmux. fish_key_reader intentionally disables handling of many signals. To terminate fish_key_reader in --continuous mode do: o press Ctrl-C twice, or o press Ctrl-D twice, or o type exit, or o type quit fish_mode_prompt - define the appearance of the mode indicator Synopsis function fish_mode_prompt echo -n "$fish_bind_mode " end Description The fish_mode_prompt function outputs the mode indicator for use in vi-mode. The default fish_mode_prompt function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. De- fine your own function to customize the appearance of the mode indica- tor. You can also define an empty fish_mode_prompt function to remove the Vi mode indicators. The $fish_bind_mode variable can be used to de- termine the current mode. It will be one of default, insert, re- place_one, or visual. fish_mode_prompt will be executed when the vi mode changes. If it pro- duces any output, it is displayed and used. If it does not, the other prompt functions (fish_prompt and fish_right_prompt) will be executed as well in case they contain a mode display. Example function fish_mode_prompt switch $fish_bind_mode case default set_color --bold red echo 'N' case insert set_color --bold green echo 'I' case replace_one set_color --bold green echo 'R' case visual set_color --bold brmagenta echo 'V' case '*' set_color --bold red echo '?' end set_color normal end Outputting multiple lines is not supported in fish_mode_prompt. fish_opt - create an option spec for the argparse command Synopsis fish_opt [ -h | --help ] fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] [ -o | --optional-val ] [ -r | --required-val ] [ --multiple-vals ] Description This command provides a way to produce option specifications suitable for use with the argparse command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides. The following argparse options are available: o -s or --short takes a single letter that is used as the short flag in the option being defined. This option is mandatory. o -l or --long takes a string that is used as the long flag in the op- tion being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option spec. o --long-only means the option spec being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., --short must be specified) but it cannot be used when parsing args using this option spec. o -o or --optional-val means the option being defined can take a value but it is optional rather than required. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by argparse will zero elements if no value was given with the option else it will have ex- actly one element. o -r or --required-val means the option being defined requires a value. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable cre- ated by argparse will have exactly one element. o --multiple-vals means the option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by argparse will have one element for each in- stance of this option in the args. o -h or --help displays help about using this command. Examples Define a single option spec for the boolean help flag: set -l options (fish_opt -s h -l help) argparse $options -- $argv Same as above but with a second flag that requires a value: set -l options (fish_opt -s h -l help) set options $options (fish_opt -s m -l max --required-val) argparse $options -- $argv Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only the long flag name (--token) can be used: set -l options (fish_opt --short=h --long=help) set options $options (fish_opt --short=m --long=max --required-val) set options $options (fish_opt --short=t --long=token --multiple-vals --long-only) argparse $options -- $argv fish_prompt - define the appearance of the command line prompt Synopsis function fish_prompt ... end Description By defining the fish_prompt function, the user can choose a custom prompt. The fish_prompt function is executed when the prompt is to be shown, and the output is used as a prompt. The exit status of commands within fish_prompt will not modify the value of $status outside of the fish_prompt function. fish ships with a number of example prompts that can be chosen with the fish_config command. Example A simple prompt: 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 fish_right_prompt - define the appearance of the right-side command line prompt Synopsis function fish_right_prompt ... end Description fish_right_prompt is similar to fish_prompt, except that it appears on the right side of the terminal window. Multiple lines are not supported in fish_right_prompt. Example A simple right prompt: function fish_right_prompt -d "Write out the right prompt" date '+%m/%d/%y' end fish_svn_prompt - output Subversion information for use in a prompt Synopsis function fish_prompt echo -n (pwd)(fish_svn_prompt) '$ ' end Description The fish_svn_prompt function displays information about the current Subversion repository, if any. Subversion (svn) must be installed. There are numerous customization options, which can be controlled with fish variables. o $__fish_svn_prompt_color_revision the colour of the revision number to display in the prompt o $__fish_svn_prompt_char_separator the separator between status characters A number of variables control the symbol ("display") and color ("color") for the different status indicators: o $__fish_svn_prompt_char_added_display o $__fish_svn_prompt_char_added_color o $__fish_svn_prompt_char_conflicted_display o $__fish_svn_prompt_char_conflicted_color o $__fish_svn_prompt_char_deleted_display o $__fish_svn_prompt_char_deleted_color o $__fish_svn_prompt_char_ignored_display o $__fish_svn_prompt_char_ignored_color o $__fish_svn_prompt_char_modified_display o $__fish_svn_prompt_char_modified_color o $__fish_svn_prompt_char_replaced_display o $__fish_svn_prompt_char_replaced_color o $__fish_svn_prompt_char_unversioned_external_display o $__fish_svn_prompt_char_unversioned_external_color o $__fish_svn_prompt_char_unversioned_display o $__fish_svn_prompt_char_unversioned_color o $__fish_svn_prompt_char_missing_display o $__fish_svn_prompt_char_missing_color o $__fish_svn_prompt_char_versioned_obstructed_display o $__fish_svn_prompt_char_versioned_obstructed_color o $__fish_svn_prompt_char_locked_display o $__fish_svn_prompt_char_locked_color o $__fish_svn_prompt_char_scheduled_display o $__fish_svn_prompt_char_scheduled_color o $__fish_svn_prompt_char_switched_display o $__fish_svn_prompt_char_switched_color o $__fish_svn_prompt_char_token_present_display o $__fish_svn_prompt_char_token_present_color o $__fish_svn_prompt_char_token_other_display o $__fish_svn_prompt_char_token_other_color o $__fish_svn_prompt_char_token_stolen_display o $__fish_svn_prompt_char_token_stolen_color o $__fish_svn_prompt_char_token_broken_display o $__fish_svn_prompt_char_token_broken_color See also fish_vcs_prompt, which will call all supported version control prompt functions, including git, Mercurial and Subversion. Example A simple prompt that displays svn info: function fish_prompt ... printf '%s %s$' $PWD (fish_svn_prompt) end fish_update_completions - Update completions using manual pages Synopsis fish_update_completions Description fish_update_completions parses manual pages installed on the system, and attempts to create completion files in the fish configuration di- rectory. This does not overwrite custom completions. There are no parameters for fish_update_completions. fish_vcs_prompt - output version control system information for use in a prompt Synopsis function fish_prompt echo -n (pwd)(fish_vcs_prompt) '$ ' end Description The fish_vcs_prompt function displays information about the current version control system (VCS) repository, if any. It calls out to VCS-specific functions. The currently supported systems are: o fish_git_prompt o fish_hg_prompt o fish_svn_prompt If a VCS isn't installed, the respective function does nothing. The svn prompt is disabled by default because it's slow on large svn repositories. To enable it, modify fish_vcs_prompt to uncomment it. See funced. For more information, see the documentation for each of the functions above. Example A simple prompt that displays all known VCS info: function fish_prompt ... set -g __fish_git_prompt_showupstream auto printf '%s %s$' $PWD (fish_vcs_prompt) end for - perform a set of commands multiple times. Synopsis for VARNAME in [VALUES...]; COMMANDS...; end Description for is a loop construct. It will perform the commands specified by COM- MANDS multiple times. On each iteration, the local variable specified by VARNAME is assigned a new value from VALUES. If VALUES is empty, COMMANDS will not be executed at all. The VARNAME is visible when the loop terminates and will contain the last value assigned to it. If VAR- NAME does not already exist it will be set in the local scope. For our purposes if the for block is inside a function there must be a local variable with the same name. If the for block is not nested inside a function then global and universal variables of the same name will be used if they exist. Example for i in foo bar baz; echo $i; end # would output: foo bar baz Notes The VARNAME was local to the for block in releases prior to 3.0.0. This means that if you did something like this: for var in a b c if break_from_loop break end end echo $var The last value assigned to var when the loop terminated would not be available outside the loop. What echo $var would write depended on what it was set to before the loop was run. Likely nothing. funced - edit a function interactively Synopsis funced [OPTIONS] NAME Description funced provides an interface to edit the definition of the function NAME. If the $VISUAL environment variable is set, it will be used as the pro- gram to edit the function. If $VISUAL is unset but $EDITOR is set, that will be used. Otherwise, a built-in editor will be used. Note that to enter a literal newline using the built-in editor you should press Alt+Enter. Pressing Enter signals that you are done editing the func- tion. This does not apply to an external editor like emacs or vim. If there is no function called NAME a new function will be created with the specified name o -e command or --editor command Open the function body inside the text editor given by the command (for example, -e vi). The special command fish will use the built-in editor (same as specifying -i). o -i or --interactive Force opening the function body in the built-in editor even if $VISUAL or $EDITOR is defined. o -s or --save Automatically save the function after successfully edit- ing it. funcsave - save the definition of a function to the user's autoload direc- tory Synopsis funcsave FUNCTION_NAME Description funcsave saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use. Note that because fish loads functions on-demand, saved functions will not function as event handlers until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your shell initialization file instead of using funcsave. function - create a function Synopsis function NAME [OPTIONS]; BODY; end Description function creates a new function NAME with the body BODY. A function is a list of commands that will be executed when the name of the function is given as a command. The following options are available: o -a NAMES or --argument-names NAMES assigns the value of successive command-line arguments to the names given in NAMES. o -d DESCRIPTION or --description=DESCRIPTION is a description of what the function does, suitable as a completion description. o -w WRAPPED_COMMAND or --wraps=WRAPPED_COMMAND causes the function to inherit completions from the given wrapped command. See the documen- tation for complete for more information. o -e or --on-event EVENT_NAME tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt. o -v or --on-variable VARIABLE_NAME tells fish to run this function when the variable VARIABLE_NAME changes value. o -j PGID or --on-job-exit PGID tells fish to run this function when the job with group ID PGID exits. Instead of PGID, the string 'caller' can be specified. This is only legal when in a command sub- stitution, and will result in the handler being triggered by the exit of the job which created this command substitution. o -p PID or --on-process-exit PID tells fish to run this function when the fish child process with process ID PID exits. Instead of a PID, for backward compatibility, "%self" can be specified as an alias for $fish_pid, and the function will be run when the current fish in- stance exits. o -s or --on-signal SIGSPEC tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP). o -S or --no-scope-shadowing allows the function to access the vari- ables of calling functions. Normally, any variables inside the func- tion that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function. It's important to note that this does not capture refer- enced variables or the scope at the time of function declaration! At this time, fish does not have any concept of closures, and variable lifetimes are never extended. In other words, by using --no-scope-shadowing the scope of the function each time it is run is shared with the scope it was called from rather than the scope it was defined in. o -V or --inherit-variable NAME snapshots the value of the variable NAME and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other lan- guages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the function notify example below for how this might be used. If the user enters any additional arguments after the function, they are inserted into the environment variable list $argv. If the --argu- ment-names option is provided, the arguments are also assigned to names specified in that option. By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the emit builtin. Fish generates the following named events: o fish_prompt, which is emitted whenever a new fish prompt is about to be displayed. o fish_command_not_found, which is emitted whenever a command lookup failed. o fish_preexec, which is emitted right before executing an interactive command. The commandline is passed as the first parameter. Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines. o fish_postexec, which is emitted right after executing an interactive command. The commandline is passed as the first parameter. Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines. o fish_exit is emitted right before fish exits. o fish_cancel, which is emitted when a commandline is cleared (used for terminal-shell integration). Example function ll ls -l $argv end will run the ls command, using the -l option, while passing on any ad- ditional files and switches to ls. function mkdir -d "Create a directory and set CWD" command mkdir $argv if test $status = 0 switch $argv[(count $argv)] case '-*' case '*' cd $argv[(count $argv)] return end end end This will run the mkdir command, and if it is successful, change the current working directory to the one just created. function notify set -l job (jobs -l -g) or begin; echo "There are no jobs" >&2; return 1; end function _notify_job_$job --on-job-exit $job --inherit-variable job echo -n \a # beep functions -e _notify_job_$job end end This will beep when the most recent job completes. Notes Note that events are only received from the current fish process as there is no way to send events from one fish process to another. functions - print or erase functions Synopsis functions [ -a | --all ] [ -n | --names ] functions [ -D | --details ] [ -v ] FUNCTION functions -c OLDNAME NEWNAME functions -d DESCRIPTION FUNCTION functions [ -e | -q ] FUNCTIONS... Description functions prints or erases functions. The following options are available: o -a or --all lists all functions, even those whose name starts with an underscore. o -c OLDNAME NEWNAME or --copy OLDNAME NEWNAME creates a new function named NEWNAME, using the definition of the OLDNAME function. o -d DESCRIPTION or --description=DESCRIPTION changes the description of this function. o -e or --erase causes the specified functions to be erased. This also means that it is prevented from autoloading. o -D or --details reports the path name where each function is defined or could be autoloaded, stdin if the function was defined interac- tively or on the command line or by reading stdin, - if the function was created via source, and n/a if the function isn't available. (Functions created via alias will return -, because alias uses source internally.) If the --verbose option is also specified then five lines are written: o the pathname as already described, o autoloaded, not-autoloaded or n/a, o the line number within the file or zero if not applicable, o scope-shadowing if the function shadows the vars in the calling function (the normal case if it wasn't defined with --no-scope-shadowing), else no-scope-shadowing, or n/a if the function isn't defined, o the function description minimally escaped so it is a single line or n/a if the function isn't defined. You should not assume that only five lines will be written since we may add additional information to the output in the future. o -n or --names lists the names of all defined functions. o -q or --query tests if the specified functions exist. o -v or --verbose will make some output more verbose. o -H or --handlers will show all event handlers. o -t or --handlers-type TYPE will show all event handlers matching the given type The default behavior of functions, when called with no arguments, is to print the names of all defined functions. Unless the -a option is given, no functions starting with underscores are not included in the output. If any non-option parameters are given, the definition of the specified functions are printed. Automatically loaded functions cannot be removed using functions -e. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions. Copying a function using -c copies only the body of the function, and does not attach any event notifications from the original function. Only one function's description can be changed in a single invocation of functions -d. The exit status of functions is the number of functions specified in the argument list that do not exist, which can be used in concert with the -q option. Examples functions -n # Displays a list of currently-defined functions functions -c foo bar # Copies the 'foo' function to a new function called 'bar' functions -e bar # Erases the function ``bar`` help - display fish documentation Synopsis help [SECTION] Description help displays the fish help documentation. If a SECTION is specified, the help for that command is shown. If the BROWSER environment variable is set, it will be used to display the documentation. Otherwise, fish will search for a suitable browser. If you prefer to use a different browser (other than as described above) for fish help, you can set the fish_help_browser variable. This variable may be set as a list, where the first element is the browser command and the rest are browser options. Note that most builtin commands display their help in the terminal when given the --help option. Example help fg shows the documentation for the fg builtin. history - Show and manipulate command history Synopsis history search [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] [ --max=n ] [ --null ] [ -R | --reverse ] [ "search string"... ] history delete [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] "search string"... history merge history save history clear history ( -h | --help ) Description history is used to search, delete, and otherwise manipulate the history of interactive commands. The following operations (sub-commands) are available: o search returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to ex- plicitly say history search if you wish to search for one of the sub- commands. The --contains search option will be used if you don't specify a different search option. Entries are ordered newest to old- est unless you use the --reverse flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout. o delete deletes history items. The --contains search option will be used if you don't specify a different search option. If you don't specify --exact a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the in- teractive delete behavior is a feature of the history function. The history builtin only supports --exact --case-sensitive deletion. o merge immediately incorporates history changes from other sessions. Ordinarily fish ignores history changes from sessions started after the current one. This command applies those changes immediately. o save immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for in- ternal use and should not normally need to be used by the user. o clear clears the history file. A prompt is displayed before the his- tory is erased asking you to confirm you really want to clear all history unless builtin history is used. The following options are available: These flags can appear before or immediately after one of the sub-com- mands listed above. o -C or --case-sensitive does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive. o -c or --contains searches or deletes items in the history that con- tain the specified text string. This is the default for the --search flag. This is not currently supported by the delete subcommand. o -e or --exact searches or deletes items in the history that exactly match the specified text string. This is the default for the delete subcommand. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the -C or --case-sensitive flag. o -p or --prefix searches or deletes items in the history that begin with the specified text string. This is not currently supported by the --delete flag. o -t or --show-time prepends each history entry with the date and time the entry was recorded. By default it uses the strftime format # %c%n. You can specify another format; e.g., --show-time="%Y-%m-%d %H:%M:%S " or --show-time="%a%I%p". The short option, -t, doesn't ac- cept a strftime format string; it only uses the default format. Any strftime format is allowed, including %s to get the raw UNIX seconds since the epoch. o -z or --null causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This al- lows the output to be processed by read -z to correctly handle multi- line history entries. o -<number> -n <number> or --max=<number> limits the matched history items to the first "n" matching entries. This is only valid for his- tory search. o -R or --reverse causes the history search results to be ordered old- est to newest. Which is the order used by most shells. The default is newest to oldest. o -h or --help display help for this command. Example history clear # Deletes all history items history search --contains "foo" # Outputs a list of all previous commands containing the string "foo". history delete --prefix "foo" # Interactively deletes commands which start with "foo" from the history. # You can select more than one entry by entering their IDs separated by a space. Customizing the name of the history file By default interactive commands are logged to $XDG_DATA_HOME/fish/fish_history (typically ~/.lo- cal/share/fish/fish_history). You can set the fish_history variable to another name for the current shell session. The default value (when the variable is unset) is fish which corresponds to $XDG_DATA_HOME/fish/fish_history. If you set it to e.g. fun, the history would be written to $XDG_DATA_HOME/fish/fun_his- tory. An empty string means history will not be stored at all. This is similar to the private session features in web browsers. You can change fish_history at any time (by using set -x fish_history "session_name") and it will take effect right away. If you set it to "default", it will use the default session name (which is "fish"). Other shells such as bash and zsh use a variable named HISTFILE for a similar purpose. Fish uses a different name to avoid conflicts and sig- nal that the behavior is different (session name instead of a file path). Also, if you set the var to anything other than fish or default it will inhibit importing the bash history. That's because the most common use case for this feature is to avoid leaking private or sensi- tive history when giving a presentation. Notes If you specify both --prefix and --contains the last flag seen is used. Note that for backwards compatibility each subcommand can also be spec- ified as a long option. For example, rather than history search you can type history --search. Those long options are deprecated and will be removed in a future release. if - conditionally execute a command Synopsis if CONDITION; COMMANDS_TRUE...; [else if CONDITION2; COMMANDS_TRUE2...;] [else; COMMANDS_FALSE...;] end Description if will execute the command CONDITION. If the condition's exit status is 0, the commands COMMANDS_TRUE will execute. If the exit status is not 0 and else is given, COMMANDS_FALSE will be executed. You can use and or or in the condition. See the second example below. The exit status of the last foreground command to exit can always be accessed using the $status variable. Example The following code will print foo.txt exists if the file foo.txt exists and is a regular file, otherwise it will print bar.txt exists if the file bar.txt exists and is a regular file, otherwise it will print foo.txt and bar.txt do not exist. if test -f foo.txt echo foo.txt exists else if test -f bar.txt echo bar.txt exists else echo foo.txt and bar.txt do not exist end The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable if test -f foo.txt and test -r foo.txt echo "foo.txt exists and is readable" end isatty - test if a file descriptor is a terminal Synopsis isatty [FILE DESCRIPTOR] Description isatty tests if a file descriptor is a terminal (as opposed to a file). The name is derived from the system call of the same name, which for historical reasons refers to a teletypewriter (TTY). FILE DESCRIPTOR may be either the number of a file descriptor, or one of the strings stdin, stdout, or stderr. If the specified file descriptor is a terminal device, the exit status of the command is zero. Otherwise, the exit status is non-zero. No mes- sages are printed to standard error. Examples From an interactive shell, the commands below exit with a return value of zero: isatty isatty stdout isatty 2 echo | isatty 1 And these will exit non-zero: echo | isatty isatty 9 isatty stdout > file isatty 2 2> file jobs - print currently running jobs Synopsis jobs [OPTIONS] [PID] Description jobs prints a list of the currently running jobs and their status. jobs accepts the following switches: o -c or --command prints the command name for each process in jobs. o -g or --group only prints the group ID of each job. o -l or --last prints only the last job to be started. o -p or --pid prints the process ID for each process in all jobs. o -q or --quiet prints no output for evaluation of jobs by exit status only. On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is ex- pressed as a percentage of full CPU activity. Note that on multiproces- sor systems, the total activity may be more than 100%. The exit status of the jobs builtin is 0 if there are running back- ground jobs and 1 otherwise. no output. Example jobs outputs a summary of the current jobs. math - Perform mathematics calculations Synopsis math [-sN | --scale=N] [--] EXPRESSION Description math is used to perform mathematical calculations. It supports all the usual operations such as addition, subtraction, etc. As well as func- tions like abs(), sqrt() and log2(). By default, the output is as a float with trailing zeroes trimmed. To get a fixed representation, the --scale option can be used, including --scale=0 for integer output. Keep in mind that parameter expansion takes before expressions are evaluated. This can be very useful in order to perform calculations in- volving shell variables or the output of command substitutions, but it also means that parenthesis (()) and the asterisk (*) glob character have to be escaped or quoted. x can also be used to denote multiplica- tion, but it needs to be followed by whitespace to distinguish it from hexadecimal numbers. math ignores whitespace between arguments and takes its input as multi- ple arguments (internally joined with a space), so math 2 +2 and math "2 + 2" work the same. math 2 2 is an error. The following options are available: o -sN or --scale=N sets the scale of the result. N must be an integer or the word "max" for the maximum scale. A scale of zero causes re- sults to be rounded down to the nearest integer. So 3/2 returns 1 rather than 2 which 1.5 would normally round to. This is for compati- bility with bc which was the basis for this command prior to fish 3.0.0. Scale values greater than zero causes the result to be rounded using the usual rules to the specified number of decimal places. Return Values If the expression is successfully evaluated and doesn't over/underflow or return NaN the return status is zero (success) else one. Syntax math knows some operators, constants, functions and can (obviously) read numbers. For numbers, . is always the radix character regardless of locale - 2.5, not 2,5. Scientific notation (10e5) is also available. Operators math knows the following operators: o + for addition and - for subtraction. o * or x for multiplication, / for division. (Note that * is the glob character and needs to be quoted or escaped, x needs to be followed by whitespace or it looks like 0x hexadecimal notation.) o ^ for exponentiation. o % for modulo. o ( and ) for grouping. (These need to be quoted or escaped because () denotes a command substitution.) They are all used in an infix manner - 5 + 2, not + 5 2. Constants math knows the following constants: o e - Euler's number. o pi - You know that one. Half of Tau. (Tau is not implemented) Use them without a leading $ - pi - 3 should be about 0. Functions math supports the following functions: o abs o acos o asin o atan o atan2 o ceil o cos o cosh o exp - the base-e exponential function o fac - factorial o floor o ln o log or log10 - the base-10 logarithm o ncr o npr o pow(x,y) returns x to the y (and can be written as x ^ y) o round - rounds to the nearest integer, away from 0 o sin o sinh o sqrt o tan o tanh All of the trigonometric functions use radians. Examples math 1+1 outputs 2. math $status - 128 outputs the numerical exit status of the last com- mand minus 128. math 10 / 6 outputs 1.666667. math -s0 10.0 / 6.0 outputs 1. math -s3 10 / 6 outputs 1.666. math "sin(pi)" outputs 0. math 5 \* 2 or math "5 * 2" or math 5 "*" 2 all output 10. math 0xFF outputs 255, math 0 x 3 outputs 0 (because it computes 0 mul- tiplied by 3). Compatibility notes Fish 1.x and 2.x releases relied on the bc command for handling math expressions. Starting with fish 3.0.0 fish uses the tinyexpr library and evaluates the expression without the involvement of any external commands. You don't need to use -- before the expression even if it begins with a minus sign which might otherwise be interpreted as an invalid option. If you do insert -- before the expression it will cause option scanning to stop just like for every other command and it won't be part of the expression. nextd - move forward through directory history Synopsis nextd [ -l | --list ] [POS] Description nextd moves forwards POS positions in the history of visited directo- ries; if the end of the history has been hit, a warning is printed. If the -l or --list flag is specified, the current directory history is also displayed. Note that the cd command limits directory history to the 25 most re- cently visited directories. The history is stored in the $dirprev and $dirnext variables which this command manipulates. You may be interested in the cdh command which provides a more intu- itive way to navigate to recently visited directories. Example cd /usr/src # Working directory is now /usr/src cd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell prevd # Working directory is now /usr/src nextd # Working directory is now /usr/src/fish-shell not - negate the exit status of a job Synopsis not COMMAND [OPTIONS...] Description not negates the exit status of another command. If the exit status is zero, not returns 1. Otherwise, not returns 0. Example The following code reports an error and exits if no file named spoon can be found. if not test -f spoon echo There is no spoon exit 1 end open - open file in its default application Synopsis open FILES... Description open opens a file in its default application, using the appropriate tool for the operating system. On GNU/Linux, this requires the common but optional xdg-open utility, from the xdg-utils package. Note that this function will not be used if a command by this name ex- ists (which is the case on macOS or Haiku). Example open *.txt opens all the text files in the current directory using your system's default text editor. or - conditionally execute a command Synopsis COMMAND1; or COMMAND2 Description or is used to execute a command if the previous command was not suc- cessful (returned a status of something other than 0). or statements may be used as part of the condition in an and or while block. or does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the $status variable. Example The following code runs the make command to build a program. If the build succeeds, the program is installed. If either step fails, make clean is run, which removes the files created by the build process. make; and make install; or make clean See Also o and command popd - move through directory stack Synopsis popd Description popd removes the top directory from the directory stack and changes the working directory to the new top directory. Use pushd to add directo- ries to the stack or dirs to print it. You may be interested in the cdh command which provides a more intu- itive way to navigate to recently visited directories. Example pushd /usr/src # Working directory is now /usr/src # Directory stack contains /usr/src pushd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell # Directory stack contains /usr/src /usr/src/fish-shell popd # Working directory is now /usr/src # Directory stack contains /usr/src prevd - move backward through directory history Synopsis prevd [ -l | --list ] [POS] Description prevd moves backwards POS positions in the history of visited directo- ries; if the beginning of the history has been hit, a warning is printed. If the -l or --list flag is specified, the current history is also dis- played. Note that the cd command limits directory history to the 25 most re- cently visited directories. The history is stored in the $dirprev and $dirnext variables which this command manipulates. You may be interested in the cdh command which provides a more intu- itive way to navigate to recently visited directories. Example cd /usr/src # Working directory is now /usr/src cd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell prevd # Working directory is now /usr/src nextd # Working directory is now /usr/src/fish-shell printf - display text according to a format string Synopsis printf FORMAT [ARGUMENT ...] Description printf formats the string FORMAT with ARGUMENT, and displays the re- sult. The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Speci- fiers are detailed below, and are taken from the C library function printf(3). Unlike echo, printf does not append a new line unless it is specified as part of the string. Valid format specifiers are: o %d: Argument will be used as decimal integer (signed or unsigned) o %i: Argument will be used as a signed integer o %o: An octal unsigned integer o %u: An unsigned decimal integer o %x or %X: An unsigned hexadecimal integer o %f, %g or %G: A floating-point number o %e or %E: A floating-point number in scientific (XXXeYY) notation o %s: A string o %b: As a string, interpreting backslash escapes, except that octal escapes are of the form 0 or 0ooo. %% signifies a literal "%". Note that conversion may fail, e.g. "102.234" will not losslessly con- vert to an integer, causing printf to print an error. printf also knows a number of backslash escapes: - \" double quote - \\ backslash - \a alert (bell) - \b backspace - \c produce no further out- put - \e escape - \f form feed - \n new line - \r carriage return - \t horizontal tab - \v vertical tab - \ooo octal number (ooo is 1 to 3 digits) - \xhh hexadecimal number (hhh is 1 to 2 digits) - \uhhhh 16-bit Unicode character (hhhh is 4 digits) - \Uhhhhhhhh 32-bit Unicode character (hhhhhhhh is 8 digits) The format argument is re-used as many times as necessary to convert all of the given arguments. If a format specifier is not appropriate for the given argument, an error is printed. For example, printf '%d' "102.234" produces an error, as "102.234" cannot be formatted as an in- teger. This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try command printf. Example printf '%s\\t%s\\n' flounder fish Will print "flounder fish" (separated with a tab character), fol- lowed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character. printf '%s: %d' "Number of bananas in my pocket" 42 Will print "Number of bananas in my pocket: 42", _without_ a newline. prompt_pwd - Print pwd suitable for prompt Synopsis function fish_prompt echo -n (prompt_pwd) '$ ' end Description prompt_pwd is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one char- acter. To change the number of characters per path component, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. Examples >_ cd ~/ >_ echo $PWD /home/alfa >_ prompt_pwd ~ >_ cd /tmp/banana/sausage/with/mustard >_ prompt_pwd /t/b/s/w/mustard >_ set -g fish_prompt_pwd_dir_length 3 >_ prompt_pwd /tmp/ban/sau/wit/mustard psub - perform process substitution Synopsis COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX]) Description Some shells (e.g., ksh, bash) feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling pro- gram. psub combined with a regular command substitution provides the same functionality. The following options are available: o -f or --file will cause psub to use a regular file instead of a named pipe to communicate with the calling process. This will cause psub to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. This is the default. o -F or --fifo will cause psub to use a named pipe rather than a file. You should only use this if the command produces no more than 8 KiB of output. The limit on the amount of data a FIFO can buffer varies with the OS but is typically 8 KiB, 16 KiB or 64 KiB. If you use this option and the command on the left of the psub pipeline produces more output a deadlock is likely to occur. o -s or --suffix will append SUFFIX to the filename. Example diff (sort a.txt | psub) (sort b.txt | psub) # shows the difference between the sorted versions of files ``a.txt`` and ``b.txt``. source-highlight -f esc (cpp main.c | psub -f -s .c) # highlights ``main.c`` after preprocessing as a C source. pushd - push directory to directory stack Synopsis pushd [DIRECTORY] Description The pushd function adds DIRECTORY to the top of the directory stack and makes it the current working directory. popd will pop it off and return to the original directory. Without arguments, it exchanges the top two directories in the stack. pushd +NUMBER rotates the stack counter-clockwise i.e. from bottom to top pushd -NUMBER rotates clockwise i.e. top to bottom. See also dirs to print the stack and dirs -c to clear it. You may be interested in the cdh command which provides a more intu- itive way to navigate to recently visited directories. Example pushd /usr/src # Working directory is now /usr/src # Directory stack contains /usr/src pushd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell # Directory stack contains /usr/src /usr/src/fish-shell pushd /tmp/ # Working directory is now /tmp # Directory stack contains /tmp /usr/src /usr/src/fish-shell pushd +1 # Working directory is now /usr/src # Directory stack contains /usr/src /usr/src/fish-shell /tmp popd # Working directory is now /usr/src/fish-shell # Directory stack contains /usr/src/fish-shell /tmp pwd - output the current working directory Synopsis pwd Description pwd outputs (prints) the current working directory. The following options are available: o -L, Output the logical working directory, without resolving symlinks (default behavior). o -P, Output the physical working directory, with symlinks resolved. random - generate random number Synopsis random random SEED random START END random START STEP END random choice [ITEMS...] Description RANDOM generates a pseudo-random integer from a uniform distribution. The range (inclusive) is dependent on the arguments passed. No argu- ments indicate a range of [0; 32767]. If one argument is specified, the internal engine will be seeded with the argument for future invoca- tions of RANDOM and no output will be produced. Two arguments indicate a range of [START; END]. Three arguments indicate a range of [START; END] with a spacing of STEP between possible outputs. RANDOM choice will select one random item from the succeeding arguments. Note that seeding the engine will NOT give the same result across dif- ferent systems. You should not consider RANDOM cryptographically secure, or even sta- tistically accurate. Example The following code will count down from a random even number between 10 and 20 to 1: for i in (seq (random 10 2 20) -1 1) echo $i end And this will open a random picture from any of the subdirectories: open (random choice **jpg) read - read line of input into variables Synopsis read [OPTIONS] [VARIABLE ...] Description read reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, read reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given. Unlike other shells, there is no default variable (such as REPLY) for storing the result - instead, it is printed on standard output. The following options are available: o -c CMD or --command=CMD sets the initial string in the interactive mode command buffer to CMD. o -d DELIMITER or --delimiter=DELIMITER splits on DELIMITER. DELIMITER will be used as an entire string to split on, not a set of charac- ters. o -g or --global makes the variables global. o -s or --silent masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information. o -l or --local makes the variables local. o -n NCHARS or --nchars=NCHARS makes read return after reading NCHARS characters or the end of the line, whichever comes first. o -p PROMPT_CMD or --prompt=PROMPT_CMD uses the output of the shell command PROMPT_CMD as the prompt for the interactive mode. The de- fault prompt command is set_color green; echo read; set_color normal; echo "_ " o -P PROMPT_STR or --prompt-str=PROMPT_STR uses the string as the prompt for the interactive mode. It is equivalent to echo PROMPT_STR and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically es- caped before being passed to the echo command. o -R RIGHT_PROMPT_CMD or --right-prompt=RIGHT_PROMPT_CMD uses the out- put of the shell command RIGHT_PROMPT_CMD as the right prompt for the interactive mode. There is no default right prompt command. o -S or --shell enables syntax highlighting, tab completions and com- mand termination suitable for entering shellscript code in the inter- active mode. NOTE: Prior to fish 3.0, the short opt for --shell was -s, but it has been changed for compatibility with bash's -s short opt for --silent. o -t -or --tokenize causes read to split the input into variables by the shell's tokenization rules. This means it will honor quotes and escaping. This option is of course incompatible with other options to control splitting like --delimiter and does not honor $IFS (like fish's tokenizer). It saves the tokens in the manner they'd be passed to commands on the commandline, so e.g. a\ b is stored as a b. Note that currently it leaves command substitutions intact along with the parentheses. o -u or --unexport prevents the variables from being exported to child processes (default behaviour). o -U or --universal causes the specified shell variable to be made uni- versal. o -x or --export exports the variables to child processes. o -a or --list stores the result as a list in a single variable. This option is also available as --array for backwards compatibility. o -z or --null marks the end of the line with the NUL character, in- stead of newline. This also disables interactive mode. o -L or --line reads each line into successive variables, and stops af- ter each variable has been filled. This cannot be combined with the --delimiter option. Without the --line option, read reads a single line of input from stan- dard input, breaks it into tokens, and then assigns one token to each variable specified in VARIABLES. If there are more tokens than vari- ables, the complete remainder is assigned to the last variable. If no option to determine how to split like --delimiter, --line or --tokenize is given, the variable IFS is used as a list of characters to split on. Relying on the use of IFS is deprecated and this behaviour will be removed in future versions. The default value of IFS contains space, tab and newline characters. As a special case, if IFS is set to the empty string, each character of the input is considered a separate token. With the --line option, read reads a line of input from standard input into each provided variable, stopping when each variable has been filled. The line is not tokenized. If no variable names are provided, read enters a special case that sim- ply provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read data that should be provided via a command line ar- gument from the console instead of hardcoding it in the command itself, allowing the command to both be reused as-is in various contexts with different input values and preventing possibly sensitive text from be- ing included in the shell history: mysql -uuser -p(read) When running in this mode, read does not split the input in any way and text is redirected to standard output without any further processing or manipulation. If -a or --array is provided, only one variable name is allowed and the tokens are stored as a list in this variable. See the documentation for set for more details on the scoping rules for variables. When read reaches the end-of-file (EOF) instead of the terminator, the exit status is set to 1. Otherwise, it is set to 0. In order to protect the shell from consuming too many system resources, read will only consume a maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then VARIABLE is set to empty and the exit status is set to 122. This limit can be altered with the fish_read_limit variable. If set to 0 (zero), the limit is removed. Using another read history file The read command supported the -m and --mode-name flags in fish ver- sions prior to 2.7.0 to specify an alternative read history file. Those flags are now deprecated and ignored. Instead, set the fish_history variable to specify a history session ID. That will affect both the read history file and the fish command history file. You can set it to an empty string to specify that no history should be read or written. This is useful for presentations where you do not want possibly private or sensitive history to be exposed to the audience but do want history relevant to the presentation to be available. Example The following code stores the value 'hello' in the shell variable $foo. echo hello|read foo # This is a neat way to handle command output by-line: printf '%s\n' line1 line2 line3 line4 | while read -l foo echo "This is another line: $foo" end # Delimiters given via "-d" are taken as one string echo a==b==c | read -d == -l a b c echo $a # a echo $b # b echo $c # c # --tokenize honors quotes and escaping like the shell's argument passing: echo 'a\ b' | read -t first second echo $first # outputs "a b", $second is empty echo 'a"foo bar"b (command echo wurst)*" "{a,b}' | read -lt -l a b c echo $a # outputs 'afoo bar' (without the quotes) echo $b # outputs '(command echo wurst)* {a,b}' (without the quotes) echo $c # nothing realpath - Convert a path to an absolute path without symlinks Synopsis realpath PATH Description realpath resolves a path to its absolute path. fish provides a realpath builtin as a fallback for systems where there is no realpath command. fish's implementation always resolves its first argument, and does not support any options. If the operation fails, an error will be reported. return - stop the current inner function Synopsis function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end Description return halts a currently running function. The exit status is set to STATUS if it is given. It is usually added inside of a conditional block such as an if state- ment or a switch statement to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function. Example The following code is an implementation of the false command as a fish function function false return 1 end set - display and change shell variables. Synopsis set [SCOPE_OPTIONS] set [OPTIONS] VARIABLE_NAME VALUES... set [OPTIONS] VARIABLE_NAME[INDICES]... VALUES... set ( -q | --query ) [SCOPE_OPTIONS] VARIABLE_NAMES... set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]... set ( -S | --show ) [VARIABLE_NAME]... Description set manipulates shell variables. If set is called with no arguments, the names and values of all shell variables are printed in sorted order. If some of the scope or export flags have been given, only the variables matching the specified scope are printed. With both variable names and values provided, set assigns the variable VARIABLE_NAME the values VALUES.... The following options control variable scope: o -a or --append causes the values to be appended to the current set of values for the variable. This can be used with --prepend to both ap- pend and prepend at the same time. This cannot be used when assigning to a variable slice. o -p or --prepend causes the values to be prepended to the current set of values for the variable. This can be used with --append to both append and prepend at the same time. This cannot be used when assign- ing to a variable slice. o -l or --local forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local o -g or --global causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they be- long to ends o -U or --universal causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current user's fish instances on the current computer, and will be preserved across restarts of the shell. o -x or --export causes the specified shell variable to be exported to child processes (making it an "environment variable") o -u or --unexport causes the specified shell variable to NOT be ex- ported to child processes o --path causes the specified variable to be treated as a path vari- able, meaning it will automatically be split on colons, and joined using colons when quoted (echo "$PATH") or exported. o --unpath causes the specified variable to not be treated as a path variable. Variables with a name ending in "PATH" are automatically path variables, so this can be used to treat such a variable nor- mally. The following options are available: o -e or --erase causes the specified shell variable to be erased o -q or --query test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined. o -n or --names List only the names of all defined variables, not their value. The names are guaranteed to be sorted. o -S or --show Shows information about the given variables. If no vari- able names are given then all variables are shown in sorted order. No other flags can be used with this option. The information shown in- cludes whether or not it is set in each of the local, global, and universal scopes. If it is set in one of those scopes whether or not it is exported is reported. The individual elements are also shown along with the length of each element. o -L or --long do not abbreviate long values when printing set vari- ables If a variable is set to more than one value, the variable will be a list with the specified elements. If a variable is set to zero ele- ments, it will become a list with zero elements. If the variable name is one or more list elements, such as PATH[1 3 7], only those list elements specified will be changed. If you specify a negative index when expanding or assigning to a list variable, the in- dex will be calculated from the end of the list. For example, the index -1 means the last index of a list. The scoping rules when creating or updating a variable are: o Variables may be explicitly set to universal, global or local. Vari- ables with the same name in different scopes will not be changed. o If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the previous variable scope is used. o If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing function. Note that this is different from using the -l or --local flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global. The exporting rules when creating or updating a variable are identical to the scoping rules for variables: o Variables may be explicitly set to either exported or not exported. When an exported variable goes out of scope, it is unexported. o 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. o If a variable is not explicitly set to be either exported or unex- ported and has never before been defined, the variable will not be exported. In query mode, the scope to be examined can be specified. In erase mode, if variable indices are specified, only the specified slices of the list variable will be erased. set requires all options to come before any other arguments. For exam- ple, set flags -l will have the effect of setting the value of the variable flags to '-l', not making the variable local. In assignment mode, set does not modify the exit status. This allows simultaneous capture of the output and exit status of a subcommand, e.g. if set output (command). In query mode, the exit status is the number of variables that were not found. In erase mode, set exits with a zero exit status in case of success, with a non-zero exit status if the commandline was invalid, if the variable was write-protected or if the variable did not exist. Examples # Prints all global, exported variables. set -xg # Sets the value of the variable $foo to be 'hi'. set foo hi # Appends the value "there" to the variable $foo. set -a foo there # Does the same thing as the previous two commands the way it would be done pre-fish 3.0. set foo hi set foo $foo there # Removes the variable $smurf set -e smurf # Changes the fourth element of the $PATH list to ~/bin set PATH[4] ~/bin # Outputs the path to Python if ``type -p`` returns true. if set python_path (type -p python) echo "Python is at $python_path" end # Like other shells, fish 3.1 supports this syntax for passing a variable to just one command: # Run fish with a temporary home directory. HOME=(mktemp -d) fish # Which is essentially the same as: begin; set -lx HOME (mktemp -d); fish; end Notes Fish versions prior to 3.0 supported the syntax set PATH[1] PATH[4] /bin /sbin, which worked like set PATH[1 4] /bin /sbin. This syntax was not widely used, and was ambiguous and inconsistent. set_color - set the terminal color Synopsis set_color [OPTIONS] VALUE Description set_color is used to control the color and styling of text in the ter- minal. VALUE describes that styling. It's a reserved color name like red or a RGB color value given as 3 or 6 hexadecimal digits ("F27" or "FF2277"). A special keyword normal resets text formatting to terminal defaults. Valid colors include: o black, red, green, yellow, blue, magenta, cyan, white o brblack, brred, brgreen, bryellow, brblue, brmagenta, brcyan, br- white The br- (as in 'bright') forms are full-brightness variants of the 8 standard-brightness colors on many terminals. brblack has higher brightness than black - towards gray. An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. fish will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., set_color 2BC is the same as set_color 22BBCC. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support set_color has for it) the actual color may be approxi- mated by a nearby matching reserved color name or set_color may not have an effect on color. A second color may be given as a desired fallback color. e.g. set_color 124212 brblue will instruct set_color to use brblue if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color. The following options are available: o -b, --background COLOR sets the background color. o -c, --print-colors prints a list of the 16 named colors. o -o, --bold sets bold mode. o -d, --dim sets dim mode. o -i, --italics sets italics mode. o -r, --reverse sets reverse mode. o -u, --underline sets underlined mode. Using the normal keyword will reset foreground, background, and all formatting back to default. Notes 1. Using the normal keyword will reset both background and foreground colors to whatever is the default for the terminal. 2. Setting the background color only affects subsequently written char- acters. Fish provides no way to set the background color for the en- tire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. Look for a config option. 3. Some terminals use the --bold escape sequence to switch to a brighter color set rather than increasing the weight of text. 4. set_color works by printing sequences of characters to stdout. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit status of isatty stdout before using set_color can be useful to de- cide not to colorize output in a script. Examples set_color red; echo "Roses are red" set_color blue; echo "Violets are blue" set_color 62A; echo "Eggplants are dark purple" set_color normal; echo "Normal is nice" # Resets the background too Terminal Capability Detection Fish uses some heuristics to determine what colors a terminal supports to avoid sending sequences that it won't understand. In particular it will: o Enable 256 colors if $TERM contains "xterm", except for known excep- tions (like MacOS 10.6 Terminal.app) o Enable 24-bit ("true-color") even if the $TERM entry only reports 256 colors. This includes modern xterm, VTE-based terminals like Gnome Terminal, Konsole and iTerm2. o Detect support for italics, dim, reverse and other modes. If terminfo reports 256 color support for a terminal, 256 color support will always be enabled. To force true-color support on or off, set $fish_term24bit to "1" for on and 0 for off - set -g fish_term24bit 1. To debug color palette problems, tput colors may be useful to see the number of colors in terminfo for a terminal. Fish launched as fish -d2 will include diagnostic messages that indicate the color support mode in use. The set_color command uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and lack color information for terminals that support it. Fish assumes that all terminals can use the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code) escape sequences if the terminfo definition indicates a color below 16 is not supported. source - evaluate contents of file. Synopsis source FILENAME [ARGUMENTS...] somecommand | source Description source evaluates the commands of the specified file in the current shell as a new block of code. This is different from starting a new process to perform the commands (i.e. fish < FILENAME) since the com- mands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional argu- ments are specified after the file name, they will be inserted into the $argv variable. The $argv variable will not include the name of the sourced file. fish will search the working directory to resolve relative paths but will not search $PATH. If no file is specified and stdin is not the terminal, or if the file name '-' is used, stdin will be read. The exit status of source is the exit status of the last job to exe- cute. If something goes wrong while opening or reading the file, source exits with a non-zero status. . (a single period) is an alias for the source command. The use of . is deprecated in favour of source, and . will be removed in a future ver- sion of fish. source creates a new local scope; set --local within a sourced block will not affect variables in the enclosing scope. Example source ~/.config/fish/config.fish # Causes fish to re-read its initialization file. Caveats In fish versions prior to 2.3.0, the $argv variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise, it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh. status - query fish runtime information Synopsis status status is-login status is-interactive status is-block status is-breakpoint status is-command-substitution status is-no-job-control status is-full-job-control status is-interactive-job-control status current-command status filename status fish-path status function status line-number status stack-trace status job-control CONTROL-TYPE status features status test-feature FEATURE Description With no arguments, status displays a summary of the current login and job control status of the shell. The following operations (sub-commands) are available: o is-command-substitution returns 0 if fish is currently executing a command substitution. Also -c or --is-command-substitution. o is-block returns 0 if fish is currently executing a block of code. Also -b or --is-block. o is-breakpoint returns 0 if fish is currently showing a prompt in the context of a breakpoint command. See also the fish_breakpoint_prompt function. o is-interactive returns 0 if fish is interactive - that is, connected to a keyboard. Also -i or --is-interactive. o is-login returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH. Also -l or --is-lo- gin. o is-full-job-control returns 0 if full job control is enabled. Also --is-full-job-control (no short flag). o is-interactive-job-control returns 0 if interactive job control is enabled. Also, --is-interactive-job-control (no short flag). o is-no-job-control returns 0 if no job control is enabled. Also --is-no-job-control (no short flag). o current-command prints the name of the currently-running function or command, like the deprecated _ variable. o filename prints the filename of the currently running script. Also current-filename, -f or --current-filename. o fish-path prints the absolute path to the currently executing in- stance of fish. o function prints the name of the currently called function if able, when missing displays "Not a function" (or equivalent translated string). Also current-function, -u or --current-function. o line-number prints the line number of the currently running script. Also current-line-number, -n or --current-line-number. o stack-trace prints a stack trace of all function calls on the call stack. Also print-stack-trace, -t or --print-stack-trace. o job-control CONTROL-TYPE sets the job control type, which can be none, full, or interactive. Also -j CONTROL-TYPE or --job-con- trol=CONTROL-TYPE. o features lists all available feature flags. o test-feature FEATURE returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized. Notes For backwards compatibility each subcommand can also be specified as a long or short option. For example, rather than status is-login you can type status --is-login. The flag forms are deprecated and may be re- moved in a future release (but not before fish 3.0). You can only specify one subcommand per invocation even if you use the flag form of the subcommand. string - manipulate strings Synopsis string collect [(-N | --no-trim-newlines)] [STRING...] string escape [(-n | --no-quoted)] [--style=xxx] [STRING...] string join [(-q | --quiet)] SEP [STRING...] string join0 [(-q | --quiet)] [STRING...] string length [(-q | --quiet)] [STRING...] string lower [(-q | --quiet)] [STRING...] string match [(-a | --all)] [(-e | --entire)] [(-i | --ignore-case)] [(-r | --regex)] [(-n | --index)] [(-q | --quiet)] [(-v | --invert)] PATTERN [STRING...] string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [(-N | --no-newline)] [(-q | --quiet)] [STRING...] string replace [(-a | --all)] [(-f | --filter)] [(-i | --ignore-case)] [(-r | --regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...] string split [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] SEP [STRING...] string split0 [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] [STRING...] string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)] [STRING...] string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...] string unescape [--style=xxx] [STRING...] string upper [(-q | --quiet)] [STRING...] Description string performs operations on strings. STRING arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one STRING per line. It is an error to supply STRING arguments on the command line and on standard input. Arguments beginning with - are normally interpreted as switches; -- causes the following arguments not to be treated as switches even if they begin with -. Switches and required arguments are recognized only on the command line. Most subcommands accept a -q or --quiet switch, which suppresses the usual output but exits with the documented status. The following subcommands are available. collect subcommand string collect [(-N | --no-trim-newlines)] [STRING...] string collect collects its input into a single output argument, with- out splitting the output when used in a command substitution. This is useful when trying to collect multiline output from another command into a variable. Exit status: 0 if any output argument is non-empty, or 1 otherwise. If invoked with multiple arguments instead of input, string collect preserves each argument separately, where the number of output argu- ments is equal to the number of arguments given to string collect. Any trailing newlines on the input are trimmed, just as with "$(cmd)" substitution in sh. --no-trim-newlines can be used to disable this be- havior, which may be useful when running a command such as set contents (cat filename | string collect -N). Examples >_ echo \"(echo one\ntwo\nthree | string collect)\" "one two three " >_ echo \"(echo one\ntwo\nthree | string collect -N)\" "one two three" escape and unescape subcommands string escape [(-n | --no-quoted)] [--style=xxx] [STRING...] string unescape [--style=xxx] [STRING...] string escape escapes each STRING in one of three ways. The first is --style=script. This is the default. It alters the string such that it can be passed back to eval to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If -n or --no-quoted is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise. --style=var ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded. --style=url ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded. --style=regex escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded. string unescape performs the inverse of the string escape command. If the string to be unescaped is not properly formatted it is ignored. For example, doing string unescape --style=var (string escape --style=var $str) will return the original string. There is no support for unescap- ing --style=regex. Examples >_ echo \\x07 | string escape cg >_ string escape --style=var 'a1 b2'\\u6161 a1_20b2__c_E6_85_A1 join and join0 subcommands string join [(-q | --quiet)] SEP [STRING...] string join0 [(-q | --quiet)] [STRING...] string join joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise. string join0 joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as sort -z. Exit status: 0 if at least one join was performed, or 1 otherwise. Examples >_ seq 3 | string join ... 1...2...3 length subcommand string length [(-q | --quiet)] [STRING...] string length reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 other- wise. Examples >_ string length 'hello, world' 12 >_ set str foo >_ string length -q $str; echo $status 0 # Equivalent to test -n $str lower subcommand string lower [(-q | --quiet)] [STRING...] string lower converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the -q flag you can readily test whether a string is already lowercase. match subcommand string match [(-a | --all)] [(-e | --entire)] [(-i | --ignore-case)] [(-r | --regex)] [(-n | --index)] [(-q | --quiet)] [(-v | --invert)] PATTERN [STRING...] string match tests each STRING against PATTERN and prints matching sub- strings. Only the first match for each STRING is reported unless -a or --all is given, in which case all matches are reported. If you specify the -e or --entire then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to grep without the -o flag). You can, obviously, achieve the same re- sult by prepending and appending * or .* depending on whether or not you have specified the --regex flag. The --entire flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the string match clearer. Without --entire and --regex, a PATTERN will need to match the entire STRING before it will be re- ported. Matching can be made case-insensitive with --ignore-case or -i. If --index or -n is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING. If --regex or -r is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the STRING will be reported, unless --entire is given. If --invert or -v is used the selected lines will be only those which do not match the given glob pattern or regular expression. Exit status: 0 if at least one match was found, or 1 otherwise. Match Glob Examples >_ string match '?' a a >_ string match 'a*b' axxb axxb >_ string match -i 'a??B' Axxb Axxb >_ echo 'ok?' | string match '*\\?' ok? # Note that only the second STRING will match here. >_ string match 'foo' 'foo1' 'foo' 'foo2' foo >_ string match -e 'foo' 'foo1' 'foo' 'foo2' foo1 foo foo2 >_ string match 'foo?' 'foo1' 'foo' 'foo2' foo1 foo foo2 Match Regex Examples >_ string match -r 'cat|dog|fish' 'nice dog' dog >_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4) dog1 dog2 cat3 dog3 cat4 dog4 >_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56 2:34:56 2 34 56 >_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur papa pa murmur mur >_ string match -r -a -n at ratatat 2 2 4 2 6 2 >_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;' 0xBadC0de repeat subcommand string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [(-N | --no-newline)] [(-q | --quiet)] [STRING...] string repeat repeats the STRING -n or --count times. The -m or --max option will limit the number of outputted char (excluding the newline). This option can be used by itself or in conjunction with --count. If both --count and --max are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both --count and --max will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If -N or --no-newline is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise. Examples Repeat Examples >_ string repeat -n 2 'foo ' foo foo >_ echo foo | string repeat -n 2 foofoo >_ string repeat -n 2 -m 5 'foo' foofo >_ string repeat -m 5 'foo' foofo replace subcommand string replace [(-a | --all)] [(-f | --filter)] [(-i | --ignore-case)] [(-r | --regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...] string replace is similar to string match but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched. If -r or --regex is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape se- quences like \t as well as references to capturing groups by number or name as $n or ${n}. If you specify the -f or --filter flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: a_cmd | string match pattern | string replace pattern new_pattern. You can instead just write a_cmd | string replace --filter pattern new_pattern. Exit status: 0 if at least one replacement was performed, or 1 other- wise. Replace Literal Examples >_ string replace is was 'blue is my favorite' blue was my favorite >_ string replace 3rd last 1st 2nd 3rd 1st 2nd last >_ string replace -a ' ' _ 'spaces to underscores' spaces_to_underscores Replace Regex Examples >_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x' 0 3.14 5 >_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right' right left $ >_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here' put a here split and split0 subcommands string split [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] SEP [STRING...] string split0 [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] [STRING...] string split splits each STRING on the separator SEP, which can be an empty string. If -m or --max is specified, at most MAX splits are done on each STRING. If -r or --right is given, splitting is performed right-to-left. This is useful in combination with -m or --max. With -n or --no-empty, empty results are excluded from consideration (e.g. hello\n\nworld would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise. See also read --delimiter. string split0 splits each STRING on the zero byte (NUL). Options are the same as string split except that no separator is given. split0 has the important property that its output is not further split when used in a command substitution, allowing for the command substitu- tion to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as find -print0 or sort -z. See split0 examples below. Examples >_ string split . example.com example com >_ string split -r -m1 / /usr/local/bin/fish /usr/local/bin fish >_ string split '' abc a b c NUL Delimited Examples >_ # Count files in a directory, without being confused by newlines. >_ count (find . -print0 | string split0) 42 >_ # Sort a list of elements which may contain newlines >_ set foo beta alpha\\ngamma >_ set foo (string join0 $foo | sort -z | string split0) >_ string escape $foo[1] alpha\\ngamma sub subcommand string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)] [STRING...] string sub prints a substring of each string argument. The start of the substring can be specified with -s or --start followed by a 1-based in- dex value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be speci- fied with -l or --length. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise. Examples >_ string sub --length 2 abcde ab >_ string sub -s 2 -l 2 abcde bc >_ string sub --start=-2 abcde de trim subcommand string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...] string trim removes leading and trailing whitespace from each STRING. If -l or --left is given, only leading whitespace is removed. If -r or --right is given, only trailing whitespace is trimmed. The -c or --chars switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise. Examples >_ string trim ' abc ' abc >_ string trim --right --chars=yz xyzzy zany x zan upper subcommand string upper [(-q | --quiet)] [STRING...] string upper converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the -q flag you can readily test whether a string is already uppercase. Regular Expressions Both the match and replace subcommand support regular expressions when used with the -r or --regex option. The dialect is that of PCRE2. In general, special characters are special by default, so a+ matches one or more "a"s, while a\+ matches an "a" and then a "+". (a+) matches one or more "a"s in a capturing group ((?:XXXX) denotes a non-capturing group). For the replacement parameter of replace, $n refers to the n-th group of the match. In the match parameter, \n (e.g. \1) refers back to groups. Some features include repetitions: o * refers to 0 or more repetitions of the previous expression o + 1 or more o ? 0 or 1. o {n} to exactly n (where n is a number) o {n,m} at least n, no more than m. o {n,} n or more Character classes, some of the more important: o . any character except newline o \d a decimal digit and \D, not a decimal digit o \s whitespace and \S, not whitespace o \w a "word" character and \W, a "non-word" character o [...] (where "..." is some characters) is a character set o [^...] is the inverse of the given character set o [x-y] is the range of characters from x-y o [[:xxx:]] is a named character set o [[:^xxx:]] is the inverse of a named character set o [[:alnum:]] : "alphanumeric" o [[:alpha:]] : "alphabetic" o [[:ascii:]] : "0-127" o [[:blank:]] : "space or tab" o [[:cntrl:]] : "control character" o [[:digit:]] : "decimal digit" o [[:graph:]] : "printing, excluding space" o [[:lower:]] : "lower case letter" o [[:print:]] : "printing, including space" o [[:punct:]] : "printing, excluding alphanumeric" o [[:space:]] : "white space" o [[:upper:]] : "upper case letter" o [[:word:]] : "same as w" o [[:xdigit:]] : "hexadecimal digit" Groups: o (...) is a capturing group o (?:...) is a non-capturing group o \n is a backreference (where n is the number of the group, starting with 1) o $n is a reference from the replacement expression to a group in the match expression. And some other things: o \b denotes a word boundary, \B is not a word boundary. o ^ is the start of the string or line, $ the end. o | is "alternation", i.e. the "or". Comparison to other tools Most operations string supports can also be done by external tools. Some of these include grep, sed and cut. If you are familiar with these, it is useful to know how string differs from them. In contrast to these classics, string reads input either from stdin or as arguments. string also does not deal with files, so it requires redirections to be used with them. In contrast to grep, strings match defaults to glob-mode, while replace defaults to literal matching. If set to regex-mode, they use PCRE regu- lar expressions, which is comparable to greps -P option. match defaults to printing just the match, which is like grep with -o (use --entire to enable grep-like behavior). Like seds s/ command, string replace still prints strings that don't match. seds -n in combination with a /p modifier or command is like string replace -f. string split somedelimiter is a replacement for tr somedelimiter \\n. string-collect - join strings into one Synopsis string collect [(-N | --no-trim-newlines)] [STRING...] Description string collect collects its input into a single output argument, with- out splitting the output when used in a command substitution. This is useful when trying to collect multiline output from another command into a variable. Exit status: 0 if any output argument is non-empty, or 1 otherwise. If invoked with multiple arguments instead of input, string collect preserves each argument separately, where the number of output argu- ments is equal to the number of arguments given to string collect. Any trailing newlines on the input are trimmed, just as with "$(cmd)" substitution in sh. --no-trim-newlines can be used to disable this be- havior, which may be useful when running a command such as set contents (cat filename | string collect -N). Examples >_ echo \"(echo one\ntwo\nthree | string collect)\" "one two three " >_ echo \"(echo one\ntwo\nthree | string collect -N)\" "one two three" string-escape - escape special characters Synopsis string escape [(-n | --no-quoted)] [--style=xxx] [STRING...] string unescape [--style=xxx] [STRING...] Description string escape escapes each STRING in one of three ways. The first is --style=script. This is the default. It alters the string such that it can be passed back to eval to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If -n or --no-quoted is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise. --style=var ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded. --style=url ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded. --style=regex escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded. string unescape performs the inverse of the string escape command. If the string to be unescaped is not properly formatted it is ignored. For example, doing string unescape --style=var (string escape --style=var $str) will return the original string. There is no support for unescap- ing --style=regex. Examples >_ echo \\x07 | string escape cg >_ string escape --style=var 'a1 b2'\\u6161 a1_20b2__c_E6_85_A1 string-join - join strings with delimiter Synopsis string join [(-q | --quiet)] SEP [STRING...] string join0 [(-q | --quiet)] [STRING...] Description string join joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise. string join0 joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as sort -z. Exit status: 0 if at least one join was performed, or 1 otherwise. Examples >_ seq 3 | string join ... 1...2...3 string-join0 - join strings with zero bytes Synopsis string join [(-q | --quiet)] SEP [STRING...] string join0 [(-q | --quiet)] [STRING...] Description string join joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise. string join0 joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as sort -z. Exit status: 0 if at least one join was performed, or 1 otherwise. Examples >_ seq 3 | string join ... 1...2...3 string-length - print string lengths Synopsis string length [(-q | --quiet)] [STRING...] Description string length reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 other- wise. Examples >_ string length 'hello, world' 12 >_ set str foo >_ string length -q $str; echo $status 0 # Equivalent to test -n $str string-lower - convert strings to lowercase Synopsis string lower [(-q | --quiet)] [STRING...] Description string lower converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the -q flag you can readily test whether a string is already lowercase. string-match - match substrings Synopsis string match [(-a | --all)] [(-e | --entire)] [(-i | --ignore-case)] [(-r | --regex)] [(-n | --index)] [(-q | --quiet)] [(-v | --invert)] PATTERN [STRING...] Description string match tests each STRING against PATTERN and prints matching sub- strings. Only the first match for each STRING is reported unless -a or --all is given, in which case all matches are reported. If you specify the -e or --entire then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to grep without the -o flag). You can, obviously, achieve the same re- sult by prepending and appending * or .* depending on whether or not you have specified the --regex flag. The --entire flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the string match clearer. Without --entire and --regex, a PATTERN will need to match the entire STRING before it will be re- ported. Matching can be made case-insensitive with --ignore-case or -i. If --index or -n is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING. If --regex or -r is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the STRING will be reported, unless --entire is given. If --invert or -v is used the selected lines will be only those which do not match the given glob pattern or regular expression. Exit status: 0 if at least one match was found, or 1 otherwise. Examples Match Glob Examples >_ string match '?' a a >_ string match 'a*b' axxb axxb >_ string match -i 'a??B' Axxb Axxb >_ echo 'ok?' | string match '*\\?' ok? # Note that only the second STRING will match here. >_ string match 'foo' 'foo1' 'foo' 'foo2' foo >_ string match -e 'foo' 'foo1' 'foo' 'foo2' foo1 foo foo2 >_ string match 'foo?' 'foo1' 'foo' 'foo2' foo1 foo foo2 Match Regex Examples >_ string match -r 'cat|dog|fish' 'nice dog' dog >_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4) dog1 dog2 cat3 dog3 cat4 dog4 >_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56 2:34:56 2 34 56 >_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur papa pa murmur mur >_ string match -r -a -n at ratatat 2 2 4 2 6 2 >_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;' 0xBadC0de string-repeat - multiply a string Synopsis string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [(-N | --no-newline)] [(-q | --quiet)] [STRING...] Description string repeat repeats the STRING -n or --count times. The -m or --max option will limit the number of outputted char (excluding the newline). This option can be used by itself or in conjunction with --count. If both --count and --max are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both --count and --max will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If -N or --no-newline is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise. Examples Repeat Examples >_ string repeat -n 2 'foo ' foo foo >_ echo foo | string repeat -n 2 foofoo >_ string repeat -n 2 -m 5 'foo' foofo >_ string repeat -m 5 'foo' foofo string-replace - replace substrings Synopsis string replace [(-a | --all)] [(-f | --filter)] [(-i | --ignore-case)] [(-r | --regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...] Description string replace is similar to string match but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched. If -r or --regex is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape se- quences like \t as well as references to capturing groups by number or name as $n or ${n}. If you specify the -f or --filter flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: a_cmd | string match pattern | string replace pattern new_pattern. You can instead just write a_cmd | string replace --filter pattern new_pattern. Exit status: 0 if at least one replacement was performed, or 1 other- wise. Examples Replace Literal Examples >_ string replace is was 'blue is my favorite' blue was my favorite >_ string replace 3rd last 1st 2nd 3rd 1st 2nd last >_ string replace -a ' ' _ 'spaces to underscores' spaces_to_underscores Replace Regex Examples >_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x' 0 3.14 5 >_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right' right left $ >_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here' put a here string-split - split strings by delimiter Synopsis string split [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] SEP [STRING...] string split0 [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] [STRING...] Description string split splits each STRING on the separator SEP, which can be an empty string. If -m or --max is specified, at most MAX splits are done on each STRING. If -r or --right is given, splitting is performed right-to-left. This is useful in combination with -m or --max. With -n or --no-empty, empty results are excluded from consideration (e.g. hello\n\nworld would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise. See also read --delimiter. string split0 splits each STRING on the zero byte (NUL). Options are the same as string split except that no separator is given. split0 has the important property that its output is not further split when used in a command substitution, allowing for the command substitu- tion to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as find -print0 or sort -z. See split0 examples below. Examples >_ string split . example.com example com >_ string split -r -m1 / /usr/local/bin/fish /usr/local/bin fish >_ string split '' abc a b c NUL Delimited Examples >_ # Count files in a directory, without being confused by newlines. >_ count (find . -print0 | string split0) 42 >_ # Sort a list of elements which may contain newlines >_ set foo beta alpha\\ngamma >_ set foo (string join0 $foo | sort -z | string split0) >_ string escape $foo[1] alpha\\ngamma string-split0 - split on zero bytes Synopsis string split [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] SEP [STRING...] string split0 [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] [STRING...] Description string split splits each STRING on the separator SEP, which can be an empty string. If -m or --max is specified, at most MAX splits are done on each STRING. If -r or --right is given, splitting is performed right-to-left. This is useful in combination with -m or --max. With -n or --no-empty, empty results are excluded from consideration (e.g. hello\n\nworld would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise. See also read --delimiter. string split0 splits each STRING on the zero byte (NUL). Options are the same as string split except that no separator is given. split0 has the important property that its output is not further split when used in a command substitution, allowing for the command substitu- tion to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as find -print0 or sort -z. See split0 examples below. Examples >_ string split . example.com example com >_ string split -r -m1 / /usr/local/bin/fish /usr/local/bin fish >_ string split '' abc a b c NUL Delimited Examples >_ # Count files in a directory, without being confused by newlines. >_ count (find . -print0 | string split0) 42 >_ # Sort a list of elements which may contain newlines >_ set foo beta alpha\\ngamma >_ set foo (string join0 $foo | sort -z | string split0) >_ string escape $foo[1] alpha\\ngamma string-sub - extract substrings Synopsis string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)] [STRING...] Description string sub prints a substring of each string argument. The start of the substring can be specified with -s or --start followed by a 1-based in- dex value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be speci- fied with -l or --length. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise. Examples >_ string sub --length 2 abcde ab >_ string sub -s 2 -l 2 abcde bc >_ string sub --start=-2 abcde de string-trim - remove trailing whitespace Synopsis string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...] Description string trim removes leading and trailing whitespace from each STRING. If -l or --left is given, only leading whitespace is removed. If -r or --right is given, only trailing whitespace is trimmed. The -c or --chars switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise. Examples >_ string trim ' abc ' abc >_ string trim --right --chars=yz xyzzy zany x zan string-unescape - expand escape sequences Synopsis string escape [(-n | --no-quoted)] [--style=xxx] [STRING...] string unescape [--style=xxx] [STRING...] Description string escape escapes each STRING in one of three ways. The first is --style=script. This is the default. It alters the string such that it can be passed back to eval to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If -n or --no-quoted is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise. --style=var ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded. --style=url ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded. --style=regex escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded. string unescape performs the inverse of the string escape command. If the string to be unescaped is not properly formatted it is ignored. For example, doing string unescape --style=var (string escape --style=var $str) will return the original string. There is no support for unescap- ing --style=regex. Examples >_ echo \\x07 | string escape cg >_ string escape --style=var 'a1 b2'\\u6161 a1_20b2__c_E6_85_A1 string-upper - convert strings to uppercase Synopsis string upper [(-q | --quiet)] [STRING...] Description string upper converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the -q flag you can readily test whether a string is already uppercase. suspend - suspend the current shell Synopsis suspend [--force] Description suspend suspends execution of the current shell by sending it a SIGTSTP signal, returning to the controlling process. It can be resumed later by sending it a SIGCONT. In order to prevent suspending a shell that doesn't have a controlling process, it will not suspend the shell if it is a login shell. This requirement is bypassed if the --force option is given or the shell is not interactive. switch - conditionally execute a block of commands Synopsis switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end Description switch performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. case is used together with the switch statement in order to determine which block should be executed. Each case command is given one or more parameters. The first case com- mand with a parameter that matches the string specified in the switch command will be evaluated. case parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expan- sion using filenames. Note that fish does not fall through on case statements. Only the first matching case is executed. Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. Example If the variable $animal contains the name of an animal, the following code would attempt to classify it: switch $animal case cat echo evil case wolf dog human moose dolphin whale echo mammal case duck goose albatross echo bird case shark trout stingray echo fish case '*' echo I have no idea what a $animal is end If the above code was run with $animal set to whale, the output would be mammal. test - perform tests on files and text Synopsis test [EXPRESSION] [ [EXPRESSION] ] Description Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments. The first form (test) is preferred. For compatibility with other shells, the second form is available: a matching pair of square brack- ets ([ [EXPRESSION ] ]). This test is mostly POSIX-compatible. When using a variable as an argument for a test operator you should al- most always enclose it in double-quotes. There are only two situations it is safe to omit the quote marks. The first is when the argument is a literal string with no whitespace or other characters special to the shell (e.g., semicolon). For example, test -b /my/file. The second is using a variable that expands to exactly one element including if that element is the empty string (e.g., set x ''). If the variable is not set, set but with no value, or set to more than one value you must en- close it in double-quotes. For example, test "$x" = "$y". Since it is always safe to enclose variables in double-quotes when used as test ar- guments that is the recommended practice. Operators for files and directories o -b FILE returns true if FILE is a block device. o -c FILE returns true if FILE is a character device. o -d FILE returns true if FILE is a directory. o -e FILE returns true if FILE exists. o -f FILE returns true if FILE is a regular file. o -g FILE returns true if FILE has the set-group-ID bit set. o -G FILE returns true if FILE exists and has the same group ID as the current user. o -k FILE returns true if FILE has the sticky bit set. If the OS does not support the concept it returns false. See https://en.wikipedia.org/wiki/Sticky_bit. o -L FILE returns true if FILE is a symbolic link. o -O FILE returns true if FILE exists and is owned by the current user. o -p FILE returns true if FILE is a named pipe. o -r FILE returns true if FILE is marked as readable. o -s FILE returns true if the size of FILE is greater than zero. o -S FILE returns true if FILE is a socket. o -t FD returns true if the file descriptor FD is a terminal (TTY). o -u FILE returns true if FILE has the set-user-ID bit set. o -w FILE returns true if FILE is marked as writable; note that this does not check if the filesystem is read-only. o -x FILE returns true if FILE is marked as executable. Operators for text strings o STRING1 = STRING2 returns true if the strings STRING1 and STRING2 are identical. o STRING1 != STRING2 returns true if the strings STRING1 and STRING2 are not identical. o -n STRING returns true if the length of STRING is non-zero. o -z STRING returns true if the length of STRING is zero. Operators to compare and examine numbers o NUM1 -eq NUM2 returns true if NUM1 and NUM2 are numerically equal. o NUM1 -ne NUM2 returns true if NUM1 and NUM2 are not numerically equal. o NUM1 -gt NUM2 returns true if NUM1 is greater than NUM2. o NUM1 -ge NUM2 returns true if NUM1 is greater than or equal to NUM2. o NUM1 -lt NUM2 returns true if NUM1 is less than NUM2. o NUM1 -le NUM2 returns true if NUM1 is less than or equal to NUM2. Both integers and floating point numbers are supported. Operators to combine expressions o COND1 -a COND2 returns true if both COND1 and COND2 are true. o COND1 -o COND2 returns true if either COND1 or COND2 are true. Expressions can be inverted using the ! operator: o ! EXPRESSION returns true if EXPRESSION is false, and false if EX- PRESSION is true. Expressions can be grouped using parentheses. o ( EXPRESSION ) returns the value of EXPRESSION. Note that parentheses will usually require escaping with \( to avoid being interpreted as a command substitution. Examples If the /tmp directory exists, copy the /etc/motd file to it: if test -d /tmp cp /etc/motd /tmp/motd end If the variable MANPATH is defined and not empty, print the contents. (If MANPATH is not defined, then it will expand to zero arguments, un- less quoted.) if test -n "$MANPATH" echo $MANPATH end Parentheses and the -o and -a operators can be combined to produce more complicated expressions. In this example, success is printed if there is a /foo or /bar file as well as a /baz or /bat file. if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \) echo Success. end. Numerical comparisons will simply fail if one of the operands is not a number: if test 42 -eq "The answer to life, the universe and everything" echo So long and thanks for all the fish # will not be executed end A common comparison is with $status: if test $status -eq 0 echo "Previous command succeeded" end The previous test can likewise be inverted: if test ! $status -eq 0 echo "Previous command failed" end which is logically equivalent to the following: if test $status -ne 0 echo "Previous command failed" end Standards test implements a subset of the IEEE Std 1003.1-2008 (POSIX.1) stan- dard. The following exceptions apply: o The < and > operators for comparing strings are not implemented. o Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the test utility in another shell. In cases such as this, one can use command test to explicitly use the system's standalone test rather than this builtin test. time - measure how long a command or block takes Synopsis time COMMAND Description time causes fish to measure how long a command takes and print the re- sults afterwards. The command can be a simple fish command or a block. The results can not currently be redirected. For checking timing after a command has completed, check $CMD_DURATION. Your system most likely also has a time command. To use that use some- thing like command time, as in command time sleep 10. Because it's not inside fish, it won't have access to fish functions and won't be able to time blocks and such. Example (for obvious reasons exact results will vary on your system) >_ time sleep 1s ________________________________________________________ Executed in 1,01 secs fish external usr time 2,32 millis 0,00 micros 2,32 millis sys time 0,88 millis 877,00 micros 0,00 millis >_ time for i in 1 2 3; sleep 1s; end ________________________________________________________ Executed in 3,01 secs fish external usr time 9,16 millis 2,94 millis 6,23 millis sys time 0,23 millis 0,00 millis 0,23 millis trap - perform an action when the shell receives a signal Synopsis trap [OPTIONS] [[ARG] REASON ... ] Description trap is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an event handler. The following parameters are available: o ARG is the command to be executed on signal delivery. o REASON is the name of the event to trap. For example, a signal like INT or SIGINT, or the special symbol EXIT. o -l or --list-signals prints a list of signal names. o -p or --print prints all defined signal handlers. If ARG and REASON are both specified, ARG is the command to be executed when the event specified by REASON occurs (e.g., the signal is deliv- ered). If ARG is absent (and there is a single REASON) or -, each specified signal is reset to its original disposition (the value it had upon en- trance to the shell). If ARG is the null string the signal specified by each REASON is ignored by the shell and by the commands it invokes. If ARG is not present and -p has been supplied, then the trap commands associated with each REASON are displayed. If no arguments are supplied or if only -p is given, trap prints the list of commands associated with each signal. Signal names are case insensitive and the SIG prefix is optional. The exit status is 1 if any REASON is invalid; otherwise trap returns 0. Example trap "status --print-stack-trace" SIGUSR1 # Prints a stack trace each time the SIGUSR1 signal is sent to the shell. true - return a successful result Synopsis true Description true sets the exit status to 0. See Also o false command o $status variable type - indicate how a command would be interpreted Synopsis type [OPTIONS] NAME [NAME ...] Description With no options, type indicates how each NAME would be interpreted if used as a command name. The following options are available: o -a or --all prints all of possible definitions of the specified names. o -s or --short suppresses function expansion when used with no options or with -a/--all. o -f or --no-functions suppresses function and builtin lookup. o -t or --type prints function, builtin, or file if NAME is a shell function, builtin, or disk file, respectively. o -p or --path prints the path to NAME if NAME resolves to an exe- cutable file in $PATH, the path to the script containing the defini- tion of the function NAME if NAME resolves to a function loaded from a file on disk (i.e. not interactively defined at the prompt), or nothing otherwise. o -P or --force-path returns the path to the executable file NAME, pre- suming NAME is found in $PATH, or nothing otherwise. --force-path ex- plicitly resolves only the path to executable files in $PATH, regard- less of whether $NAME is shadowed by a function or builtin with the same name. o -q or --quiet suppresses all output; this is useful when testing the exit status. The -q, -p, -t and -P flags (and their long flag aliases) are mutually exclusive. Only one can be specified at a time. Example >_ type fg fg is a builtin ulimit - set or get resource usage limits Synopsis ulimit [OPTIONS] [LIMIT] Description ulimit builtin sets or outputs the resource usage limits of the shell and any processes spawned by it. If a new limit value is omitted, the current value of the limit of the resource is printed; otherwise, the specified limit is set to the new value. Use one of the following switches to specify which resource limit to set or report: o -c or --core-size: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled. o -d or --data-size: the maximum size of a process' data segment. o -f or --file-size: the maximum size of files created by the shell. o -l or --lock-size: the maximum size that may be locked into memory. o -m or --resident-set-size: the maximum resident set size. o -n or --file-descriptor-count: the maximum number of open file de- scriptors (most systems do not allow this value to be set). o -s or --stack-size: the maximum stack size. o -t or --cpu-time: the maximum amount of CPU time in seconds. o -u or --process-count: the maximum number of processes available to a single user. o -v or --virtual-memory-size The maximum amount of virtual memory available to the shell. Note that not all these limits are available in all operating systems. The value of limit can be a number in the unit specified for the re- source or one of the special values hard, soft, or unlimited, which stand for the current hard limit, the current soft limit, and no limit, respectively. If limit is given, it is the new value of the specified resource. If no option is given, then -f is assumed. Values are in kilobytes, except for -t, which is in seconds and -n and -u, which are unscaled values. The exit status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit. ulimit also accepts the following switches that determine what type of limit to set: o -H or --hard sets hard resource limit o -S or --soft sets soft resource limit A hard limit can only be decreased. Once it is set it cannot be in- creased; a soft limit may be increased up to the value of the hard limit. If neither -H nor -S is specified, both the soft and hard limits are updated when assigning a new limit value, and the soft limit is used when reporting the current value. The following additional options are also understood by ulimit: o -a or --all prints all current limits The fish implementation of ulimit should behave identically to the im- plementation in bash, except for these differences: o Fish ulimit supports GNU-style long options for all switches o Fish ulimit does not support the -p option for getting the pipe size. The bash implementation consists of a compile-time check that empiri- cally guesses this number by writing to a pipe and waiting for SIG- PIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish. o Fish ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch Example ulimit -Hs 64 sets the hard stack size limit to 64 kB. umask - set or get the file creation mode mask Synopsis umask [OPTIONS] [MASK] Description umask displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files. The umask may be expressed either as an octal number, which represents the rights that will be removed by default, or symbolically, which rep- resents the only rights that will be granted by default. Access rights are explained in the manual page for the chmod(1) pro- gram. With no parameters, the current file creation mode mask is printed as an octal number. o -h or --help prints this message. o -S or --symbolic prints the umask in symbolic form instead of octal form. o -p or --as-command outputs the umask in a form that may be reused as input If a numeric mask is specified as a parameter, the current shell's umask will be set to that value, and the rights specified by that mask will be removed from new files and directories by default. If a symbolic mask is specified, the desired permission bits, and not the inverse, should be specified. A symbolic mask is a comma separated list of rights. Each right consists of three parts: o The first part specifies to whom this set of right applies, and can be one of u, g, o or a, where u specifies the user who owns the file, g specifies the group owner of the file, o specific other users rights and a specifies all three should be changed. o The second part of a right specifies the mode, and can be one of =, + or -, where = specifies that the rights should be set to the new value, + specifies that the specified right should be added to those previously specified and - specifies that the specified rights should be removed from those previously specified. o The third part of a right specifies what rights should be changed and can be any combination of r, w and x, representing read, write and execute rights. If the first and second parts are skipped, they are assumed to be a and =, respectively. As an example, r,u+w means all users should have read access and the file owner should also have write access. Note that symbolic masks currently do not work as intended. Example umask 177 or umask u=rw sets the file creation mask to read and write for the owner and no permissions at all for any other users. vared - interactively edit the value of an environment variable Synopsis vared VARIABLE_NAME Description vared is used to interactively edit the value of an environment vari- able. Array variables as a whole can not be edited using vared, but in- dividual list elements can. Example vared PATH[3] edits the third element of the PATH list wait - wait for jobs to complete Synopsis wait [-n | --any] [PID | PROCESS_NAME] ... Description wait waits for child jobs to complete. o If a pid is specified, the command waits for the job that the process with the pid belongs to. o If a process name is specified, the command waits for the jobs that the matched processes belong to. o If neither a pid nor a process name is specified, the command waits for all background jobs. o If the -n / --any flag is provided, the command returns as soon as the first job completes. If it is not provided, it returns after all jobs complete. Example sleep 10 & wait $last_pid spawns sleep in the background, and then waits until it finishes. for i in (seq 1 5); sleep 10 &; end wait spawns five jobs in the background, and then waits until all of them finishes. for i in (seq 1 5); sleep 10 &; end hoge & wait sleep spawns five jobs and hoge in the background, and then waits until all sleeps finish, and doesn't wait for hoge finishing. while - perform a command multiple times Synopsis while CONDITION; COMMANDS...; end Description while repeatedly executes CONDITION, and if the exit status is 0, then executes COMMANDS. The exit status of the while loop is the exit status of the last itera- tion of the COMMANDS executed, or 0 if none were executed. (This matches other shells and is POSIX-compatible.) You can use and or or for complex conditions. Even more complex control can be achieved with while true containing a break. Example while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end # outputs 'file exists' at 10 second intervals as long as the file foo.txt or bar.txt exists. DESIGN 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: 1. Everything that can be done in other shell languages should be pos- sible to do in fish, though fish may rely on external commands in doing so. 2. Fish should be user friendly, but not at the expense of expressive- ness. Most tradeoffs between power and ease of use can be avoided with careful design. 3. Whenever possible without breaking the above goals, fish should fol- low the Posix syntax. To achieve these high-level goals, the fish design relies on a number of more specific design principles. These are presented below, together with a rationale and a few examples for each. 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 source code, making the pro- gram harder to maintain and update. Examples: o Here documents are too similar to using echo inside of a pipeline. o Subshells, command substitution and process substitution are strongly related. fish only supports command substitution, the others can be achieved either using a block or the psub shellscript function. o Having both aliases and functions is confusing, especially since both of them have limitations and problems. fish functions have none of the drawbacks of either syntax. o The many Posix quoting styles are silly, especially $''. The law of responsiveness The shell should attempt to remain responsive to the user at all times, even in the face of contended or unresponsive filesystems. It is only acceptable to block in response to a user initiated action, such as running a command. Rationale: Bad performance increases user-facing complexity, because it trains users to recognize and route around slow use cases. It is also incredibly frustrating. Examples: o Features like syntax highlighting and autosuggestions must perform all of their disk I/O asynchronously. o Startup should minimize forks and disk I/O, so that fish can be started even if the system is under load. 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 failure 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 im- ply assumptions about the code which change when reimplementing the code, causing issues with backwards compatibility. But mostly, configu- ration 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: o 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. o Fish does not allow you to set the number of history entries, differ- ent language substyles or any number of other common shell configura- tion 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 de- fault. Both zsh and bash support command-specific completions, but no such completions are shipped with bash by default, and they are turned off by default in zsh. Other features that zsh supports that are dis- abled by default include tab-completion of strings containing wild- cards, a sane completion pager and a history file. The law of user focus When designing a program, one should first think about how to make an intuitive and powerful program. Implementation issues should only be considered once a user interface has been designed. Rationale: This design rule is different than the others, since it describes how one should go about designing new features, not what the features should be. The problem with focusing on what can be done, and what is easy to do, is that too much of the implementation is exposed. This means that the user must know a great deal about the underlying system to be able to guess how the shell works, it also means that the lan- guage will often be rather low-level. Examples: - There should only be one type of input to the shell, lists of commands. Loops, conditionals and variable assignments are all per- formed through regular commands. o The differences between built-in commands and shellscript functions should be made as small as possible. Built-ins and shellscript func- tions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipe- line, and should support any I/O redirection. o 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. o All blocks end with the end built-in. The law of discoverability A program should be designed to make its features as easy as possible to discover for the user. Rationale: A program whose features are discoverable turns a new user into an expert in a shorter span of time, since the user will become an expert on the program simply by using it. The main benefit of a graphical program over a command-line-based pro- gram is discoverability. In a graphical program, one can discover all the common features by simply looking at the user interface and guess- ing what the different buttons, menus and other widgets do. The tradi- tional way to discover features in command-line programs is through manual pages. This requires both that the user starts to use a differ- ent program, and then they remember the new information until the next time they use the same program. Examples: - Everything should be tab-completable, and every tab comple- tion should have a description. o Every syntax error and error in a built-in 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 high- lighter. o The help manual should be easy to read, easily available from the shell, complete and contain many examples o The language should be uniform, so that once the user understands the command/argument syntax, they will know the whole language, and be able to use tab-completion to discover new features. TUTORIAL Why fish? fish is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. fish supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure. If you want to make your command line more productive, more useful, and more fun, without learning a bunch of arcane syntax and configuration options, then fish might be just what you're looking for! Getting started Once installed, just type in fish into your current shell to try it out! You will be greeted by the standard fish prompt, which means you are all set up and can start using fish: > fish Welcome to fish, the friendly interactive shell Type help for instructions on how to use fish you@hostname ~> This prompt that you see above is the fish default prompt: it shows your username, hostname, and working directory. - to change this prompt see how to change your prompt - to switch to fish permanently see switch your default shell to fish. From now on, we'll pretend your prompt is just a '>' to save space. Learning fish This tutorial assumes a basic understanding of command line shells and Unix commands, and that you have a working copy of fish. If you have a strong understanding of other shells, and want to know what fish does differently, search for the magic phrase unlike other shells, which is used to call out important differences. Running Commands fish runs commands like other shells: you type a command, followed by its arguments. Spaces are separators: > echo hello world hello world This runs the command echo with the arguments hello and world. You can include a literal space in an argument with a backslash, or by using single or double quotes: > mkdir My\ Files > cp ~/Some\ File 'My Files' > ls "My Files" Some File Commands can be chained with semicolons. Getting Help fish has excellent help and man pages. Run help to open help in a web browser, and man to open it in a man page. You can also ask for help with a specific command, for example, help set to open in a web browser, or man set to see it in the terminal. > man set set - handle shell variables Synopsis... Syntax Highlighting You'll quickly notice that fish performs syntax highlighting as you type. Invalid commands are colored red by default > /bin/mkd A command may be invalid because it does not exist, or refers to a file that you cannot execute. When the command becomes valid, it is shown in a different color: > /bin/mkdir fish will underline valid file paths as you type them > cat ~/somefi This tells you that there exists a file that starts with 'somefi', which is useful feedback as you type. These colors, and many more, can be changed by running fish_config, or by modifying variables directly. Wildcards fish supports the familiar wildcard *. To list all JPEG files: > ls *.jpg lena.jpg meena.jpg santa maria.jpg You can include multiple wildcards: > ls l*.p* lena.png lesson.pdf Especially powerful is the recursive wildcard ** which searches direc- tories recursively: > ls /var/**.log /var/log/system.log /var/run/sntp.log If that directory traversal is taking a long time, you can Control+C out of it. Pipes and Redirections You can pipe between commands with the usual vertical bar: > echo hello world | wc 1 2 12 stdin and stdout can be redirected via the familiar _ and _. stderr is redirected with a 2_. > grep fish < /etc/shells > ~/output.txt 2> ~/errors.txt To redirect stdout and stderr into one file, you need to first redirect stdout, and then stderr into stdout: > make > make_output.txt 2>&1 Autosuggestions fish suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example > /bin/hostname It knows about paths and options _ grep --ignore-case And history too. Type a command once, and you can re-summon it by just typing a few letters > rsync -avze ssh . myname@somel- onghost.com:/some/long/path/doo/dee/doo/dee/doo To accept the autosuggestion, hit ^a (right arrow) or Control+F. To ac- cept a single word of the autosuggestion, Alt+^a (right arrow). If the autosuggestion is not what you want, just ignore it. Tab Completions fish comes with a rich set of tab completions, that work "out of the box." Press Tab, and fish will attempt to complete the command, argument, or path > /pri Tab => /private/ If there's more than one possibility, it will list them > ~/stuff/s Tab ~/stuff/script.sh (Executable, 4.8kB) ~/stuff/sources/ (Directory) Hit tab again to cycle through the possibilities. fish can also complete many commands, like git branches: > git merge pr :kbd:`Tab` => git merge prompt_designer > git checkout b :kbd:`Tab` builtin_list_io_merge (Branch) builtin_set_color (Branch) busted_events (Tag) Try hitting tab and see what fish can do! Variables Like other shells, a dollar sign performs variable substitution: > echo My home directory is $HOME My home directory is /home/tutorial Variable substitution also happens in double quotes, but not single quotes: > echo "My current directory is $PWD" My current directory is /home/tutorial > echo 'My current directory is $PWD' My current directory is $PWD Unlike other shells, fish has no dedicated VARIABLE=VALUE syntax for setting variables. Instead it has an ordinary command: set, which takes a variable name, and then its value. > set name 'Mister Noodle' > echo $name Mister Noodle (Notice the quotes: without them, Mister and Noodle would have been separate arguments, and $name would have been made into a list of two elements.) Unlike other shells, variables are not further split after substitu- tion: > mkdir $name > ls Mister Noodle In bash, this would have created two directories "Mister" and "Noodle". In fish, it created only one: the variable had the value "Mister Noo- dle", so that is the argument that was passed to mkdir, spaces and all. Other shells use the term "arrays", rather than lists. You can erase (or "delete") a variable with -e or --erase > set -e MyVariable > env | grep MyVariable (no output) Exports (Shell Variables) Sometimes you need to have a variable available to an external command, often as a setting. For example many programs like git or man read the $PAGER variable to figure out your preferred pager (the program that lets you scroll text). Other variables used like this include $BROWSER, $LANG (to configure your language) and $PATH. You'll note these are written in ALLCAPS, but that's just a convention. To give a variable to an external command, it needs to be "exported". Unlike other shells, fish does not have an export command. Instead, a variable is exported via an option to set, either --export or just -x. > set -x MyVariable SomeValue > env | grep MyVariable MyVariable=SomeValue It can also be unexported with --unexport or -u. Lists The set command above used quotes to ensure that Mister Noodle was one argument. If it had been two arguments, then name would have been a list of length 2. In fact, all variables in fish are really lists, that can contain any number of values, or none at all. Some variables, like $PWD, only have one value. By convention, we talk about that variable's value, but we really mean its first (and only) value. Other variables, like $PATH, really do have multiple values. During variable expansion, the variable expands to become multiple arguments: > echo $PATH /usr/bin /bin /usr/sbin /sbin /usr/local/bin Variables whose name ends in "PATH" are automatically split on colons to become lists. They are joined using colons when exported to subcom- mands. This is for compatibility with other tools, which expect $PATH to use colons. You can also explicitly add this quirk to a variable with set --path, or remove it with set --unpath. Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop. Get the length of a list with count: > count $PATH 5 You can append (or prepend) to a list by setting the list to itself, with some additional arguments. Here we append /usr/local/bin to $PATH: > set PATH $PATH /usr/local/bin You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end: > echo $PATH /usr/bin /bin /usr/sbin /sbin /usr/local/bin > echo $PATH[1] /usr/bin > echo $PATH[-1] /usr/local/bin You can also access ranges of elements, known as "slices:" > echo $PATH[1..2] /usr/bin /bin > echo $PATH[-1..2] /usr/local/bin /sbin /usr/sbin /bin You can iterate over a list (or a slice) with a for loop: > for val in $PATH echo "entry: $val" end entry: /usr/bin/ entry: /bin entry: /usr/sbin entry: /sbin entry: /usr/local/bin Lists adjacent to other lists or strings are expanded as cartesian products unless quoted (see Variable expansion): > set a 1 2 3 > set 1 a b c > echo $a$1 1a 2a 3a 1b 2b 3b 1c 2c 3c > echo $a" banana" 1 banana 2 banana 3 banana > echo "$a banana" 1 2 3 banana This is similar to Brace expansion. Command Substitutions Command substitutions use the output of one command as an argument to another. Unlike other shells, fish does not use backticks `` for com- mand substitutions. Instead, it uses parentheses: > echo In (pwd), running (uname) In /home/tutorial, running FreeBSD A common idiom is to capture the output of a command in a variable: > set os (uname) > echo $os Linux Command substitutions are not expanded within quotes. Instead, you can temporarily close the quotes, add the command substitution, and reopen them, all in the same argument: > touch "testing_"(date +%s)".txt" > ls *.txt testing_1360099791.txt Unlike other shells, fish does not split command substitutions on any whitespace (like spaces or tabs), only newlines. This can be an issue with commands like pkg-config that print what is meant to be multiple arguments on a single line. To split it on spaces too, use string split. > printf '%s\n' (pkg-config --libs gio-2.0) -lgio-2.0 -lgobject-2.0 -lglib-2.0 > printf '%s\n' (pkg-config --libs gio-2.0 | string split " ") -lgio-2.0 -lgobject-2.0 -lglib-2.0 Separating Commands (Semicolon) Like other shells, fish allows multiple commands either on separate lines or the same line. To write them on the same line, use the semicolon (";"). That means the following two examples are equivalent: echo fish; echo chips # or echo fish echo chips Exit Status When a command exits, it returns a status code as a natural number. This indicates how the command fared - 0 usually means success, while the others signify kinds of failure. For instance fish's set --query returns the number of variables it queried that weren't set - set --query PATH usually returns 0, set --query arglbargl boogagoogoo usu- ally returns 2. Unlike other shells, fish stores the exit status of the last command in $status instead of $?. > false > echo $status 1 This indicates how the command fared - 0 usually means success, while the others signify kinds of failure. For instance fish's set --query returns the number of variables it queried that weren't set - set --query PATH usually returns 0, set --query arglbargl boogagoogoo usu- ally returns 2. There is also a $pipestatus list variable for the exit statuses [1] of processes in a pipe. [1] or "stati" if you prefer, or "statA<<s" if you've time-travelled from ancient Rome or work as a latin teacher Combiners (And, Or, Not) fish supports the familiar && and || to combine commands, and ! to negate them: > ./configure && make && sudo make install Here, make is only executed if ./configure succeeds (returns 0), and sudo make install is only executed if both ./configure and make suc- ceed. fish also supports and, or, and not. The first two are job modifiers and have lower precedence. Example usage: > cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt ; and echo "Backup successful"; or echo "Backup failed" Backup failed As mentioned in the section on the semicolon, this can also be written in multiple lines, like so: cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt and echo "Backup successful" or echo "Backup failed" Conditionals (If, Else, Switch) Use if, else if, and else to conditionally execute code, based on the exit status of a command. if grep fish /etc/shells echo Found fish else if grep bash /etc/shells echo Found bash else echo Got nothing end To compare strings or numbers or check file properties (whether a file exists or is writeable and such), use test, like if test "$fish" = "flounder" echo FLOUNDER end # or if test "$number" -gt 5 echo $number is greater than five else echo $number is five or less end # or if test -e /etc/hosts # is true if the path /etc/hosts exists - it could be a file or directory or symlink (or possibly something else). echo We most likely have a hosts file else echo We do not have a hosts file end Combiners can also be used to make more complex conditions, like if grep fish /etc/shells; and command -sq fish echo fish is installed and configured end For even more complex conditions, use begin and end to group parts of them. There is also a switch command: switch (uname) case Linux echo Hi Tux! case Darwin echo Hi Hexley! case FreeBSD NetBSD DragonFly echo Hi Beastie! case '*' echo Hi, stranger! end Note that case does not fall through, and can accept multiple arguments or (quoted) wildcards. Functions A fish function is a list of commands, which may optionally take argu- ments. Unlike other shells, arguments are not passed in "numbered vari- ables" like $1, but instead in a single list $argv. To create a func- tion, use the function builtin: > function say_hello echo Hello $argv end > say_hello Hello > say_hello everybody! Hello everybody! Unlike other shells, fish does not have aliases or special prompt syn- tax. Functions take their place. You can list the names of all functions with the functions keyword (note the plural!). fish starts out with a number of functions: > functions alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, trap, type, umask, up-or-search, vared You can see the source for any function by passing its name to func- tions: > functions ls function ls --description 'List contents of directory' command ls -G $argv end Loops While loops: > while true echo "Loop forever" end Loop forever Loop forever Loop forever ... # yes, this really will loop forever. Unless you abort it with ctrl-c. For loops can be used to iterate over a list. For example, a list of files: > for file in *.txt cp $file $file.bak end Iterating over a list of numbers can be done with seq: > for x in (seq 5) touch file_$x.txt end Prompt Unlike other shells, there is no prompt variable like PS1. To display your prompt, fish executes a function with the name fish_prompt, and its output is used as the prompt. You can define your own prompt: > function fish_prompt echo "New Prompt % " end New Prompt % Multiple lines are OK. Colors can be set via set_color, passing it named ANSI colors, or hex RGB values: > function fish_prompt set_color purple date "+%m/%d/%y" set_color FF0 echo (pwd) '>' (set_color normal) end will look like 02/06/13 /home/tutorial > You can choose among some sample prompts by running fish_config prompt. fish also supports RPROMPT through fish_right_prompt. $PATH $PATH is an environment variable containing the directories that fish searches for commands. Unlike other shells, $PATH is a list, not a colon-delimited string. To prepend /usr/local/bin and /usr/sbin to $PATH, you can write: > set PATH /usr/local/bin /usr/sbin $PATH To remove /usr/local/bin from $PATH, you can write: > set PATH (string match -v /usr/local/bin $PATH) For compatibility with other shells and external commands, $PATH is a path variable, and so will be joined with colons (not spaces) when you quote it: > echo "$PATH" /usr/local/sbin:/usr/local/bin:/usr/bin and it will be exported like that, and when fish starts it splits the $PATH it receives into a list on colon. You can do so directly in config.fish, like you might do in other shells with .profile. See this example. A faster way is to modify the $fish_user_paths universal variable, which is automatically prepended to $PATH. For example, to permanently add /usr/local/bin to your $PATH, you could write: > set -U fish_user_paths /usr/local/bin $fish_user_paths The advantage is that you don't have to go mucking around in files: just run this once at the command line, and it will affect the current session and all future instances too. (Note: you should NOT add this line to config.fish. If you do, the variable will get longer each time you run fish!) Startup (Where's .bashrc?) fish starts by executing commands in ~/.config/fish/config.fish. You can create it if it does not exist. It is possible to directly create functions and variables in con- fig.fish file, using the commands shown above. For example: > cat ~/.config/fish/config.fish set -x PATH $PATH /sbin/ function ll ls -lh $argv end However, it is more common and efficient to use autoloading functions and universal variables. If you want to organize your configuration, fish also reads commands in .fish files in ~/.config/fish/conf.d/. See initialization for the de- tails. Autoloading Functions When fish encounters a command, it attempts to autoload a function for that command, by looking for a file with the name of that command in ~/.config/fish/functions/. For example, if you wanted to have a function ll, you would add a text file ll.fish to ~/.config/fish/functions: > cat ~/.config/fish/functions/ll.fish function ll ls -lh $argv end This is the preferred way to define your prompt as well: > cat ~/.config/fish/functions/fish_prompt.fish function fish_prompt echo (pwd) "> " end See the documentation for funced and funcsave for ways to create these files automatically, and $fish_function_path to control their location. Universal Variables A universal variable is a variable whose value is shared across all in- stances of fish, now and in the future a even after a reboot. You can make a variable universal with set -U: > set -U EDITOR vim Now in another shell: > echo $EDITOR vim Switching to fish? If you wish to use fish (or any other shell) as your default shell, you need to enter your new shell's executable /usr/local/bin/fish in two places: - add /usr/local/bin/fish to /etc/shells - change your default shell with chsh -s /usr/local/bin/fish You can use the following commands for this: Add the fish shell /usr/local/bin/fish to /etc/shells with: > echo /usr/local/bin/fish | sudo tee -a /etc/shells Change your default shell to fish with: > chsh -s /usr/local/bin/fish (To change it back to another shell, just substitute /usr/lo- cal/bin/fish with /bin/bash, /bin/tcsh or /bin/zsh as appropriate in the steps above.) Ready for more? If you want to learn more about fish, there is lots of detailed docu- mentation, the official gitter channel, an official mailing list, and the github page. FREQUENTLY ASKED QUESTIONS How do I set or clear an environment variable? Use the set command: set -x key value set -e key Since fish 3.1 you can set an environment variable for just one command using the key=value some command syntax, like in other shells. The two lines below behave identically - unlike other shells, fish will output value both times: key=value echo $key begin; set -lx key value; echo $key; end How do I run a command every login? What's fish's equivalent to .bashrc or .profile? Edit the file ~/.config/fish/config.fish, creating it if it does not exist (Note the leading period). How do I set my prompt? The prompt is the output of the fish_prompt function. Put it in ~/.con- fig/fish/functions/fish_prompt.fish. For example, a simple prompt is: function fish_prompt set_color $fish_color_cwd echo -n (prompt_pwd) set_color normal echo -n ' > ' end You can also use the Web configuration tool, fish_config, to preview and choose from a gallery of sample prompts. How do I run a command from history? Type some part of the command, and then hit the ^a (up) or ^a (down) ar- row keys to navigate through history matches. Additional default key bindings include Control+P (up) and Control+N (down). How do I run a subcommand? The backtick doesn't work! fish uses parentheses for subcommands. For example: for i in (ls) echo $i end My command (pkg-config) gives its output as a single long string? Unlike other shells, fish splits command substitutions only on new- lines, not spaces or tabs or the characters in $IFS. That means if you run echo x(printf '%s ' a b c)x It will print xa b c x, because the "a b c " is used in one piece. But if you do echo x(printf '%s\n' a b c)x it will print xax xbx xcx. In the overwhelming majority of cases, splitting on spaces is unwanted, so this is an improvement. However sometimes, especially with pkg-config and related tools, split- ting on spaces is needed. In these cases use string split " " like: g++ example_01.cpp (pkg-config --cflags --libs gtk+-2.0 | string split " ") How do I get the exit status of a command? Use the $status variable. This replaces the $? variable used in some other shells. somecommand if test $status -eq 7 echo "That's my lucky number!" end If you are just interested in success or failure, you can run the com- mand directly as the if-condition: if somecommand echo "Command succeeded" else echo "Command failed" end Or if you just want to do one command in case the first succeeded or failed, use and or or: somecommand or someothercommand See the documentation for test and if for more information. How do I check whether a variable is defined? Use set -q var. For example, if set -q var; echo variable defined; end. To check multiple variables you can combine with and and or like so: if set -q var1; or set -q var2 echo either variable defined end Keep in mind that a defined variabled could also be empty, either by having no elements (if set like set var) or only empty elements (if set like set var ""). Read on for how to deal with those. How do I check whether a variable is not empty? Use string length -q -- $var. For example, if string length -q -- $var; echo not empty; end. Note that string length will interpret a list of multiple variables as a disjunction (meaning any/or): if string length -q -- $var1 $var2 $var3 echo at least one of these variables is not empty end Alternatively, use test -n "$var", but remember that the variable must be double-quoted. For example, if test -n "$var"; echo not empty; end. The test command provides its own and (-a) and or (-o): if test -n "$var1" -o -n "$var2" -o -n "$var3" echo at least one of these variables is not empty end If you want to know if a variable has no elements, use set -q var[1]. Why doesn't set -Ux (exported universal variables) seem to work? A global variable of the same name already exists. Environment variables such as EDITOR or TZ can be set universally using set -Ux. However, if there is an environment variable already set be- fore fish starts (such as by login scripts or system administrators), it is imported into fish as a global variable. The variable scopes are searched from the "inside out", which means that local variables are checked first, followed by global variables, and finally universal variables. This means that the global value takes precedence over the universal value. To avoid this problem, consider changing the setting which fish inher- its. If this is not possible, add a statement to your user initializa- tion file (usually ~/.config/fish/config.fish): set -gx EDITOR vim How do I customize my syntax highlighting colors? Use the web configuration tool, fish_config, or alter the fish_color family of environment variables. How do I update man page completions? Use the fish_update_completions command. I accidentally entered a directory path and fish changed directory. What happened? If fish is unable to locate a command with a given name, and it starts with '.', '/' or '~', fish will test if a directory of that name ex- ists. If it does, it is implicitly assumed that you want to change working directory. For example, the fastest way to switch to your home directory is to simply press ~ and enter. The open command doesn't work. The open command uses the MIME type database and the .desktop files used by Gnome and KDE to identify filetypes and default actions. If at least one of these environments is installed, but the open command is not working, this probably means that the relevant files are installed in a non-standard location. Consider asking for more help. How do I make fish my default shell? If you installed fish manually (e.g. by compiling it, not by using a package manager), you first need to add fish to the list of shells by executing the following command (assuming you installed fish in /usr/local): echo /usr/local/bin/fish | sudo tee -a /etc/shells If you installed a prepackaged version of fish, the package manager should have already done this for you. In order to change your default shell, type: chsh -s /usr/local/bin/fish You may need to adjust the above path to e.g. /usr/bin/fish. Use the command which fish if you are unsure of where fish is installed. Unfortunately, there is no way to make the changes take effect at once. You will need to log out and back in again. I'm seeing weird output before each prompt when using screen. What's wrong? Quick answer: Run the following command in fish: function fish_title; end; funcsave fish_title Problem solved! The long answer: Fish is trying to set the titlebar message of your terminal. While screen itself supports this feature, your terminal does not. Unfortu- nately, when the underlying terminal doesn't support setting the title- bar, screen simply passes through the escape codes and text to the un- derlying terminal instead of ignoring them. It is impossible to detect and resolve this problem from inside fish since fish has no way of knowing what the underlying terminal type is. For now, the only way to fix this is to unset the titlebar message, as suggested above. Note that fish has a default titlebar message, which will be used if the fish_title function is undefined. So simply unsetting the fish_ti- tle function will not work. How do I change the greeting message? Change the value of the variable fish_greeting or create a fish_greet- ing function. For example, to remove the greeting use: set fish_greeting Why doesn't history substitution ("!$" etc.) work? Because history substitution is an awkward interface that was invented before interactive line editing was even possible. Fish drops it in favor of perfecting the interactive history recall interface. Switch- ing requires a small change of habits: if you want to modify an old line/word, first recall it, then edit. E.g. don't type "sudo !!" - first press Up, then Home, then type "sudo ". Fish history recall is very simple yet effective: o As in any modern shell, the Up arrow, ^a recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like. o If the line you want is far back in the history, type any part of the line and then press Up one or more times. This will constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like. o Alt+^a,Up recalls individual arguments, starting from the last argu- ment in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like. An alternate key binding is Alt+.. o If the argument you want is far back in history (e.g. 2 lines back - that's a lot of words!), type any part of it and then press Alt+^a,Up. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient! o If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (Alt+D and Alt+Backspace are your friends). See documentation for more details about line editing in fish. How can I use - as a shortcut for cd -? In fish versions prior to 2.5.0 it was possible to create a function named - that would do cd -. Changes in the 2.5.0 release included sev- eral bug fixes that enforce the rule that a bare hyphen is not a valid function (or variable) name. However, you can achieve the same effect via an abbreviation: abbr -a -- - 'cd -' Uninstalling fish Should you wish to uninstall fish, first ensure fish is not set as your shell. Run chsh -s /bin/bash if you are not sure. Next, do the following (assuming fish was installed to /usr/local): rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish rm /usr/local/share/man/man1/fish*.1 cd /usr/local/bin rm -f fish fish_indent Unicode private-use characters reserved by fish Fish reserves the Unicode private-use character range from U+F600 thru U+F73F for internal use. Any attempt to feed characters in that range to fish will result in them being replaced by the Unicode "replacement character" U+FFFD. This includes both interactive input as well as any file read by fish (but not programs run by fish). Where can I find extra tools for fish? The fish user community extends fish in unique and useful ways via scripts that aren't always appropriate for bundling with the fish pack- age. Typically because they solve a niche problem unlikely to appeal to a broad audience. You can find those extensions, including prompts, themes and useful functions, in various third-party repositories. These include: o Fisher o Fundle o Oh My Fish o Tacklebox This is not an exhaustive list and the fish project has no opinion re- garding the merits of the repositories listed above or the scripts found therein. LICENSE fish Copyright A(C) 2005-2009 Axel Liljencrantz, 2009-2019 fish-shell contributors. fish is released under the GNU General Public License, version 2. fish includes other code licensed under the GNU General Public License, version 2, including GNU printf. Copyright A(C) 1990-2007 Free Software Foundation, Inc. Printf (from GNU Coreutils 6.9) is released under the GNU General Public License, version 2. The GNU General Public License agreement follows. GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. This General Pub- lic License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this ser- vice if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you dis- tribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free soft- ware. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program pro- prietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modifi- cation follow. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION o This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", be- low, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copy- right law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without lim- itation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Pro- gram is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicu- ously and appropriately publish on each copy an appropriate copy- right notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distrib- ute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: o You must cause the modified files to carry prominent notices stat- ing that you changed the files and the date of any change. o You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. o If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Excep- tion: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If iden- tifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in them- selves, then this License, and its terms, do not apply to those sec- tions when you distribute them as separate works. But when you dis- tribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or con- test your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Pro- gram with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may copy and distribute the Program (or a work based on it, un- der Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the follow- ing: o Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software inter- change; or, o Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete ma- chine-readable copy of the corresponding source code, to be dis- tributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, o Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is al- lowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to con- trol compilation and installation of the executable. However, as a special exception, the source code distributed need not include any- thing that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the oper- ating system on which the executable runs, unless that component it- self accompanies the executable. If distribution of executable or object code is made by offering ac- cess to copy from a designated place, then offering equivalent ac- cess to copy the source code from the same place counts as distribu- tion of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program ex- cept as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. How- ever, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Pro- gram), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further re- strictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent in- fringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a conse- quence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Pro- gram. If any portion of this section is held invalid or unenforceable un- der any particular circumstance, the balance of the section is in- tended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the in- tegrity of the free software distribution system, which is imple- mented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distrib- ute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in cer- tain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorpo- rates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Pro- gram specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version pub- lished by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free pro- grams whose distribution conditions are different, write to the au- thor to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WAR- RANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIM- ITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PER- FORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DE- FECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRIT- ING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CON- SEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. ---- License for PCRE2 fish contains code from the [PCRE2](http://www.pcre.org) library to support regular expressions. This code, created by Philip Hazel, is distributed under the terms of the BSD license. Copyright A(C) 1997-2015 University of Cambridge. The BSD license follows. Redistribution and use in source and binary forms, with or without mod- ification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright no- tice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distri- bution. o Neither the name of the University of Cambridge nor the names of any contributors may be used to endorse or promote products de- rived from this software without specific prior written permis- sion. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC- ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. AUTHOR fish-shell developers COPYRIGHT 2019, fish-shell developers 3.1 Mar 02, 2021 FISH-DOC(1)
NAME | INSTALLATION | STARTING AND EXITING | EXECUTING BASH | DEFAULT SHELL | UNINSTALLING | SHEBANG LINE | SOME COMMON WORDS | QUOTES | ESCAPING CHARACTERS | INPUT/OUTPUT REDIRECTION | PIPING | BACKGROUND JOBS | JOB CONTROL | FUNCTIONS | DEFINING ALIASES | AUTOLOADING FUNCTIONS | CONDITIONAL EXECUTION OF CODE AND FLOW CONTROL | PARAMETER EXPANSION (GLOBBING) | WILDCARDS | COMMAND SUBSTITUTION | BRACE EXPANSION | VARIABLE EXPANSION | CARTESIAN PRODUCTS | INDEX RANGE EXPANSION | HOME DIRECTORY EXPANSION | COMBINING DIFFERENT EXPANSIONS | SHELL VARIABLE AND FUNCTION NAMES | SHELL VARIABLES | VARIABLE SCOPE | OVERRIDING VARIABLES FOR A SINGLE COMMAND | MORE ON UNIVERSAL VARIABLES | VARIABLE SCOPE FOR FUNCTIONS | EXPORTING VARIABLES | LISTS | PATH VARIABLES | SPECIAL VARIABLES | THE STATUS VARIABLE | VARIABLES FOR CHANGING HIGHLIGHTING COLORS | LOCALE VARIABLES | BUILTIN COMMANDS | HELP | AUTOSUGGESTIONS | TAB COMPLETION | WRITING YOUR OWN COMPLETIONS | USEFUL FUNCTIONS FOR WRITING COMPLETIONS | WHERE TO PUT COMPLETIONS | SHARED BINDINGS | EMACS MODE COMMANDS | VI MODE COMMANDS | COMMAND MODE | INSERT MODE | VISUAL MODE | COPY AND PASTE (KILL RING) | SEARCHABLE HISTORY | MULTILINE EDITING | SYNTAX HIGHLIGHTING | PROGRAMMABLE TITLE | PROGRAMMABLE PROMPT | CONFIGURABLE GREETING | PRIVATE MODE | EVENT HANDLERS | DEBUGGING FISH SCRIPTS | COMMANDS | DESIGN | TUTORIAL | FREQUENTLY ASKED QUESTIONS | LICENSE | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fish-doc&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>