NAME

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.

Fish is used by giving commands in the fish language, see The Fish Language for information on that.

HELP

Fish also has man pages for its commands, and translates the help pages to man pages. 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.

This page can be viewed via help index (or just help) or man fish-doc. The tutorial can be viewed with help tutorial or man fish-tutorial.

AUTOSUGGESTIONS

To accept the autosuggestion (replacing the command line contents), press → or Control+F. To accept the first suggested word, press Alt+→ 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 efficient technique for navigating through directory hierarchies.

TAB COMPLETION

The pager can be navigated with the arrow keys, Page Up / Page Down, Tab or Shift+Tab. Pressing Control+S (the pager-toggle-search binding - / in vi-mode) opens up a search menu that you can use to filter the list.

Fish provides some general purpose completions:

It also provides a large number of program specific scripted completions. Most of these completions are simple options like the -l option for ls, but some are more advanced. For example:

You can also write your own completions or install some you got from someone else. For that, see Writing your own completions.

SYNTAX HIGHLIGHTING

Detected errors include:

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 variables listed in the Variables for changing highlighting colors section.

set fish_color_error red --bold

set fish_pager_color_background --background=white

set fish_pager_color_prefix black
set fish_pager_color_completion black
set fish_pager_color_description black
set fish_pager_color_background --background=white
set fish_pager_color_secondary_background --background=brwhite

ABBREVIATIONS

abbr -a gco git checkout

After entering gco and pressing Space or Enter, the full text git checkout will appear in the command line.

This is an alternative to aliases, and has the advantage that you see the actual command before using it, and the actual command will be stored in history.

PROGRAMMABLE TITLE

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

CONFIGURABLE GREETING

PRIVATE MODE

You can also launch with fish --private (or fish -P for short). This both hides old history and prevents writing history to disk. This is useful to avoid leaking personal information (e.g. for screencasts) or when dealing with sensitive information.

You can query the variable fish_private_mode (if test -n "$fish_private_mode" ...) if you would like to respect the user's wish for privacy and alter the behavior of your own fish scripts.

COMMAND LINE EDITOR

Like bash and other shells, fish includes two sets of keyboard shortcuts (or key bindings): one inspired by the Emacs text editor, and one by the Vi text editor. The default editing mode is Emacs. You can switch to Vi mode by running 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 the fish_key_bindings variable to its name. For example:

function fish_hybrid_key_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 fish_hybrid_key_bindings

While the key bindings included with fish include many of the shortcuts popular from the respective text editors, they are not a complete implementation. They include a shortcut to open the current command line in your preferred editor (Alt+E by default) if you need the full power of your editor.

SHARED BINDINGS

EMACS MODE COMMANDS

You can change these key bindings using the bind builtin.

VI MODE COMMANDS

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
    # Then execute the vi-bindings so they take precedence when there's a conflict.
    # Without --no-erase fish_vi_key_bindings will default to
    # resetting all bindings.
    # The argument specifies the initial mode (insert, "default" or visual).
    fish_vi_key_bindings --no-erase insert
end

When in vi-mode, the fish_mode_prompt function will display a mode indicator 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/functions/fish_mode_prompt.fish. (Bindings that change the mode are supposed 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 parameters to set a blinking cursor in the specified shape.

If the cursor shape does not appear to be changing after setting the above variables, it's likely your terminal emulator does not support the capabilities necessary to do this. It may also be the case, however, that fish_vi_cursor has not detected your terminal's features correctly (for example, if you are using tmux). If this is the case, you can force fish_vi_cursor to set the cursor shape by setting $fish_vi_force_cursor in config.fish. You'll have to restart fish for any changes to take effect. If cursor shape setting remains broken after this, it's almost certainly an issue with your terminal emulator, and not fish.

CUSTOM BINDINGS

# Just clear the commandline on control-c
bind \cc 'commandline -r ""'

Put bind statements into config.fish or a function called fish_user_key_bindings.

The key sequence (the \cc) here depends on your setup, in particular the terminal. To find out what the terminal sends use fish_key_reader:

> fish_key_reader # pressing control-c
Press a key:
            hex:    3  char: \cC
Press [ctrl-C] again to exit
bind \cC 'do something'
> fish_key_reader # pressing the right-arrow
Press a key:
            hex:   1B  char: \c[  (or \e)
(  0.077 ms)  hex:   5B  char: [
(  0.037 ms)  hex:   43  char: C
bind \e\[C 'do something'

Note that some key combinations are indistinguishable or unbindable. For instance control-i is the same as the tab key. This is a terminal limitation that fish can't do anything about.

Also, Escape is the same thing as Alt in a terminal. To distinguish between pressing Escape and then another key, and pressing Alt and that key (or an escape sequence the key sends), fish waits for a certain time after seeing an escape character. This is configurable via the fish_escape_delay_ms variable.

If you want to be able to press Escape and then a character and have it count as Alt+that character, set it to a higher value, e.g.:

set -g fish_escape_delay_ms 100

COPY AND PASTE (KILL RING)

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 [1]) 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 result can be used as a single token simply by closing the quote after. Kill ring entries are stored in fish_killring variable.

[1]

These rely on external tools. Currently xsel, xclip, wl-copy/wl-paste and pbcopy/pbpaste are supported.

MULTILINE EDITING

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 arrow keys and other such keyboard shortcuts.

SEARCHABLE COMMAND HISTORY

By pressing Alt+↑ and Alt+↓, a history search is also performed, but instead of searching for a complete commandline, each commandline is broken into separate elements just like it would be before execution, and the history is searched for an element matching that under the cursor.

History searches are case-insensitive unless the search string contains an uppercase character. You can stop a search to edit your search string by pressing Esc or Page Down.

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_history (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>_history file); both before starting the shell and while the shell is running.

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+↑ to search for previously typed words containing 'm'.

NAVIGATING DIRECTORIES

DIRECTORY HISTORY

Several commands are provided to interact with this directory history:

DIRECTORY STACK

AUTHOR

COPYRIGHT