2022-11-13 07:07:53 +08:00
.. |Cirrus CI| image :: https://api.cirrus-ci.com/github/fish-shell/fish-shell.svg?branch=master
:target: https://cirrus-ci.com/github/fish-shell/fish-shell
:alt: Cirrus CI Build Status
`fish <https://fishshell.com/> `__ - the friendly interactive shell |Build Status| |Cirrus CI|
2024-04-25 14:13:41 +08:00
=============================================================================================
2020-05-28 23:07:51 +08:00
fish is a smart and user-friendly command line shell for macOS, Linux,
and the rest of the family. fish includes features like syntax
highlighting, autosuggest-as-you-type, and fancy tab completions that
just work, with no configuration required.
2023-01-10 00:44:27 +08:00
For downloads, screenshots and more, go to https://fishshell.com/.
2020-05-28 23:07:51 +08:00
Quick Start
-----------
fish generally works like other shells, like bash or zsh. A few
important differences can be found at
https://fishshell.com/docs/current/tutorial.html by searching for the
magic phrase “unlike other shells”.
Detailed user documentation is available by running `` help `` within
fish, and also at https://fishshell.com/docs/current/index.html
Getting fish
------------
macOS
~~~~~
fish can be installed:
- using `Homebrew <http://brew.sh/> `__ : `` brew install fish ``
- using `MacPorts <https://www.macports.org/> `__ :
`` sudo port install fish ``
- using the `installer from fishshell.com <https://fishshell.com/> `__
- as a `standalone app from fishshell.com <https://fishshell.com/> `__
2022-06-02 01:38:15 +08:00
Note: The minimum supported macOS version is 10.10 "Yosemite".
2020-05-28 23:07:51 +08:00
Packages for Linux
~~~~~~~~~~~~~~~~~~
Packages for Debian, Fedora, openSUSE, and Red Hat Enterprise
Linux/CentOS are available from the `openSUSE Build
Service <https://software.opensuse.org/download.html?project=shells%3Afish&package=fish>`__.
Packages for Ubuntu are available from the `fish
PPA <https://launchpad.net/~fish-shell/+archive/ubuntu/release-3>`__,
and can be installed using the following commands:
::
sudo apt-add-repository ppa:fish-shell/release-3
2021-11-30 21:39:46 +08:00
sudo apt update
sudo apt install fish
2020-05-28 23:07:51 +08:00
Instructions for other distributions may be found at
`fishshell.com <https://fishshell.com> `__ .
Windows
~~~~~~~
2024-01-02 05:07:11 +08:00
- On Windows 10/11, fish can be installed under the WSL Windows Subsystem
2020-05-28 23:07:51 +08:00
for Linux with the instructions for the appropriate distribution
listed above under “Packages for Linux”, or from source with the
instructions below.
2024-11-06 23:22:26 +08:00
- fish (4.0 on and onwards) cannot be installed in Cygwin, due to a lack of Rust support.
2020-05-28 23:07:51 +08:00
Building from source
~~~~~~~~~~~~~~~~~~~~
If packages are not available for your platform, GPG-signed tarballs are
available from `fishshell.com <https://fishshell.com/> `__ and
`fish-shell on
GitHub <https://github.com/fish-shell/fish-shell/releases>`__. See the
2021-04-18 04:39:58 +08:00
`Building <#building> `__ section for instructions.
2020-05-28 23:07:51 +08:00
Running fish
------------
Once installed, run `` fish `` from your current shell to try fish out!
Dependencies
~~~~~~~~~~~~
Running fish requires:
2024-02-23 23:36:10 +08:00
- A terminfo database, typically from curses or ncurses (preinstalled on most \*nix systems) - this needs to be the directory tree format, not the "hashed" database.
If this is unavailable, fish uses an included xterm-256color definition.
2020-05-28 23:07:51 +08:00
- some common \*nix system utilities (currently `` mktemp `` ), in
addition to the basic POSIX utilities (`` cat `` , `` cut `` , `` dirname `` ,
2024-01-26 18:06:17 +08:00
`` file `` , `` ls `` , `` mkdir `` , `` mkfifo `` , `` rm `` , `` sort `` , `` tee `` , `` tr `` ,
2021-02-17 00:29:46 +08:00
`` uname `` and `` sed `` at least, but the full coreutils plus `` find `` and
`` awk `` is preferred)
2020-06-15 01:09:26 +08:00
- The gettext library, if compiled with
2020-05-28 23:07:51 +08:00
translation support
The following optional features also have specific requirements:
- builtin commands that have the `` --help `` option or print usage
2022-03-27 03:41:45 +08:00
messages require `` nroff `` or `` mandoc `` for
2020-05-28 23:07:51 +08:00
display
2020-09-16 15:57:10 +08:00
- automated completion generation from manual pages requires Python 3.5+
- the `` fish_config `` web configuration tool requires Python 3.5+ and a web browser
2020-05-28 23:07:51 +08:00
- system clipboard integration (with the default Ctrl-V and Ctrl-X
bindings) require either the `` xsel `` , `` xclip `` ,
`` wl-copy `` /`` wl-paste `` or `` pbcopy `` /`` pbpaste `` utilities
- full completions for `` yarn `` and `` npm `` require the
`` all-the-package-names `` NPM module
2021-11-16 21:42:01 +08:00
- `` colorls `` is used, if installed, to add color when running `` ls `` on platforms
that do not have color support (such as OpenBSD)
2020-05-28 23:07:51 +08:00
Building
--------
.. _dependencies-1:
Dependencies
~~~~~~~~~~~~
2024-12-02 03:09:28 +08:00
Compiling fish requires:
2020-05-28 23:07:51 +08:00
2024-11-06 23:22:26 +08:00
- Rust (version 1.70 or later)
2021-06-28 23:56:02 +08:00
- CMake (version 3.5 or later)
2024-11-06 23:22:26 +08:00
- a C compiler (for system feature detection and the test helper binary)
2022-07-03 09:46:44 +08:00
- PCRE2 (headers and libraries) - optional, this will be downloaded if missing
2020-05-28 23:07:51 +08:00
- gettext (headers and libraries) - optional, for translation support
2024-11-06 23:22:26 +08:00
- an Internet connection, as other dependencies will be downloaded automatically
2020-05-28 23:07:51 +08:00
Sphinx is also optionally required to build the documentation from a
cloned git repository.
2024-11-06 23:22:26 +08:00
Additionally, running the full test suite requires Python 3, tmux, and the pexpect package.
2023-07-15 16:56:28 +08:00
2024-12-02 03:09:28 +08:00
Building from source with CMake
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2020-05-28 23:07:51 +08:00
2024-12-11 08:04:00 +08:00
Rather than building from source, consider using a packaged build for your platform. Using the
steps below makes fish difficult to uninstall or upgrade. Release packages are available from the
links above, and up-to-date `development builds of fish are available for many platforms
<https://github.com/fish-shell/fish-shell/wiki/Development-builds> `__
2020-05-28 23:07:51 +08:00
To install into `` /usr/local `` , run:
.. code :: bash
mkdir build; cd build
cmake ..
2024-12-11 08:04:00 +08:00
cmake --build .
sudo cmake --install .
2020-05-28 23:07:51 +08:00
The install directory can be changed using the
`` -DCMAKE_INSTALL_PREFIX `` parameter for `` cmake `` .
2024-12-07 20:13:18 +08:00
CMake Build options
~~~~~~~~~~~~~~~~~~~
In addition to the normal CMake build options (like `` CMAKE_INSTALL_PREFIX `` ), fish's CMake build has some other options available to customize it.
- BUILD_DOCS=ON|OFF - whether to build the documentation. This is automatically set to OFF when Sphinx isn't installed.
- INSTALL_DOCS=ON|OFF - whether to install the docs. This is automatically set to on when BUILD_DOCS is or prebuilt documentation is available (like when building in-tree from a tarball).
- FISH_USE_SYSTEM_PCRE2=ON|OFF - whether to use an installed pcre2. This is normally autodetected.
- MAC_CODESIGN_ID=String|OFF - the codesign ID to use on Mac, or "OFF" to disable codesigning.
- WITH_GETTEXT=ON|OFF - whether to build with gettext support for translations.
- extra_functionsdir, extra_completionsdir and extra_confdir - to compile in an additional directory to be searched for functions, completions and configuration snippets
Building fish as self-installable (experimental)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2024-12-02 03:09:28 +08:00
You can also build fish as a self-installing binary.
2024-12-11 01:49:34 +08:00
This will include all the datafiles like the included functions or web configuration tool in the main `` fish `` binary.
2024-12-02 03:09:28 +08:00
2024-12-11 01:49:34 +08:00
On the first interactive run, and whenever it notices they are out of date, it will extract the datafiles to ~/.local/share/fish/install/ (currently, subject to change). You can do this manually by running `` fish --install `` (or `` fish --install=noconfirm `` to skip the confirmation).
2024-12-02 03:09:28 +08:00
2024-12-11 23:43:48 +08:00
To install fish as self-installable, just use `` cargo `` , like::
2024-12-02 03:09:28 +08:00
cargo install --path /path/to/fish # if you have a git clone
cargo install --git https://github.com/fish-shell/fish-shell --tag 4.0 # to build from git once 4.0 is released
cargo install --git https://github.com/fish-shell/fish-shell # to build the current development snapshot without cloning
2024-12-11 08:04:52 +08:00
This will place the binaries in `` ~/.cargo/bin/ `` , but you can place them wherever you want.
2024-12-02 03:09:28 +08:00
2024-12-11 08:04:15 +08:00
This build won't have the HTML docs (`` help `` will open the online version) or translations.
2024-12-02 03:09:28 +08:00
2024-12-11 23:43:48 +08:00
It requires sphinx by default, if sphinx-build is not available you can build without man pages by running it with $FISH_BUILD_DOCS set to 0::
FISH_BUILD_DOCS=0 cargo install --path .
2024-12-02 03:09:28 +08:00
You can also link it statically (but not against glibc) and move it to other computers.
2020-05-28 23:07:51 +08:00
Contributing Changes to the Code
--------------------------------
2020-05-28 23:10:21 +08:00
See the `Guide for Developers <CONTRIBUTING.rst> `__ .
2020-05-28 23:07:51 +08:00
Contact Us
----------
Questions, comments, rants and raves can be posted to the official fish
mailing list at https://lists.sourceforge.net/lists/listinfo/fish-users
2023-09-06 21:48:12 +08:00
or join us on our `matrix
channel <https://matrix.to/#/#fish-shell:matrix.org>`__. Or use the ` fish tag
2021-12-01 05:13:25 +08:00
on Unix & Linux Stackexchange <https://unix.stackexchange.com/questions/tagged/fish>`__.
There is also a fish tag on Stackoverflow, but it is typically a poor fit.
2020-05-28 23:07:51 +08:00
Found a bug? Have an awesome idea? Please `open an
issue <https://github.com/fish-shell/fish-shell/issues/new>`__.
2021-12-18 08:12:08 +08:00
.. |Build Status| image :: https://github.com/fish-shell/fish-shell/workflows/make%20test/badge.svg
2020-11-11 02:03:09 +08:00
:target: https://github.com/fish-shell/fish-shell/actions