mirror of
https://github.com/fish-shell/fish-shell
synced 2025-01-13 21:44:16 +00:00
README.md: rearrange and rewrite
Closes #2062
(cherry picked from commit 1183505695)
This commit is contained in:
David Adam
parent
e892c51b9c
commit
f3142a7d91
1 changed files with 125 additions and 64 deletions
189
README.md
189
README.md
|
|
@ -1,7 +1,9 @@
|
|||
[fish](https://fishshell.com/) - the friendly interactive shell [](https://travis-ci.org/fish-shell/fish-shell)
|
||||
================================================
|
||||
|
||||
fish is a smart and user-friendly command line shell for OS X, 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.
|
||||
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.
|
||||
|
||||
For more on fish's design philosophy, see the [design document](https://fishshell.com/docs/current/design.html).
|
||||
|
||||
|
|
@ -11,77 +13,87 @@ fish generally works like other shells, like bash or zsh. A few important differ
|
|||
|
||||
Detailed user documentation is available by running `help` within fish, and also at <https://fishshell.com/docs/current/index.html>
|
||||
|
||||
## Building
|
||||
## 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/)
|
||||
|
||||
### 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%3Arelease%3A2&package=fish).
|
||||
|
||||
Packages for Ubuntu are available from the [fish
|
||||
PPA](https://launchpad.net/~fish-shell/+archive/ubuntu/release-2), and can be installed using the
|
||||
following commands:
|
||||
|
||||
```
|
||||
sudo apt-add-repository ppa:fish-shell/release-2
|
||||
sudo apt-get update
|
||||
sudo apt-get install fish
|
||||
```
|
||||
|
||||
Instructions for other distributions may be found at [fishshell.com](https://fishshell.com).
|
||||
|
||||
### Windows
|
||||
|
||||
fish can be installed using [Cygwin](https://cygwin.com/) Setup (under the **Shells** category).
|
||||
|
||||
fish can be installed into Windows Services for Linux using the instructions under *Packages for
|
||||
Linux* for the appropriate image (eg Ubuntu).
|
||||
|
||||
### 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 *Building* section for instructions.
|
||||
|
||||
## Running fish
|
||||
|
||||
Once installed, run `fish` from your current shell to try fish out!
|
||||
|
||||
### Dependencies
|
||||
|
||||
Compiling fish requires:
|
||||
Running fish requires:
|
||||
|
||||
* a C++11 compiler. It builds successfully with g++ 4.8 or later, or with clang 3.3 or later. fish can be built using autotools or Xcode. autoconf 2.60 or later, as well as automake 1.13 or later, are required to build from git versions, but these are not required to build from the officially released tarballs.
|
||||
* the headers and libraries of a curses implementation such as ncurses.
|
||||
* gettext, for translation support.
|
||||
* Doxygen 1.8.7 or newer, for building the documentation.
|
||||
|
||||
At runtime, fish requires:
|
||||
|
||||
* a curses implementation such as ncurses (which should provide the `tput` command).
|
||||
* gettext, if you need the localizations.
|
||||
* PCRE2, due to the regular expression support contained in the `string` builtin. A copy is included with the source code, and will be used automatically if it does not already exist on your system.
|
||||
* a curses implementation such as ncurses (libraries and the `tput` command)
|
||||
* PCRE2 library - a copy is included with fish
|
||||
* gettext (library and `gettext` command), if compiled with translation support
|
||||
* basic system utilities including `basename`, `cat`, `cut`, `date`, `dircolors`, `dirname`, `ls`,
|
||||
`mkdir`, `mkfifo`, `mktemp`, `rm`, `seq`, `sort`, `stat`, `stty`, `tail`, `tr`, `tty`, `uname`,
|
||||
`uniq`, `wc`, and `whoami`
|
||||
* a number of common UNIX utilities:
|
||||
* an awk implementation, such as gawk, mawk, etc
|
||||
* coreutils --- at least basename, cat, cut, date, dircolors, dirname, ls, mkdir, mkfifo, mktemp, rm, seq, sort, stat, stty, tail, tr, tty, uname, uniq, wc, whoami
|
||||
* find
|
||||
* grep
|
||||
* hostname
|
||||
* kill
|
||||
* ps
|
||||
* sed
|
||||
* bc, the "basic calculator" program.
|
||||
* `awk`
|
||||
* `bc`, the "basic calculator" program
|
||||
* `find`
|
||||
* `grep`
|
||||
* `hostname`
|
||||
* `kill`
|
||||
* `ps`
|
||||
* `sed`
|
||||
|
||||
Optional functionality should degrade gracefully. (If fish ever threw a syntax error or a core dump due to missing dependencies for an optional feature, it would be a bug in fish and should be reported on our GitHub.) Optional features and dependencies include:
|
||||
The following optional features also have specific requirements:
|
||||
|
||||
* dynamically generating usage tips for builtin functions, which requires man, apropos, nroff, and ul.
|
||||
* manual page parsing for auto-completion for external commands, which also requires the above man tools, plus Python 2.6+ or Python 3.3+. Python 2 will also need the backports.lzma package; Python 3.3+ should include the required module by default.
|
||||
* the web configuration tool, which requires Python 2.6+ or 3.3+.
|
||||
* the fish_clipboard_* functions (bound to \cv and \cx), which require xsel or pbcopy/pbpaste.
|
||||
* builtin commands that have the `--help` option or print usage messages require `nroff` and
|
||||
`ul` (manual page formatters) to do so
|
||||
* completion generation from manual pages requires Python 2.7, 3.3 or greater, and possibly the
|
||||
`backports.lzma` module for Python 2.7
|
||||
* the `fish_config` Web configuration tool requires Python 2.7, 3.3 or greater, and a web browser
|
||||
* system clipboard integration (with the default Ctrl-V and Ctrl-X bindings) require either the
|
||||
`xsel` or `pbcopy`/`pbpaste` utilities
|
||||
* prompts which support showing VCS information (Git, Mercurial or Subversion) require these
|
||||
utilities
|
||||
|
||||
fish can also show VCS information in the prompt, when the current working directory is in a VCS-tracked project, with support for Git, Mercurial, and Subversion. This is one of the weakest dependencies, though: if you don't use git, for example, you don't need git information in the prompt, and if you do use git, you already have it. Similarly, fish comes with a variety of auto-completion scripts to help with command-line usage of a variety of applications; these scripts call the application in question, but you should only need these applications if you use them.
|
||||
|
||||
### Autotools Build
|
||||
|
||||
autoreconf --no-recursive [if building from Git]
|
||||
./configure
|
||||
make [gmake on BSD]
|
||||
sudo make install [sudo gmake install on BSD]
|
||||
|
||||
### Xcode Development Build
|
||||
|
||||
* Build the `base` target in Xcode
|
||||
* Run the fish executable, for example, in `DerivedData/fish/Build/Products/Debug/base/bin/fish`
|
||||
|
||||
### Xcode Build and Install
|
||||
|
||||
xcodebuild install
|
||||
sudo ditto /tmp/fish.dst /
|
||||
sudo make install-doc
|
||||
|
||||
## Help, it didn't build!
|
||||
|
||||
If fish reports that it could not find curses, try installing a curses development package and build again.
|
||||
|
||||
On Debian or Ubuntu you want:
|
||||
|
||||
sudo apt-get install build-essential ncurses-dev libncurses5-dev gettext autoconf
|
||||
|
||||
On RedHat, CentOS, or Amazon EC2:
|
||||
|
||||
sudo yum install ncurses-devel
|
||||
|
||||
## Packages for Linux
|
||||
|
||||
Instructions on how to find builds for several Linux distros are at <https://github.com/fish-shell/fish-shell/wiki/Nightly-builds>
|
||||
|
||||
## Switching to fish
|
||||
### Switching to fish
|
||||
|
||||
If you wish to use fish as your default shell, use the following command:
|
||||
|
||||
|
|
@ -101,6 +113,55 @@ Substitute /bin/bash with /bin/tcsh or /bin/zsh as appropriate.
|
|||
|
||||
You may need to logout/login for the change (chsh) to take effect.
|
||||
|
||||
## Building
|
||||
|
||||
### Dependencies
|
||||
|
||||
Compiling fish requires:
|
||||
|
||||
* a C++11 compiler (g++ 4.8 or later, or clang 3.3 or later)
|
||||
* either GNU Make (all platforms) or Xcode (macOS only)
|
||||
* a curses implementation such as ncurses (headers and libraries)
|
||||
* PCRE2 (headers and libraries) - a copy is included with fish
|
||||
* gettext (headers and libraries) - optional, for translation support
|
||||
|
||||
Compiling from git (that is, not a released tarball) also requires:
|
||||
|
||||
* either Xcode (macOS only) or the following Autotools utilities (all platforms):
|
||||
* autoconf 2.60 or later
|
||||
* automake 1.13 or later
|
||||
* Doxygen (1.8.7 or later) - optional, for documentation
|
||||
|
||||
### Autotools Build
|
||||
|
||||
autoreconf --no-recursive [if building from Git]
|
||||
./configure
|
||||
make [gmake on BSD]
|
||||
sudo make install [sudo gmake install on BSD]
|
||||
|
||||
### Xcode Development Build
|
||||
|
||||
* Build the `base` target in Xcode
|
||||
* Run the fish executable, for example, in `DerivedData/fish/Build/Products/Debug/base/bin/fish`
|
||||
|
||||
### Xcode Build and Install
|
||||
|
||||
xcodebuild install
|
||||
sudo ditto /tmp/fish.dst /
|
||||
sudo make install-doc
|
||||
|
||||
### Help, it didn't build!
|
||||
|
||||
If fish reports that it could not find curses, try installing a curses development package and build again.
|
||||
|
||||
On Debian or Ubuntu you want:
|
||||
|
||||
sudo apt-get install build-essential ncurses-dev libncurses5-dev gettext autoconf
|
||||
|
||||
On RedHat, CentOS, or Amazon EC2:
|
||||
|
||||
sudo yum install ncurses-devel
|
||||
|
||||
## Contributing Changes to the Code
|
||||
|
||||
See the [Guide for Developers](CONTRIBUTING.md).
|
||||
|
|
|
|||
Loading…
Reference in a new issue