2019-03-14 13:52:25 -07:00
.. highlight :: fish-docs-samples
2019-03-31 11:32:40 +02:00
.. _intro:
2018-12-15 16:23:36 -08:00
2018-12-15 18:45:16 -08:00
Introduction
2021-03-03 20:30:35 +01:00
***** ***** **
2018-12-15 16:23:36 -08:00
2021-11-05 16:50:19 -07:00
This is the documentation for :command: `fish` , the **f** \ riendly **i** \ nteractive **sh** \ ell.
2019-02-24 15:46:10 -08:00
2020-12-26 14:45:48 -07:00
A shell is a program that helps you operate your computer by starting other programs. fish offers a command-line interface focused on usability and interactive use.
2019-12-09 20:44:57 +01:00
2019-09-11 12:16:19 +08:00
Some of the special features of fish are:
2019-02-24 15:46:10 -08:00
2021-03-03 20:30:35 +01:00
- **Extensive UI** : :ref: `Syntax highlighting <color>` , :ref: `autosuggestions` , :ref: `tab completion <tab-completion>` and selection lists that can be navigated and filtered.
2019-02-24 15:46:10 -08:00
2019-09-11 12:16:19 +08:00
- **No configuration needed** : fish is designed to be ready to use immediately, without requiring extensive configuration.
2019-02-24 15:46:10 -08:00
2021-02-05 19:50:05 +01:00
- **Easy scripting** : New :ref: `functions <syntax-function>` can be added on the fly. The syntax is easy to learn and use.
2019-02-24 15:46:10 -08:00
2021-03-03 20:30:35 +01:00
This page explains how to install and set up fish and where to get more information.
2021-10-23 17:13:36 +02:00
Where to go?
============
2021-05-18 22:51:28 +02:00
2021-03-03 20:30:35 +01:00
If this is your first time using fish, see the :ref: `tutorial <tutorial>` .
2019-02-24 15:46:10 -08:00
2021-01-22 16:23:09 +01:00
If you are already familiar with other shells like bash and want to see the scripting differences, see :ref: `Fish For Bash Users <fish_for_bash_users>` .
2021-03-03 20:30:35 +01:00
For a comprehensive overview of fish's scripting language, see :ref: `The Fish Language <language>` .
For information on using fish interactively, see :ref: `Interactive use <interactive>` .
2021-10-23 17:13:36 +02:00
If you need to install fish first, read on, the rest of this document will tell you how to get, install and configure fish.
2021-11-05 16:50:19 -07:00
Installation
============
2019-02-24 15:46:10 -08:00
2021-11-05 16:50:19 -07:00
This section describes how to install, uninstall, start, and exit :command: `fish` . It also explains how to make fish the default shell.
2019-12-10 18:35:25 +01:00
2019-02-24 15:46:10 -08:00
Installation
------------
2019-09-11 12:18:27 +08:00
Up-to-date instructions for installing the latest version of fish are on the `fish homepage <https://fishshell.com/> `_ .
2019-02-24 15:46:10 -08:00
2020-12-26 14:45:48 -07:00
To install the development version of fish, see the instructions on the `project's GitHub page <https://github.com/fish-shell/fish-shell> `_ .
2019-02-24 15:46:10 -08:00
Starting and Exiting
--------------------
2019-09-11 12:18:27 +08:00
Once fish has been installed, open a terminal. If fish is not the default shell:
2019-02-24 15:46:10 -08:00
2021-11-05 16:50:19 -07:00
- Type :command: `fish` to start a shell::
2019-02-24 15:46:10 -08:00
> fish
2021-11-05 16:50:19 -07:00
- Type :command: `exit` to end the session::
2019-02-24 15:46:10 -08:00
> exit
2019-12-10 18:35:25 +01:00
Default Shell
-------------
2020-12-26 14:45:48 -07:00
To make fish your default shell:
2020-07-15 01:58:57 -04:00
2021-01-27 18:25:46 +01:00
- Add the line `` /usr/local/bin/fish `` to `` /etc/shells `` .
2020-12-26 14:45:48 -07:00
- Change your default shell with `` chsh -s /usr/local/bin/fish `` .
2019-12-10 18:35:25 +01:00
2020-07-15 01:58:57 -04:00
For detailed instructions see :ref: `Switching to fish <switching-to-fish>` .
2019-12-10 18:35:25 +01:00
Uninstalling
------------
For uninstalling fish: see :ref: `FAQ: Uninstalling fish <faq-uninstalling>` .
2019-12-10 18:29:57 +01:00
Shebang Line
------------
2020-12-26 14:45:48 -07:00
Because shell scripts are written in many different languages, they need to carry information about which interpreter should be used to execute them. For this, they are expected to have a first line, the shebang line, which names the interpreter executable.
2019-12-10 18:29:57 +01:00
2021-11-05 16:50:19 -07:00
A script written in :command: `bash` would need a first line like this:
2021-11-04 13:26:54 -07:00
::
2019-12-10 18:29:57 +01:00
#!/bin/bash
2021-01-27 16:58:12 +01:00
When the shell tells the kernel to execute the file, it will use the interpreter `` /bin/bash `` .
2019-12-10 18:29:57 +01:00
2021-01-27 16:58:12 +01:00
For a script written in another language, just replace `` /bin/bash `` with the interpreter for that language (for example: `` /usr/bin/python `` for a python script, or `` /usr/local/bin/fish `` for a fish script).
2019-12-10 18:29:57 +01:00
2020-12-26 14:45:48 -07:00
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 `` , a shebang is not required (but it doesn't hurt!).
2019-12-10 18:29:57 +01:00
2021-11-05 16:50:19 -07:00
Configuration
=============
2018-12-15 16:23:36 -08:00
2021-11-05 16:50:19 -07:00
To store configuration write it to a file called `` ~/.config/fish/config.fish `` .
2018-12-15 16:23:36 -08:00
2021-11-05 16:50:19 -07:00
`` .fish `` scripts in `` ~/.config/fish/conf.d/ `` are also automatically executed before `` config.fish `` .
2018-12-15 16:23:36 -08:00
2021-11-05 16:50:19 -07:00
These files are read on the startup of every shell, whether interactive and/or if they're login shells. Use `` status --is-interactive `` and `` status --is-login `` to discriminate.
2018-12-15 16:23:36 -08:00
Examples:
2021-11-05 16:50:19 -07:00
---------
2018-12-15 16:23:36 -08:00
2021-11-05 16:50:19 -07:00
To add `` ~/linux/bin `` to PATH variable when using a login shell, add this to `` ~/.config/fish/config.fish `` file::
2018-12-15 16:23:36 -08:00
2018-12-15 18:45:16 -08:00
if status --is-login
2021-02-01 18:12:24 +01:00
set -gx PATH $PATH ~/linux/bin
2018-12-15 18:45:16 -08:00
end
2018-12-15 16:23:36 -08:00
2021-11-12 07:42:31 +01:00
This is just an example; using :ref: `fish_add_path <cmd-fish_add_path>` e.g. `` fish_add_path ~/linux/bin `` which only adds the path if it isn't included yet is easier.
2018-12-15 16:23:36 -08:00
2021-11-05 16:50:19 -07:00
To run commands on exit, use an :ref: `event handler <event>` that is triggered by the exit of the shell::
2018-12-15 18:45:16 -08:00
function on_exit --on-event fish_exit
echo fish is now exiting
end
.. _more-help:
2021-11-05 16:50:19 -07:00
Resources
=========
2018-12-15 16:23:36 -08:00
2020-09-18 17:19:44 +02:00
- The `GitHub page <https://github.com/fish-shell/fish-shell/> `_
2018-12-15 16:23:36 -08:00
2020-09-18 17:19:44 +02:00
- The official `Gitter channel <https://gitter.im/fish-shell/fish-shell> `_
2018-12-15 16:23:36 -08:00
2020-09-18 17:19:44 +02:00
- The official mailing list at `fish-users@lists.sourceforge.net <https://lists.sourceforge.net/lists/listinfo/fish-users> `_
2018-12-15 16:23:36 -08:00
2020-09-18 17:19:44 +02:00
If you have an improvement for fish, you can submit it via the GitHub page.
2019-03-29 19:08:25 +01:00
.. _other_pages:
2021-07-14 16:57:22 +02:00
Other help pages
================
.. toctree ::
:maxdepth: 1
2022-01-12 21:42:16 +01:00
self
2021-07-14 16:57:22 +02:00
faq
interactive
language
commands
fish_for_bash_users
tutorial
completions
design
relnotes
license